add udf and json arrays

Author: Antony Bailey

README.md

@@ -40,6 +40,26 @@ Work with geospatial data to find points within a radius, bounding boxes, and di
 
 Integrate predictive models for forecasting and anomaly detection within queries.
 
+### 🔹 [JSON & Arrays](json_arrays.md)
+
+Filter and manipulate JSON fields and array data types.
+
+### 🔹 [User-defined Functions (UDFs)](user_defined_functions.md)
+
+Define and use custom functions to extend SQLY’s capabilities.
+
+### 🔹 [Performance Optimization](performance.md)
+
+Learn techniques to optimize query execution and improve efficiency.
+
+### 🔹 [Advanced Debugging](debugging.md)
+
+Enable query tracing, logging, and error handling for efficient debugging.
+
+### 🔹 [SQLY Extensions](extensions.md)
+
+Explore custom functions, external data sources, and event-driven triggers.
+
 ## 🚀 Getting Started
 
 To start using SQLY, check out the [Basics](basics.md) section and explore examples.

json_arrays.md

@@ -0,0 +1,91 @@
+# JSON & Arrays in SQLY
+
+## 📖 Introduction
+
+SQLY provides powerful support for querying and manipulating JSON data and array structures, enabling efficient handling of semi-structured data.
+
+---
+
+## 📦 Querying JSON Fields
+
+SQLY allows extracting and filtering data from JSON objects.
+
+### ✅ Example 1: Extract a JSON Field
+
+```yaml
+json_query:
+  select: [customer_id, profile.name]
+  from: customers
+  where:
+    profile.age: "> 30"
+```
+
+This extracts the `name` field from the `profile` JSON object and filters customers older than 30.
+
+### ✅ Example 2: Filter by a JSON Array Value
+
+```yaml
+json_query:
+  select: [order_id, items]
+  from: orders
+  where:
+    items[*].category: "electronics"
+```
+
+This retrieves orders containing items in the `electronics` category.
+
+---
+
+## 📑 Modifying JSON Data
+
+SQLY enables updates and modifications within JSON structures.
+
+### ✅ Example 3: Update a JSON Field
+
+```yaml
+json_modify:
+  update: customers
+  set:
+    profile.status: "VIP"
+  where:
+    customer_id: 123
+```
+
+This updates the `status` field inside the `profile` JSON object.
+
+---
+
+## 📂 Working with Arrays
+
+Arrays are supported for querying and filtering within SQLY.
+
+### ✅ Example 4: Check If a Value Exists in an Array
+
+```yaml
+array_query:
+  select: [user_id, roles]
+  from: users
+  where:
+    roles: contains("admin")
+```
+
+This retrieves users who have `admin` in their `roles` array.
+
+### ✅ Example 5: Unnest an Array
+
+```yaml
+array_query:
+  select: [user_id, unnest(permissions)]
+  from: users
+```
+
+This expands the `permissions` array into individual rows.
+
+---
+
+## 📌 Summary
+
+- Query JSON fields using dot notation.
+- Filter JSON arrays with wildcard `[*]`.
+- Modify JSON data using structured updates.
+- Work with arrays using `contains()` and `unnest()`.

user_defined_functions.md

@@ -0,0 +1,103 @@
+# User-defined Functions (UDFs) in SQLY
+
+## 📖 Introduction
+
+SQLY supports user-defined functions (UDFs) to extend its capabilities by creating reusable logic for queries.
+
+---
+
+## 🔧 Defining a User-defined Function
+
+Users can create custom functions with parameters and return types.
+
+### ✅ Example 1: Define a Simple Function
+
+```yaml
+udf:
+  name: calculate_tax
+  parameters:
+    - name: price
+      type: float
+    - name: tax_rate
+      type: float
+  return_type: float
+  body: |
+    return price * tax_rate
+```
+
+This defines a `calculate_tax` function to compute tax based on a given price and tax rate.
+
+---
+
+## 📌 Using UDFs in Queries
+
+UDFs can be called in SQLY queries to process data dynamically.
+
+### ✅ Example 2: Apply a UDF in a Query
+
+```yaml
+query:
+  select: [product_id, calculate_tax(price, 0.07)]
+  from: products
+```
+
+This applies the `calculate_tax` function to compute tax for each product dynamically.
+
+---
+
+## 🏗️ Advanced UDF Features
+
+SQLY supports advanced UDF capabilities, including conditional logic and iteration.
+
+### ✅ Example 3: UDF with Conditional Logic
+
+```yaml
+udf:
+  name: discount_price
+  parameters:
+    - name: price
+      type: float
+  return_type: float
+  body: |
+    if price > 100:
+      return price * 0.9
+    else:
+      return price
+```
+
+This function applies a discount for prices above 100.
+
+---
+
+## 🚀 Registering External Functions
+
+SQLY allows integration with external libraries or APIs within UDFs.
+
+### ✅ Example 4: Call an External API in a UDF
+
+```yaml
+udf:
+  name: get_exchange_rate
+  parameters:
+    - name: currency
+      type: string
+  return_type: float
+  external:
+    type: REST
+    endpoint: "https://api.exchangerate.com/latest"
+    method: GET
+    query_params:
+      base: "USD"
+      target: "currency"
+```
+
+This function fetches exchange rates from an external API.
+
+---
+
+## 📌 Summary
+
+- Define UDFs with parameters and return types.
+- Use UDFs dynamically in queries.
+- Implement conditional logic within functions.
+- Register external functions to call APIs or libraries.