diff --git a/content/guides/02.content/1.explore.md b/content/guides/02.content/1.explore.md index 9428b03d..f165ee48 100644 --- a/content/guides/02.content/1.explore.md +++ b/content/guides/02.content/1.explore.md @@ -41,6 +41,39 @@ The following dynamic variables are built into Directus to add extra functionali :video-embed{video-id="a0f37f8b-c789-4421-b6c4-e4f681028d66"} +### Filtering JSON Fields + +You can filter on values stored inside JSON fields. When you select a JSON field in the filter field list, a **JSON** function entry appears beneath it. + +![The filter popup open on a collection page, with the field list showing a JSON function entry under the Metadata field](/img/json_filter.png) + +To filter on a JSON field: + +1. Click on :icon{name="material-symbols:filter-list"} at the top of the page and select the **JSON** function entry under a JSON field. +2. Enter the path to the value you want to filter on, using dot notation for object keys and bracket notation for array indices, for example `author.name` or `tags[0]`. +3. Select an operator and enter a value. + +![A JSON filter on the path author.name using the Starts with operator with the value Ja](/img/json_filter_startsWith.png) + +![A JSON filter on the array path tags[0] using the Equals operator with the value safety](/img/json_filter_arrayIndex.png) + +JSON stores typed values, so the value you enter is matched by type: + +- `4` is treated as the number `4`, and `true` as a boolean. +- Wrap a value in double quotes to force a string. For example, `"4"` matches the string `"4"` rather than the number `4`. +- String operators such as **Contains** and **Starts with** always treat the value as a string, so no quoting is needed. + +JSON filters can be combined with other filters, including in `AND` and `OR` groups, and support [dynamic variables](#dynamic-variables) in values. + +![An AND group combining a Title Contains filter with a JSON filter on the path rating](/img/json_filter_in_and_group.png) + +::callout{icon="i-lucide-triangle-alert" color="warning"} +**Not Available in Validation and Conditions** +JSON filters cannot be used in field validation rules or field conditions in the data model settings, as these are evaluated by a rule engine that does not support them. +:: + +JSON filters are saved as [`_json` filter rules](/guides/connect/json/quickstart). See [Advanced Querying](/guides/connect/json/advanced-querying) for the full path notation, supported operators, depth limits, and database-specific behavior. + ## Browsing Draft Versions When [content versioning](/guides/content/content-versioning) is enabled for a collection, a **Published/Draft** selector appears in the collection page header. Use it to switch between viewing published items and their draft versions. diff --git a/content/guides/04.connect/7.json/1.quickstart.md b/content/guides/04.connect/7.json/1.quickstart.md index 72c03bd3..9bafe6ec 100644 --- a/content/guides/04.connect/7.json/1.quickstart.md +++ b/content/guides/04.connect/7.json/1.quickstart.md @@ -11,6 +11,10 @@ Directus provides two ways of working with JSON fields in queries: Both use the same path notation and work across REST, GraphQL, and the SDK. +::callout{icon="i-lucide-info" color="info"} +JSON filtering is also available visually in the Studio filter UI. See [Filtering JSON Fields](/guides/content/explore#filtering-json-fields). +:: + ## Using the `json()` function **Function Syntax:** diff --git a/content/guides/04.connect/7.json/2.advanced-querying.md b/content/guides/04.connect/7.json/2.advanced-querying.md index f3c92e13..c40d378e 100644 --- a/content/guides/04.connect/7.json/2.advanced-querying.md +++ b/content/guides/04.connect/7.json/2.advanced-querying.md @@ -616,6 +616,10 @@ The alias rule follows the expected REST [response format](#response-format). Fo The `_json` operator filters items by values inside a JSON field. It accepts an object mapping JSON paths to standard filter operators, letting you compare specific keys or array elements without loading the full document. +::callout{icon="i-lucide-info" color="info"} +JSON filtering is also available visually in the Studio filter UI. See [Filtering JSON Fields](/guides/content/explore#filtering-json-fields). +:: + ::callout{icon="i-lucide-triangle-alert" color="warning"} `_json` is only valid on `json` typed fields. :: diff --git a/public/img/json_filter.png b/public/img/json_filter.png new file mode 100644 index 00000000..4b7cd976 Binary files /dev/null and b/public/img/json_filter.png differ diff --git a/public/img/json_filter_arrayIndex.png b/public/img/json_filter_arrayIndex.png new file mode 100644 index 00000000..cb003504 Binary files /dev/null and b/public/img/json_filter_arrayIndex.png differ diff --git a/public/img/json_filter_in_and_group.png b/public/img/json_filter_in_and_group.png new file mode 100644 index 00000000..8ce7db92 Binary files /dev/null and b/public/img/json_filter_in_and_group.png differ diff --git a/public/img/json_filter_startsWith.png b/public/img/json_filter_startsWith.png new file mode 100644 index 00000000..fe662e60 Binary files /dev/null and b/public/img/json_filter_startsWith.png differ