---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
alternate:
  - https://ydb-platform--ydb.viewer.diplodoc.com/en/recipes/json-search/json-index-quickstart.md
  - https://ydb-platform--ydb.viewer.diplodoc.com/ru/recipes/json-search/json-index-quickstart.md
  - href: https://ydb-platform--ydb.viewer.diplodoc.com/ru/recipes/json-search/json-index-quickstart.md
    type: text/markdown
    title: Markdown version
  - href: https://ydb-platform--ydb.viewer.diplodoc.com/ru/llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: ru/core/recipes/json-search/json-index-quickstart.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb-platform--ydb.viewer.diplodoc.com/ru/llms.txt

# JSON-индекс — быстрый старт

В этом руководстве показано, как создать [JSON-индекс](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/json-indexes.md) и выполнять запросы с использованием функций [JSON_EXISTS](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/builtins/json.md#json_exists) и [JSON_VALUE](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/builtins/json.md#json_value) в YDB.

## Создайте таблицу и JSON-индекс

```yql
CREATE TABLE documents (
    id Uint64,
    payload JsonDocument,
    PRIMARY KEY (id),
    INDEX json_idx GLOBAL USING json ON (payload)
);
```

Тип колонки `JsonDocument` хранит JSON в компактном бинарном формате и предпочтителен для индексируемой колонки. Альтернативно может использоваться тип `Json` (текстовое представление).

Первичный ключ таблицы должен состоять из единственной колонки целочисленного типа (`Uint64`, `Uint32`, `Int64` или `Int32`) — это [текущее ограничение](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/json-indexes.md#limitations) реализации JSON-индексов.

## Добавьте тестовые данные

```yql
UPSERT INTO documents (id, payload) VALUES
    (1, JsonDocument(@@{"user": {"id": 100, "name": "Alice"}, "active": true}@@)),
    (2, JsonDocument(@@{"user": {"id": 101, "name": "Bob"}, "active": false}@@)),
    (3, JsonDocument(@@{"user": {"id": 102, "name": "Charlie"}, "archived": true}@@));
```

Здесь конструкция `@@...@@` — это [многострочный строковый литерал](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/expressions.md), удобный для записи JSON без экранирования кавычек. Функция `JsonDocument(...)` преобразует текст в значение типа `JsonDocument`.

## Фильтр по наличию пути в документе

Функция [JSON_EXISTS](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/builtins/json.md#json_exists) проверяет, существует ли в документе путь, заданный выражением JsonPath.

```yql
SELECT id
FROM documents VIEW json_idx
WHERE JSON_EXISTS(payload, '$.user.id');
```

Результат:

```text
id
1
2
3
```

Для поиска по индексу используется токен пути `$.user.id`. Индекс возвращает результат без сканирования основной таблицы.

## Отбор строк с конкретным значением поля документа

Функция [JSON_VALUE](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/builtins/json.md#json_value) извлекает скалярное значение по JsonPath; для использования индекса обязательно нужно указать тип возвращаемого значения в секции `RETURNING`:

```yql
SELECT id
FROM documents VIEW json_idx
WHERE JSON_VALUE(payload, '$.user.name' RETURNING Utf8) = "Alice"u;
```

Результат:

```text
id
1
```

При проверке равенства в индекс попадает токен «путь + значение» (`$.user.name = "Alice"`), что обеспечивает наивысшую селективность.

## Комбинация условий

Несколько вызовов `JSON_EXISTS` / `JSON_VALUE` на одной индексированной JSON-колонке можно объединять операторами `AND` и `OR`:

```yql
SELECT id
FROM documents VIEW json_idx
WHERE JSON_EXISTS(payload, '$.user.id')
  AND JSON_VALUE(payload, '$.active' RETURNING Bool);
```

Результат:

```text
id
1
```

## Подробнее

* [JSON-индексы](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/json-indexes.md) — полный обзор возможностей и ограничений.
* [VIEW (JSON-индекс)](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/select/json_index.md) — синтаксис запросов через `VIEW`.
* [INDEX (CREATE TABLE)](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/create_table/json_index.md) — синтаксис создания JSON-индекса.
* [Каталог со вложенными атрибутами](https://ydb-platform--ydb.viewer.diplodoc.com/ru/recipes/json-search/json-index-catalog.md) — пример каталога товаров с вложенными атрибутами.