Quickstart
Directus provides two ways of working with JSON fields in queries:
json(field, path): A selection function to extract a value from a JSON document. It can be used in thefields,sort, andaliasparameters._json: A filter operator that lets you filter records based on values within a JSON document. It can be used within thefilterparameter.
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:
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)"],
}),
);
GET /items/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 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":
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" } },
},
},
}),
);
GET /items/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" }
]
}
Refer to the Supported Inner Operations section for a list of available operators within the _json operator.
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 key |
[n] | tags[0] | Array element at index n |
a[n].b | items[0].name | Mixed object/array access |
Wildcards (*, [*]) and other special characters are not currently supported. See the Unsupported Path Expressions section for a complete list of unsupported characters.
More information
For advanced usage details and additional examples, see Advanced JSON Querying.
Get once-a-month release notes & real‑world code tips...no fluff. 🐰
Directus SDK
A JavaScript and TypeScript library that simplifies working with Directus.
Advanced Querying
Advanced JSON querying for the `json(field, path)` function and `_json` filter operator, including path notation, relational queries, GraphQL support, SDK usage, depth limits, and database-specific behavior.