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 in fields, sort, and alias.
_json filters items by values inside a JSON document. Use it in filter.

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 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.

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.

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. 🐰

Directus SDK

A JavaScript and TypeScript library that simplifies working with Directus.

JSON Queries

Extract and filter values in JSON fields using the json(field, path) function and _json filter operator, with path notation, relational support, GraphQL, and TypeScript SDK.

Path Notation

Using the json() function

Filtering with _json

More information

Using the `json()` function

Filtering with `_json`