# Quickstart

> Quickstart for extracting and filtering values inside JSON fields with the json() function and _json filter operator.

Directus provides two ways of working with JSON fields in queries:

- [`json(field, path)`](/guides/connect/json/quickstart#using-the-json-function): A selection function to extract a value from a JSON document. It can be used in the `fields`, `sort`, and `alias` parameters.
- [`_json`](/guides/connect/json/quickstart#filtering-with-_json): A filter operator that lets you filter records based on values within a JSON document. It can be used within the `filter` parameter.

Both use the same path notation and work across REST, GraphQL, and the SDK.

<callout color="info" icon="i-lucide-info">

JSON filtering is also available visually in the Studio filter UI. See [Filtering JSON Fields](/guides/content/explore#filtering-json-fields).

</callout>

## Using the `json()` function

**Function Syntax:**

```text
json(field, path)
```

**Example:**

Extract the `color` key from a `metadata` JSON field:

<code-group>

```http [REST]
GET /items/articles?fields=id,title,json(metadata, color)
```

```js [SDK]
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)"],
  }),
);
```

```graphql [GraphQL]
query {
  articles {
    id
    title
    metadata_func {
      json(path: "color")
    }
  }
}
```

</code-group>

Response:

<code-group>

```json [REST / SDK]
{
  "data": [
    {
      "id": 1,
      "title": "An Article",
      "metadata_color_json": "blue"
    }
  ]
}
```

```json [GraphQL]
{
  "data": {
    "articles": [
      {
        "id": 1,
        "title": "An Article",
        "metadata_func": { "json": "blue" }
      }
    ]
  }
}
```

</code-group>

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:**

```text
{
    "field": {
        "_json": {
            "path": {
                "_operator": value
            }
        }
    }
}
```

**Example:**

Find articles where the `color` key inside `metadata` equals `"blue"`:

<code-group>

```http [REST]
GET /items/articles
    ?filter={"metadata":{"_json":{"color":{"_eq":"blue"}}}}
```

```js [SDK]
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" } },
      },
    },
  }),
);
```

```graphql [GraphQL]
query {
  articles(filter: { metadata: { _json: { color: { _eq: "blue" } } } }) {
    id
    title
  }
}
```

</code-group>

Response:

```json
{
  "data": [
    { "id": 1, "title": "An Article" },
    { "id": 4, "title": "Another Article" }
  ]
}
```

Refer to the [Supported Inner Operations](/guides/connect/json/advanced-querying#supported-inner-operators) 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.

<table>
<thead>
  <tr>
    <th>
      Pattern
    </th>
    
    <th>
      Example
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      <code>
        color
      </code>
    </td>
    
    <td>
      Top-level object key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        a.b.c
      </code>
    </td>
    
    <td>
      <code>
        settings.theme.color
      </code>
    </td>
    
    <td>
      Nested object key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [n]
      </code>
    </td>
    
    <td>
      <code>
        tags[0]
      </code>
    </td>
    
    <td>
      Array element at index <code>
        n
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        a[n].b
      </code>
    </td>
    
    <td>
      <code>
        items[0].name
      </code>
    </td>
    
    <td>
      Mixed object/array access
    </td>
  </tr>
</tbody>
</table>

Wildcards (`*`, `[*]`) and other special characters are not currently supported. See the [Unsupported Path Expressions](/guides/connect/json/advanced-querying#unsupported-path-expressions) section for a complete list of unsupported characters.

## More information

For advanced usage details and additional examples, see [Advanced JSON Querying](/guides/connect/json/advanced-querying).