Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
ComfortablyCoding
requested changes
Apr 22, 2026
Comment on lines
+637
to
+641
| ### The JSON Function | ||
|
|
||
| Extract a specific value from a JSON field and return it as a separate field in the response. See [Using the `json(field, path)` function](/guides/connect/json-queries#using-the-json-function) for full path syntax and examples. | ||
|
|
||
| This function cannot be used in `filter`. To filter on JSON values, use the [`_json` filter operator](/guides/connect/json-queries#filtering-with-_json) instead. |
Member
There was a problem hiding this comment.
Potentially better if we are more specific? 🤔
Suggested change
| ### The JSON Function | |
| Extract a specific value from a JSON field and return it as a separate field in the response. See [Using the `json(field, path)` function](/guides/connect/json-queries#using-the-json-function) for full path syntax and examples. | |
| This function cannot be used in `filter`. To filter on JSON values, use the [`_json` filter operator](/guides/connect/json-queries#filtering-with-_json) instead. | |
| ### Selecting JSON field values | |
| The [`json(field, path)` function](/guides/connect/json-queries#using-the-json-function) is used to retrieve a value from a specific path within a JSON document. The extracted value is returned as its own field in the query results, similar to other function outputs. | |
| Note that this function cannot be applied within a `filter`. If you need to filter based on JSON values, use the [`_json` filter operator](/guides/connect/json-queries#filtering-with-_json) instead. | |
| description: Quickstart for extracting and filtering values inside JSON fields with the json() function and _json filter operator. | ||
| --- | ||
|
|
||
| Directus gives you two ways of working with JSON fields in queries: |
Member
There was a problem hiding this comment.
Nit
Suggested change
| Directus gives you two ways of working with JSON fields in queries: | |
| Directus provides two ways of working with JSON documents in queries: |
|
|
||
| Directus gives you two ways of working with JSON fields in queries: | ||
|
|
||
| - **`json(field, path)`** extracts a value from a JSON document. Use it in `fields`, `sort`, and `alias`. |
Member
There was a problem hiding this comment.
Suggested change
| - **`json(field, path)`** extracts a value from a JSON document. Use it in `fields`, `sort`, and `alias`. | |
| - **`json(field, path)`**: A selection function to extract a value from a JSON document. It can be used in the `fields`, `sort`, and `alias` parameters. |
| Directus gives you two ways of working with JSON fields in queries: | ||
|
|
||
| - **`json(field, path)`** extracts a value from a JSON document. Use it in `fields`, `sort`, and `alias`. | ||
| - **`_json`** filters items by values inside a JSON document. Use it in `filter`. |
Member
There was a problem hiding this comment.
Suggested change
| - **`_json`** filters items by values inside a JSON document. Use it in `filter`. | |
| - **`_json`**: A filter operator that lets you filter records based on values within a JSON document. It can be used as part of the `filter` parameter. |
| ``` | ||
|
|
||
|
|
||
| The `_json` operator supports most filter operators, with the exception of itself, geometric, regex, and relational operators (`_json`, `_intersects`, `_intersects_bbox`, `_regex`, `_some`, and `_none`). |
Member
There was a problem hiding this comment.
This is worth a warning callout
Comment on lines
+171
to
+178
| The [JSON Queries Reference](/guides/connect/json-queries-reference) covers: | ||
|
|
||
| - Extracting multiple paths in one request | ||
| - Relational queries (M2O, O2M, M2A) | ||
| - Paths with dots or brackets in GraphQL | ||
| - Combining conditions with `_and` / `_or` | ||
| - Depth limits and SDK type safety | ||
| - Database-specific behavior (PostgreSQL, SQLite, MSSQL, Oracle) |
Member
There was a problem hiding this comment.
We can probably simplify this to
Suggested change
| The [JSON Queries Reference](/guides/connect/json-queries-reference) covers: | |
| - Extracting multiple paths in one request | |
| - Relational queries (M2O, O2M, M2A) | |
| - Paths with dots or brackets in GraphQL | |
| - Combining conditions with `_and` / `_or` | |
| - Depth limits and SDK type safety | |
| - Database-specific behavior (PostgreSQL, SQLite, MSSQL, Oracle) | |
| For advanced usage, expanded explanations etc, see [JSON Queries Reference](/guides/connect/json-queries-reference) |
Comment on lines
+7
to
+34
| This is the full reference for querying JSON fields in Directus. For a short introduction with basic syntax and examples, see [JSON Queries](/guides/connect/json-queries). | ||
|
|
||
| Directus provides two ways of working with JSON fields in queries: | ||
|
|
||
| - The **`json(field, path)` function** extracts a specific value from a JSON document. It can be used in the `fields`, `sort`, and `alias` query parameters. | ||
| - The **`_json` filter operator** filters items by values inside a JSON document without loading the full document. Use it in the `filter` query parameter. | ||
|
|
||
| Both use the same path notation and work across REST, GraphQL, and the SDK. | ||
|
|
||
| ## Path Notation | ||
|
|
||
| Paths use dot notation for object keys and bracket notation for array indices. | ||
|
|
||
| | Pattern | Example | Meaning | | ||
| |---|---|---| | ||
| | `key` | `color` | Top-level key | | ||
| | `a.b.c` | `settings.theme.color` | Nested keys | | ||
| | `[n]` | `tags[0]` | Array element at index `n` | | ||
| | `a[n].b` | `items[0].name` | Mixed object/array access | | ||
|
|
||
| **Examples:** | ||
|
|
||
| ``` | ||
| json(metadata, color) → top-level key | ||
| json(metadata, settings.theme) → nested object | ||
| json(data, items[0].name) → array element property | ||
| json(data, [0]) → first element of a top-level array | ||
| ``` |
Member
There was a problem hiding this comment.
This entire section is a repeat from basic. Thoughts on just linking to the relevant section on the basic page?
| json(data, [0]) → first element of a top-level array | ||
| ``` | ||
|
|
||
| The following path syntaxes are **not supported** and return an error in both the function and filter operator: |
Member
There was a problem hiding this comment.
Probably worth a heading for future linking
Member
There was a problem hiding this comment.
Quite a bit of repetitiveness in here, ideally we link where needed or just remove as we mention it on the basic which is expected to be read first as an intro.
Member
There was a problem hiding this comment.
Should we have a json top level and nest these 2 pages under them instead of 2 separate pages?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes PM-1228
Fixes #591