[WIP] json query docs

content/guides/04.connect/3.query-parameters.md

@@ -40,10 +40,70 @@ Use native GraphQL queries.
 ::
 
 ::callout{icon="material-symbols:info-outline"}
-**Wildcards and performance**  
+**Wildcards and performance**
 While wildcards are very useful, we recommend only requesting specific fields in production. By only requesting the fields you need, you can speed up the request, and reduce the overall output size.
 ::
 
+### JSON Field Extraction
+
+Extract specific values from JSON fields using the `json()` function. This allows you to retrieve only the data you need from JSON columns without fetching the entire JSON object.
+
+**Syntax**: `json(field.path.to.value)`
+
+::code-group
+```http [REST]
+GET /items/products
+	?fields=id,name,json(metadata.color),json(metadata.dimensions.width)
+```
+
+```graphql [GraphQL]
+query {
+	products {
+		id
+		name
+		metadata_func {
+			color: json(path: "color")
+			width: json(path: "dimensions.width")
+		}
+	}
+}
+```
+
+```js [SDK]
+import { createDirectus, rest, readItems } from '@directus/sdk';
+const directus = createDirectus('https://directus.example.com').with(rest());
+
+const result = await directus.request(
+	readItems('products', {
+		fields: ['id', 'name', 'json(metadata.color)', 'json(metadata.dimensions.width)']
+	})
+);
+```
+::
+
+::callout{icon="material-symbols:info-outline"}
+**JSON Path Syntax**
+
+| Syntax                  | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `json(data.color)`      | Extract a top-level property from a JSON object                |
+| `json(data[0])`         | Extract the first element from a top-level JSON array          |
+| `json(data.items[0])`   | Extract the first element from a nested JSON array             |
+| `json(data.user.name)`  | Extract a nested property using dot notation                   |
+| `json(data.tags[2].id)` | Extract a property from an array element using mixed notation  |
+
+**Note**: The `json()` function can only be used with fields of type JSON. If the specified path doesn't exist in the JSON data, `null` will be returned.
+::
+
+::callout{icon="material-symbols:lightbulb-outline"}
+**Use Cases**
+
+- **Reduce payload size**: Fetch only specific properties from large JSON documents
+- **Improve performance**: Extract values at the database level rather than in application code
+- **Simplify queries**: Access nested data without client-side JSON parsing
+- **With relations**: Use `json()` on related items, e.g., `category.json(metadata.icon)`
+::
+
 ### Many to Any Fields
 
 As Many to Any (M2A) fields have nested data from multiple collections, you are not always able to fetch the same field from every related collection. In M2A fields, you can use the following syntax to specify what fields to fetch from which related nested collection type: `?fields=m2a-field:collection-scope.field`