СОЗДАТЬ ИНДЕКС JSON (Transact-SQL)

2025-05-27

Применимо к: Предварительная версия SQL Server 2025 (17.x)

Создает индекс JSON для указанной таблицы и столбца в предварительной версии SQL Server 2025 (17.x).

Индексы JSON:

Можно создать до появления данных в таблице.
Можно создать в таблицах в другой базе данных, указав полное имя базы данных.
Требуется, чтобы таблица имела кластеризованный первичный ключ.
Невозможно указать в индексированных представлениях.

Замечание

Создание индексов JSON в настоящее время доступно в предварительной версии и доступно только в предварительной версии SQL Server 2025 (17.x).

Соглашения о синтаксисе Transact-SQL

Синтаксис

CREATE JSON INDEX name ON table_name (json_column_name)
  [ FOR ( sql_json_path [ , ...n ] ) ]
  [ WITH ( <json_index_option> [ , ...n ] ) ]
  [ ON { filegroup_name | "default" } ]
[ ; ]

<object> ::=
    { database_name.schema_name.table_name | schema_name.table_name | table_name }

<sql_json_path> ::=
    { character_string_literal }

<json_index_option> ::=
{
    FILLFACTOR = fillfactor
  | DROP_EXISTING = { ON | OFF }
  | ONLINE = OFF
  | ALLOW_ROW_LOCKS = { ON | OFF }
  | ALLOW_PAGE_LOCKS = { ON | OFF }
  | MAXDOP = max_degree_of_parallelism
  | DATA_COMPRESSION = { NONE | ROW | PAGE }
}

Аргументы

имя_индекса

Имя индекса. Имена индексов должны быть уникальными в таблице, но не должны быть уникальными в базе данных. Имена индексов должны соответствовать правилам идентификаторов.

ОБЪЕКТ< ON >(json_column_name )

Указывает объект (базу данных, схему или таблицу), в которой должен быть создан индекс, и имя столбца JSON .
json_column_name

Имя столбца типа данных JSON , table_name содержащего ноль или более указанных путей SQL/JSON.
sql_json_path

Путь SQL/JSON, который необходимо извлечь и индексировать из json_column_name. Значение sql_json_path по умолчанию — $.
- Рекурсивно индексирует все ключи и значения, начиная с указанного пути и далее.
- Поддерживает до 128 уровней в пути документа JSON.
- Не допускает перекрытия.
Например, $.a и $.a.b вызывают ошибку, поскольку путь $.a рекурсивно включает все пути, и намерение пользователя неясно.

ON filegroup_name

Создает заданный индекс в указанной файловой группе. Если расположение не указано, а таблица не секционирована, индекс использует ту же файловую группу, что и базовая таблица. Файловая группа уже должна существовать.

ON по умолчанию

Создает указанный индекс в файловой группе по умолчанию.

Термин по умолчанию в этом контексте не является ключевым словом. Это идентификатор файловой группы по умолчанию и должен быть разделен как в ON "default" или ON [default]. Если "default" задано, QUOTED_IDENTIFIER параметр должен быть ON для текущего сеанса. Это параметр по умолчанию. Дополнительные сведения см. в описании SET QUOTED_IDENTIFIER.

<объект>:: =

Полностью или неполностью квалифицированный объект для индексирования.

database_name

Имя базы данных.
schema_name

Имя схемы, которой принадлежит таблица.
table_name

Имя таблицы для индексирования.

FILLFACTOR = fillfactor

Указывает, на сколько процентов ядро СУБД должно заполнять конечный уровень каждой страницы индекса во время создания и изменения индекса. Fillfactor должен быть целым значением от1.100 Значение по умолчанию — 0. Если fillfactor равен 100 или 0, ядро СУБД создает индексы со страницами уровня листа, полностью заполненными.

Замечание

Значения 0 коэффициента заполнения и 100 одинаковы во всех отношениях.

Аргумент FILLFACTOR действует только при создании или перестройке индекса. Ядро СУБД не сохраняет динамически указанный процентный объем свободного места на страницах. Чтобы просмотреть параметр коэффициента заполнения, используйте представление каталога sys.indexes .

Создание кластеризованного индекса со значением FILLFACTOR, которое меньше 100, влияет на объем занимаемого места для хранения данных, так как система управления базами данных перераспределяет данные при его создании.

Дополнительные сведения см. в статье Указание коэффициента заполнения для индекса.

DROP_EXISTING = { ON | OFF }

Указывает, что именованный, существующий пространственный индекс удаляется и перестраивается. Значение по умолчанию — OFF.

НА

Существующий индекс удаляется и перестраивается. Указанное имя индекса должно совпадать с существующим индексом; однако определение индекса можно изменить. Например, можно указать различные столбцы, порядок сортировки, схему секционирования или параметры индекса.
Выкл.

Ошибка отображается, если указанное имя индекса уже существует.

Тип индекса нельзя изменить с помощью DROP_EXISTING.

ОНЛАЙН = ВЫКЛ.

Указывает, что базовые таблицы и связанные индексы недоступны для запросов и изменения данных во время операции индекса. В этой версии SQL Server сборки индексов в сети не поддерживаются для индексов JSON. Если для индекса JSON задано ON значение этого параметра, возникает ошибка. Либо опустить ONLINE параметр, либо задать значение ONLINEOFF .

Операция индекса, выполняемая вне сети, которая создает, перестраивает или удаляет индекс JSON, получает блокировку изменения схемы (Sch-M) таблицы. Это предотвращает доступ к базовой таблице всех пользователей во время операции.

Операции с индексами в Сети недоступны в каждом выпуске SQL Server.

Для получения списка возможностей, поддерживаемых выпусками SQL Server на платформе Windows, см. следующий список:

ALLOW_ROW_LOCKS = { ON | OFF } (Включает или отключает блокировки на уровне строк)

Указывает, разрешены ли блокировки строк. Значение по умолчанию — ON.

НА

Блокировки строк допустимы при доступе к индексу. Ядро СУБД определяет, когда используются блокировки строк.
Выкл.

Блокировки строк не используются.

ALLOW_PAGE_LOCKS (разрешить блокировку страниц) = { ВКЛ. | ВЫКЛ. }

Указывает, разрешены ли блокировки страниц. Значение по умолчанию — ON.

НА

Блокировки страниц возможны при доступе к индексу. Ядро СУБД определяет, когда используются блокировки страниц.
Выкл.

Блокировки страниц не используются.

MAXDOP = max_degree_of_parallelism

Переопределяет опцию конфигурации max degree of parallelism на время выполнения операции индекса. Используется MAXDOP для ограничения количества процессоров, используемых в параллельном выполнении плана. Максимальное значение — 64 процессора.

Это важно

Хотя параметр MAXDOP синтаксически поддерживается, CREATE SPATIAL INDEX в настоящее время всегда используется только один процессор.

max_degree_of_parallelism может быть одним из следующих значений.

Ценность	Описание
`1`	Подавляет формирование параллельных планов.
`>1`	Ограничивает максимальное количество процессоров, используемых в параллельных операциях с индексами, заданным или меньшим числом в зависимости от текущей рабочей нагрузки системы.
`0` (по умолчанию)	В зависимости от текущей рабочей нагрузки системы использует реальное или меньшее число процессоров.

Дополнительные сведения см. в статье Настройка параллельных операций с индексами.

Параллельные операции индексов недоступны в каждом выпуске SQL Server.

Для получения списка возможностей, поддерживаемых выпусками SQL Server на платформе Windows, см. следующий список:

DATA_COMPRESSION = { NONE (нет) | ROW (строка) | PAGE (страница) }

Определяет уровень сжатия данных, используемый индексом.

НЕТ

Сжатие данных по индексу не используется
РЯД

Сжатие строк, используемое для данных индексом
СТРАНИЦА

Сжатие страниц, используемое для данных по индексу

Замечания

Каждый параметр можно указать только один раз для каждой CREATE JSON INDEX инструкции. При указании дубликата любого параметра возникает ошибка.

[ ON { filegroup_name | "default" } ]

Если указать файловую группу для индекса JSON, индекс помещается в эту файловую группу независимо от схемы секционирования таблицы.

Дополнительные сведения о создании индексов см. в разделе "Примечания" в CREATE INDEX.

Предикаты, поддерживаемые индексом JSON

Операции поиска в документах JSON, содержащихся в столбце JSON в таблице, можно оптимизировать, если индекс JSON существует в столбце json . Индекс JSON используется в запросах с различными выражениями на основе функций JSON.

В следующих примерах используется Sales.SalesOrderHeader таблица в AdventureWorks2022 базе данных с именем Info. Столбец Info создается как тип JSON . Индекс JSON также создается в столбце Info с параметрами по умолчанию. В следующем примере кода показан оператор CREATE JSON INDEX:

CREATE JSON INDEX sales_info_idx ON Sales.SalesOrderHeader(Info);

Для примеров выражений поиска используйте следующие документы JSON в качестве данных:

НомерЗаказа	Информация
`437`	`{"Customer":{"Name":"Kelsey Raje","ID":16517,"Type":"IN"},"Order":{"ID":43710,"Number":"SO43710","CreationDate":"2011-06-02T00:00:00","TotalDue":3953.9884}}`
`643`	`{"Customer":{"Name":"Aaron Campbell","ID":16167,"Type":"IN"},"Order":{"ID":64304,"Number":"SO64304","CreationDate":"2014-01-16T00:00:00","TotalDue":36.0230, "IsProcessed": true}}`

функция JSON_PATH_EXISTS

Используйте функцию JSON_PATH_EXISTS для проверки наличия указанного пути SQL/JSON в документе JSON.

Этот запрос демонстрирует JSON_PATH_EXISTS в столбце JSON, который можно оптимизировать с помощью индекса JSON.

SELECT COUNT(*)
FROM Sales.SalesOrderHeader
WHERE JSON_PATH_EXISTS(Info, '$.Order.IsProcessed') = 1;

Индекс JSON поддерживается с JSON_PATH_EXISTS предикатом и следующими операторами:

Операторы сравнения (=)
IS [NOT] NULL предикат (в настоящее время не поддерживается)

функция JSON_VALUE

Используйте JSON_VALUE для извлечения текста и скалярного значения JSON в указанном пути SQL/JSON в документе JSON. В следующих запросах показано, как JSON_VALUE можно оптимизировать выражение в столбце JSON с помощью индекса JSON.

Поиск равенства строки JSON в свойстве объекта:

SELECT COUNT(*)
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.Type') = 'IN';

Поиск равенства числа JSON в свойстве объекта после преобразования этого значения в тип данных int.
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
```
Выполнение поиска чисел в JSON в диапазоне значений, хранящихся в свойстве объекта, после преобразования значения в тип данных int.
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
```
Поиск по диапазону числа JSON в свойстве объекта после преобразования значения в десятичный тип данных.
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Order.TotalDue RETURNING decimal(20, 4)) BETWEEN 1000 and 2000;
```

Индекс JSON поддерживается с предикатом JSON_VALUE и следующими операторами:

Операторы сравнения (=)
LIKE предикат (в настоящее время не поддерживается)
IS [NOT] NULL предикат (в настоящее время не поддерживается)

функция JSON_CONTAINS

Функция JSON_CONTAINS поддерживает простой поиск значений JSON в документе JSON, который может использовать индекс JSON при наличии в столбце JSON . Эту функцию можно использовать для проверки того, содержится ли скалярное значение JSON, объект или массив в указанном пути SQL/JSON в документе JSON. Значения поиска, указанные как скалярные типы SQL, преобразуются по существующим преобразованиям типов SQL/JSON. Эти правила определены в разделе поведения.

Требование

Для таблицы, содержащей столбец JSON, требуется ключ кластеризации. Ошибка возникает, если ключ кластеризации отсутствует. Ключ кластеризации ограничен 31 столбцами, а максимальный размер ключа индекса должен быть меньше 128 байт.

Разрешения

Пользователь должен иметь ALTER разрешение на таблицу или быть членом предопределенной роли сервера sysadmin либо членом предопределенных ролей базы данных db_ddladmin и db_owner.

Ограничения

Для инструкции индекса JSON существуют следующие ограничения:

Только один индекс JSON можно создать в столбце JSON в таблице.
В таблице можно создать до 249 индексов JSON. Создание нескольких индексов JSON в определенном столбце JSON не поддерживается.
Невозможно создать индекс JSON в вычисляемых столбцах JSON .
Индекс JSON нельзя создать в столбцах json в представлениях, табличных переменных или в таблицах, оптимизированных для памяти.
Индекс JSON можно создать или изменить только в автономном режиме.
Пути JSON не могут перекрываться в определении индекса. Например, $a и $a.b перекрываются и не допускаются в инструкции CREATE JSON INDEX .
Для изменения путей требуется повторное создание индекса JSON.
Индексы JSON не поддерживаются в подсказках для индексов.
Параметр сжатия данных не поддерживается.

Примеры

А. Создание индекса JSON в столбце JSON

В следующем примере создается таблица с именемdocs, содержащая столбец типа JSON. content Затем в примере создается индекс JSON в json_content_indexстолбце content . В примере создается индекс JSON по всему документу JSON или по всем путям SQL/JSON в этом документе.

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);
CREATE JSON INDEX json_content_index ON docs(content);

А. Создание индекса JSON в столбце JSON с определенными путями

В следующем примере создается таблица с именемdocs, содержащая столбец типа JSON. content Затем в примере создается индекс JSON в json_content_indexстолбце content . В примере создается индекс JSON для определенных путей SQL/JSON в документе JSON.
В примере также устанавливается индекс FILLFACTOR для 80.

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);

CREATE JSON INDEX json_content_index
    ON docs(content) FOR ('$.a', '$.b')
    WITH (FILLFACTOR = 80);