JSON 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 infields,sort, andalias._jsonfilters items by values inside a JSON document. Use it infilter.
Both use the same path notation and work across REST, GraphQL, and the SDK.
Using the json() function
Function Syntax:
json(field, path)
Example:
Extract the color key from a metadata JSON field:
GET /items/articles?fields=id,title,json(metadata, color)
import { createDirectus, rest, readItems } from '@directus/sdk';
const directus = createDirectus('https://directus.example.com').with(rest());
const result = await directus.request(
readItems('articles', {
fields: ['id', 'title', 'json(metadata, color)'],
})
);
query {
articles {
id
title
metadata_func {
json(path: "color")
}
}
}
Response:
{
"data": [
{
"id": 1,
"title": "An Article",
"metadata_color_json": "blue"
}
]
}
{
"data": {
"articles": [
{
"id": 1,
"title": "An Article",
"metadata_func": { "json": "blue" }
}
]
}
}
For REST and the SDK, the extracted value is returned under the alias {field}_{path}_json, with ., [, and ] replaced by underscores.
Filtering with _json
Operator Syntax:
{
"field": {
"_json": {
"path": {
"_operator": value
}
}
}
}
Example:
Find articles where the color key inside metadata equals "blue":
GET /items/articles
?filter={"metadata":{"_json":{"color":{"_eq":"blue"}}}}
import { createDirectus, rest, readItems } from '@directus/sdk';
const directus = createDirectus('https://directus.example.com').with(rest());
const result = await directus.request(
readItems('articles', {
filter: {
metadata: {
_json: { color: { _eq: 'blue' } },
},
},
})
);
query {
articles(filter: { metadata: { _json: { color: { _eq: "blue" } } } }) {
id
title
}
}
Response:
{
"data": [
{ "id": 1, "title": "An Article" },
{ "id": 4, "title": "Another Article" }
]
}
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).
See the reference for more details.
Path Notation
Paths use dot notation for object keys and bracket notation for array indices.
| Pattern | Example | Meaning |
|---|---|---|
key | color | Top-level object key |
a.b.c | settings.theme.color | Nested object keys |
[n] | tags[0] | Array element at index n |
a[n].b | items[0].name | Mixed object/array access |
Wildcards (*, [*]) among other special characters are not supported. See the reference for the full list.
More information
The 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)
Get once-a-month release notes & real‑world code tips...no fluff. 🐰