CRÉER UN INDEX JSON (Transact-SQL)

S’applique à : SQL Server 2025 (17.x)

Crée un index JSON sur une table et une colonne spécifiées dans SQL Server 2025 (17.x).

Index JSON :

Peut être créé avant que des données ne soient présentes dans la table.
Peut être créé sur des tables d’une autre base de données en spécifiant un nom de base de données qualifié.
Exiger que la table dispose d’une clé primaire en cluster.
Ne peut pas être spécifié sur des vues indexées.

Remarque

La création d’index JSON est actuellement en version avant-première et disponible uniquement dans SQL Server 2025 (17.x).

Conventions de la syntaxe Transact-SQL

Syntaxe

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> ::=
{
    OPTIMIZE_FOR_ARRAY_SEARCH = { ON | OFF }
  | 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 }
}

Les arguments

nom_de_l'index

Nom de l’index. Les noms d’index doivent être uniques dans une table, mais ne doivent pas être uniques dans une base de données. Les noms d’index doivent suivre les règles des identificateurs.

ON <(>json_column_name )

Spécifie l’objet (base de données, schéma ou table) sur lequel l’index doit être créé et le nom de la colonne json .
json_column_name

Nom de la colonne de type de données JSON dans table_name laquelle contient zéro ou plusieurs chemins SQL/JSON spécifiés.
sql_json_path

Chemin SQL/JSON qui doit être extrait et indexé à partir de json_column_name. La valeur par défaut de sql_json_path est de $.
- Indexe de manière récursive toutes les clés/valeurs à partir du chemin spécifié.
- Prend en charge jusqu’à 128 niveaux dans le chemin du document JSON.
- Ne permet pas de chevauchements.
Par exemple, $.a et $.a.b déclenchez une erreur, car le chemin $.a inclut de manière récursive tous les chemins et que l’intention de l’utilisateur n’est pas claire.

SUR filegroup_name

Crée l'index spécifié dans le groupe de fichiers spécifié. Si aucun emplacement n’est spécifié et que la table n’est pas partitionnée, l’index utilise le même groupe de fichiers que la table sous-jacente. Le groupe de fichiers doit déjà exister.

ON « default »

Crée l’index spécifié sur le groupe de fichiers par défaut.

Le terme par défaut, dans ce contexte, n’est pas un mot clé. Il s’agit d’un identificateur pour le groupe de fichiers par défaut et doit être délimité, comme dans ON "default" ou ON [default]. Si "default" elle est spécifiée, l’option QUOTED_IDENTIFIER doit être ON pour la session active. Il s’agit du paramètre par défaut. Pour plus d’informations, voir SET QUOTED_IDENTIFIER.

<object> :: =

Objet totalement qualifié ou non qualifié à indexer.

database_name

Nom de la base de données.
schema_name

Nom du schéma auquel appartient la table.
table_name

Nom de la table à indexer.

OPTIMIZE_FOR_ARRAY_SEARCH = { ON | OFF }

Spécifie si les recherches de tableau sont optimisées dans l’index JSON. La valeur par défaut est OFF.

FILLFACTOR = fillfactor

Spécifie un pourcentage indiquant le taux de remplissage appliqué par le Moteur de base de données au niveau feuille de chaque page d'index lors de la création ou de la reconstruction de l'index. fillfactor doit être une valeur entière comprise entre 1100. La valeur par défaut est 0. Si fillfactor est 100 ou 0, le moteur de base de données crée des index avec des pages de feuilles remplies à pleine capacité.

Remarque

Les valeurs 0 de facteur de remplissage et 100 sont identiques à tous les égards.

La valeur FILLFACTOR s’applique uniquement lors de la création ou de la reconstruction de l’index. Dans les pages, le Moteur de base de données ne conserve pas dynamiquement le pourcentage d’espace libre défini. Pour afficher le paramètre de facteur de remplissage, utilisez la vue catalogue sys.indexes .

La création d’un index clusterisé avec un FILLFACTOR inférieur à 100 affecte la quantité d’espace de stockage occupé par les données, car le moteur de base de données redistribue les données lorsqu’il crée l’index clusterisé.

Pour plus d’informations, consultez Spécifier un facteur de remplissage pour un index.

DROP_EXISTING = { ON | OFF }

Spécifie que l’index JSON nommé et préexistant est supprimé et reconstruit. La valeur par défaut est OFF.

ACTIVÉ

L’index existant est supprimé et reconstruit. Le nom d’index spécifié doit être identique à un index actuellement existant ; toutefois, la définition d’index peut être modifiée. Par exemple, vous pouvez spécifier différentes colonnes, ordre de tri, schéma de partition ou options d’index.
DE

Une erreur s’affiche si le nom d’index spécifié existe déjà.

Le type d’index ne peut pas être modifié à l’aide de DROP_EXISTING.

EN LIGNE = HORS LIGNE

Spécifie que les tables sous-jacentes et les index associés ne sont pas disponibles pour les requêtes et la modification des données pendant l’opération d’index. Dans cette version de SQL Server, les builds d’index en ligne ne sont pas prises en charge pour les index JSON. Si cette option est définie ON pour un index JSON, une erreur est générée. Omettez l'option ONLINE ou définissez ONLINE sur OFF.

Une opération d’index hors connexion qui crée, reconstruit ou supprime un index JSON, acquiert un verrou de modification de schéma (Sch-M) sur la table. Cela empêche tous les utilisateurs d'accéder à la table sous-jacente pendant la durée de l'opération.

Les opérations d’index en ligne ne sont pas disponibles dans chaque édition de SQL Server.

Pour obtenir la liste des fonctionnalités prises en charge par les éditions de SQL Server sur Windows, consultez :

ALLOW_ROW_LOCKS = { ON | OFF }

Spécifie si les verrous de ligne sont autorisés. La valeur par défaut est ON.

ACTIVÉ

Les verrous de ligne sont autorisés lors de l'accès à l'index. Le Moteur de base de données détermine le moment où les verrous de ligne sont utilisés.
DE

Les verrous de ligne ne sont pas utilisés.

ALLOW_PAGE_LOCKS = { ON | OFF }

Spécifie si les verrous de page sont autorisés. La valeur par défaut est ON.

ACTIVÉ

Les verrous de page sont autorisés lors de l'accès à l'index. Le Moteur de base de données détermine le moment où les verrous de page sont utilisés.
DE

Les verrous de page ne sont pas utilisés.

MAXDOP = max_degree_of_parallelism

Remplace l’option max degree of parallelism de configuration pour la durée de l’opération d’index. Permet MAXDOP de limiter le nombre de processeurs utilisés dans une exécution de plan parallèle. Le maximum est de 64 processeurs.

Important

Bien que l’option MAXDOP soit prise en charge de manière syntactique, CREATE JSON INDEX n’utilise toujours qu’un seul processeur.

max_degree_of_parallelism peut être l’une des valeurs suivantes.

Valeur	Descriptif
`1`	Supprime la création de plans parallèles.
`>1`	Limite le nombre maximal de processeurs utilisés dans l'indexation parallèle au nombre défini ou à un nombre inférieur en fonction de la charge de travail actuelle du système.
`0` (valeur par défaut)	Utilise le nombre réel de processeurs ou un nombre de processeurs inférieur en fonction de la charge de travail actuelle du système.

Pour plus d’informations, consultez Configurer des opérations d’index parallèles.

Les opérations d’index parallèles ne sont pas disponibles dans toutes les éditions de SQL Server.

Pour obtenir la liste des fonctionnalités prises en charge par les éditions de SQL Server sur Windows, consultez :

DATA_COMPRESSION = { NONE | LIGNE | PAGE }

Détermine le niveau de compression des données utilisé par l’index.

AUCUN

Aucune compression utilisée sur les données par l’index
LIGNE

Compression de ligne utilisée sur les données par l’index
PAGE

Compression de page appliquée aux données par l'index

Remarques

Chaque option ne peut être spécifiée qu’une seule fois par CREATE JSON INDEX instruction. La spécification d’un doublon d’une option génère une erreur.

[ ON { filegroup_name | « default » } ]

Si vous spécifiez un groupe de fichiers pour un index JSON, l’index est placé sur ce groupe de fichiers, quel que soit le schéma de partitionnement de la table.

Pour plus d’informations sur la création d’index, consultez la section Notes dans CREATE INDEX.

Prédicats pris en charge avec un index JSON

La recherche d’opérations sur des documents JSON contenus dans une colonne JSON dans une table peut être optimisée si un index JSON existe sur la colonne JSON . L’index JSON est utilisé dans les requêtes avec différentes expressions basées sur des fonctions JSON.

Les exemples suivants utilisent la Sales.SalesOrderHeader table dans la AdventureWorks2025 base de données avec une colonne json appelée Info. La Info colonne est créée en tant que type json . Un index JSON est également créé sur la Info colonne avec les paramètres par défaut. L’exemple de code suivant montre l’instruction CREATE JSON INDEX :

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

Pour les exemples d’expressions de recherche, utilisez les documents JSON suivants en tant que données :

Numéro de commande de vente	Informations
`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}}`

fonction JSON_PATH_EXISTS

Utilisez la fonction JSON_PATH_EXISTS pour tester si un chemin SQL/JSON spécifié existe dans un document JSON.

Cette requête illustre JSON_PATH_EXISTS sur une colonne json qui peut être optimisée à l’aide d’un index JSON :

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

L’index JSON est pris en charge avec le prédicat JSON_PATH_EXISTS et les opérateurs suivants :

Opérateurs de comparaison (=)
IS [NOT] NULL prédicat (actuellement non pris en charge)

fonction JSON_VALUE

Utilisez le JSON_VALUE pour extraire le texte JSON ou la valeur scalaire d’un chemin SQL/JSON spécifié dans un document JSON. Les requêtes suivantes montrent comment une JSON_VALUE expression sur une colonne JSON peut être optimisée à l’aide d’un index JSON.

Recherche d’égalité pour une chaîne JSON dans une propriété d’objet :

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

Rechercher l'égalité pour un nombre JSON dans une propriété d'objet après avoir converti la valeur en une valeur du type de données int :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
```
Recherchez un nombre JSON dans une propriété d’objet après avoir converti la valeur en type de données int :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
```

Recherchez un nombre JSON dans une propriété d’objet après avoir converti la valeur en type de données décimal :

SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Order.TotalDue RETURNING decimal(20, 4)) BETWEEN 1000 and 2000;

L’index JSON est pris en charge avec un JSON_VALUE prédicat et les opérateurs suivants :

Opérateurs de comparaison (=)
LIKE prédicat (actuellement non pris en charge)
IS [NOT] NULL prédicat (actuellement non pris en charge)

fonction JSON_CONTAINS

La fonction JSON_CONTAINS prend en charge la recherche facile de valeurs JSON dans un document JSON qui peut utiliser un index JSON s’il est présent sur une colonne JSON . Cette fonction peut être utilisée pour tester si une valeur scalaire JSON, un objet ou un tableau est contenu dans le chemin d’accès SQL/JSON spécifié dans un document JSON. Les valeurs de recherche spécifiées en tant que types scalaires SQL sont converties par conversions de types SQL/JSON existantes. Ces règles sont définies dans la section comportement.

Besoin

Une clé de clustering est requise sur la table qui contient la colonne JSON. Une erreur est générée si la clé de clustering est absente. La clé de clustering est limitée à 31 colonnes et la taille maximale de la clé d’index doit être inférieure à 128 octets.

Autorisations

L’utilisateur doit disposer ALTER d’autorisations sur la table, ou être membre du rôle serveur fixe sysadmin , ou des rôles de base de données fixes db_ddladmin et db_owner .

Limites

Les limitations suivantes existent pour l’instruction d’index JSON :

Un seul index JSON peut être créé sur une colonne json dans une table.
Vous pouvez créer jusqu’à 249 index JSON dans une table. La création de plusieurs index JSON sur une colonne JSON spécifique n’est pas prise en charge.
Un index JSON ne peut pas être créé sur des colonnes json calculées.
Un index JSON ne peut pas être créé sur des colonnes JSON dans une vue, une variable table ou une table optimisée en mémoire.
Un index JSON peut être créé ou modifié uniquement de manière hors connexion.
Les chemins JSON ne peuvent pas se chevaucher dans la définition d’index. Par exemple, $a et $a.b se chevauchent et ne sont pas autorisés dans l'instruction CREATE JSON INDEX.
La modification des chemins d’accès nécessite la recréation de l’index JSON.
Les index JSON ne sont pas pris en charge dans les indicateurs d’index.
L’option de compression des données n’est pas prise en charge.

Exemples

Un. Créer un index JSON sur une colonne JSON

L’exemple suivant crée une table nommée docs qui contient une colonne de type json. content L’exemple crée ensuite un index JSON, json_content_indexsur la content colonne. L’exemple crée l’index json sur l’ensemble du document JSON ou sur tous les chemins SQL/JSON du document JSON.

DROP TABLE IF EXISTS docs;

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

CREATE JSON INDEX json_content_index
    ON docs (content);

Un. Créer un index JSON sur une colonne JSON avec des chemins d’accès spécifiques

L’exemple suivant crée une table nommée docs qui contient une colonne de type json. content L’exemple crée ensuite un index JSON, json_content_indexsur la content colonne. L’exemple crée l’index json sur des chemins SQL/JSON spécifiques dans le document JSON.
L’exemple définit également l’index FILLFACTOR sur 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);

B. Index JSON avec optimisation de la recherche de tableau

L’exemple suivant retourne des index JSON pour la table dbo.Customers. L’index JSON est créé avec l’option d’optimisation de la recherche de tableau activée.

DROP TABLE IF EXISTS dbo.Customers;

CREATE TABLE dbo.Customers
(
    customer_id INT IDENTITY PRIMARY KEY,
    customer_info JSON NOT NULL
);

CREATE JSON INDEX CustomersJsonIndex
    ON dbo.Customers (customer_info) WITH (OPTIMIZE_FOR_ARRAY_SEARCH = ON);

INSERT INTO dbo.Customers (customer_info)
VALUES ('{"name":"customer1", "email": "customer1@example.com", "phone":["123-456-7890", "234-567-8901"]}');

SELECT object_id,
       index_id,
       optimize_for_array_search
FROM sys.json_indexes AS ji
WHERE object_id = OBJECT_ID('dbo.Customers');

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-27