ERSTELLEN SIE JSON-INDEX (Transact-SQL)

2025-05-27

Gilt für: SQL Server 2025 (17.x) Vorschau

Erstellt einen JSON-Index für eine angegebene Tabelle und Spalte in SQL Server 2025 (17.x) Preview.

JSON-Indizes:

Kann erstellt werden, bevor daten in der Tabelle vorhanden sind.
Kann in Tabellen in einer anderen Datenbank erstellt werden, indem ein qualifizierter Datenbankname angegeben wird.
Die Tabelle muss über einen gruppierten Primärschlüssel verfügen.
Kann für indizierte Ansichten nicht angegeben werden.

Hinweis

Das Erstellen von JSON-Indizes befindet sich derzeit in der Vorschau und ist nur in SQL Server 2025 (17.x) Preview verfügbar.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

index_name

Der Name des Index. Indexnamen müssen innerhalb einer Tabelle eindeutig sein, müssen aber nicht innerhalb einer Datenbank eindeutig sein. Indexnamen müssen den Regeln von Bezeichnern entsprechen.

ON-Objekt <> ( json_column_name )

Gibt das Objekt (Datenbank, Schema oder Tabelle) an, für das der Index erstellt werden soll, und den Namen der JSON-Spalte .
json_column_name

Der Name der Spalte des JSON-Datentyps in table_name, der keine oder mehr der angegebenen SQL/JSON-Pfade enthält.
sql_json_path

Der SQL/JSON-Pfad, der aus json_column_name extrahiert und indiziert werden muss. Der Standardwert für sql_json_path lautet $.
- Rekursiv werden alle Schlüssel/Werte ab dem angegebenen Pfad indiziert.
- Unterstützt bis zu 128 Ebenen im JSON-Dokumentpfad.
- Erlaubt kein Überlappen.
Beispielsweise lösen $.a und $.a.b einen Fehler aus, da der Pfad $.a rekursiv alle anderen Pfade umfasst und die Absicht des Benutzers unklar ist.

ON filegroup_name

Erstellt den angegebenen Index für die angegebene Dateigruppe. Wenn kein Speicherort angegeben ist und die Tabelle nicht partitioniert wird, verwendet der Index dieselbe Dateigruppe wie die zugrunde liegende Tabelle. Die Dateigruppe muss bereits vorhanden sein.

AN „Standard“

Erstellt den angegebenen Index in der Standarddateigruppe.

Der Ausdrucksstandard ist in diesem Kontext kein Schlüsselwort. Es handelt sich um einen Bezeichner für die Standarddateigruppe und muss wie in ON "default" oder ON [default]. Wenn "default" angegeben, muss die QUOTED_IDENTIFIER Option für die aktuelle Sitzung sein ON . Dies ist die Standardeinstellung. Weitere Informationen finden Sie unter SET QUOTED_IDENTIFIER.

<object>:: =

Das vollqualifizierte oder nicht vollqualifizierte Objekt, das indiziert werden soll.

database_name

Der Name der Datenbank.
schema_name

Der Name des Schemas, zu dem die Tabelle gehört.
table_name

Der Name der tabelle, die indiziert werden soll.

FILLFACTOR = Füllfaktor

Gibt einen Prozentsatz an, der angibt, wie weit das Datenbank-Engine die Blattebene jeder Indexseite während der Indexerstellung oder -neuerstellung füllen soll. fillfactor muss ein ganzzahliger Wert von 1 bis 100 sein. Der Standardwert lautet 0. Wenn der Füllfaktor ist 100 oder 0, erstellt das Datenbankmodul Indizes mit blattseitigen Seiten, die zur Kapazität gefüllt sind.

Hinweis

Füllfaktorwerte 0 und 100 sind in allen Punkten gleich.

Die FILLFACTOR-Einstellung gilt nur, wenn der Index erstellt oder neu erstellt wird. Die Datenbank-Engine hält den angegebenen Prozentsatz des Speicherplatzes auf den Seiten nicht dynamisch frei. Verwenden Sie die Katalogansicht "sys.indexes ", um die Einstellung für den Füllfaktor anzuzeigen.

Das Erstellen eines gruppierten Indexes mit einem FILLFACTOR geringeren 100 Als wirkt sich auf die Menge des Speicherplatzes aus, den die Daten belegen, da das Datenbankmodul die Daten beim Erstellen des gruppierten Indexes neu verteilt.

Weitere Informationen finden Sie unter Angeben des Füllfaktors für einen Index.

DROP_EXISTING = { ON | OFF }

Gibt an, dass der benannte, bereits vorhandene räumliche Index gelöscht und neu erstellt wird. Der Standardwert lautet OFF.

AUF

Der vorhandene Index wird gelöscht und neu erstellt. Der angegebene Indexname muss mit einem derzeit vorhandenen Index identisch sein; Die Indexdefinition kann jedoch geändert werden. Sie können z. B. unterschiedliche Spalten, Sortierreihenfolge, Partitionsschema oder Indexoptionen angeben.
AUS

Wenn der angegebene Indexname bereits vorhanden ist, wird ein Fehler angezeigt.

Der Indextyp kann nicht mithilfe von DROP_EXISTING geändert werden.

ONLINE = AUS

Gibt an, dass zugrunde liegende Tabellen und zugeordnete Indizes während des Indexvorgangs nicht für Abfragen und Datenänderungen verfügbar sind. In dieser Version von SQL Server werden Onlineindexbuilds für JSON-Indizes nicht unterstützt. Wenn diese Option auf ON für einen JSON-Index festgelegt ist, wird ein Fehler ausgelöst. Entweder ONLINE weglassen oder ONLINE auf OFF setzen.

Ein Offline-Indexvorgang, der einen JSON-Index erstellt, neu erstellt oder löscht, erwirbt eine Sperre für eine Schemaänderung (Sch-M) an der Tabelle. Dadurch wird verhindert, dass Benutzer für die Dauer des Vorgangs auf die zugrunde liegende Tabelle zugreifen können.

Onlineindexvorgänge sind in jeder Edition von SQL Server nicht verfügbar.

Eine Liste der Features, die von den SQL Server-Editionen auf Windows unterstützt werden, finden Sie hier:

ALLOW_ROW_LOCKS = { EIN | AUS }

Gibt an, ob Zeilensperren zulässig sind. Der Standardwert lautet ON.

AUF

Zeilensperren sind beim Zugriff auf den Index zulässig. Das Datenbank-Engine bestimmt, wann Zeilensperren verwendet werden.
AUS

Zeilensperren werden nicht verwendet.

ALLOW_PAGE_LOCKS = { EIN | AUS }

Gibt an, ob Seitensperren zulässig sind. Der Standardwert lautet ON.

AUF

Seitensperren sind beim Zugriff auf den Index zulässig. Das Datenbank-Engine bestimmt, wann Seitensperren verwendet werden.
AUS

Seitensperren werden nicht verwendet.

MAXDOP = max_degree_of_parallelism

Überschreibt die max degree of parallelism Konfigurationsoption für die Dauer des Indexvorgangs. Wird verwendet MAXDOP , um die Anzahl der Prozessoren zu begrenzen, die in einer parallelen Planausführung verwendet werden. Das Maximum beträgt 64 Prozessoren.

Von Bedeutung

Obwohl die MAXDOP Option syntaktisch unterstützt wird, CREATE SPATIAL INDEX wird derzeit immer nur ein einzelner Prozessor verwendet.

max_degree_of_parallelism kann einer der folgenden Werte sein:

Wert	BESCHREIBUNG
`1`	Unterdrückt das Generieren paralleler Pläne.
`>1`	Beschränkt die maximale Anzahl der Prozessoren, die bei einem parallelen Indexvorgang verwendet werden, je nach aktueller Systemauslastung auf die angegebene Zahl oder einen niedrigeren Wert.
`0` (Standardwert)	Verwendet abhängig von der aktuellen Systemarbeitsauslastung die tatsächliche Anzahl von Prozessoren oder weniger Prozessoren.

Weitere Informationen finden Sie unter Konfigurieren von Parallelindexvorgängen.

Parallele Indexvorgänge sind nicht in jeder Edition von SQL Server verfügbar.

Eine Liste der Features, die von den SQL Server-Editionen auf Windows unterstützt werden, finden Sie hier:

DATA_COMPRESSION = { NONE | ZEILE | SEITE }

Bestimmt die Vom Index verwendete Datenkomprimierungsebene.

NICHTS

Keine Komprimierung für Daten durch den Index verwendet
ZEILE

Zeilenkomprimierung, die für Daten vom Index verwendet wird
SEITE

Seitenkomprimierung, die für Daten vom Index verwendet wird

Bemerkungen

Jede Option kann nur einmal pro CREATE JSON INDEX Anweisung angegeben werden. Wenn Sie ein Duplikat einer beliebigen Option angeben, wird ein Fehler ausgelöst.

[ ON { filegroup_name | "default" } ]

Wenn Sie eine Dateigruppe für einen JSON-Index angeben, wird der Index unabhängig vom Partitionierungsschema der Tabelle in dieser Dateigruppe platziert.

Weitere Informationen zum Erstellen von Indizes finden Sie im Abschnitt "Hinweise" in CREATE INDEX.

Mit einem JSON-Index unterstützte Prädikate

Suchvorgänge für JSON-Dokumente, die in einer JSON-Spalte in einer Tabelle enthalten sind, können optimiert werden, wenn in der JSON-Spalte ein JSON-Index vorhanden ist. Der JSON-Index wird in Abfragen mit verschiedenen JSON-funktionsbasierten Ausdrücken verwendet.

In den folgenden Beispielen wird die Sales.SalesOrderHeader-Tabelle in der AdventureWorks2022-Datenbank mit einer JSON-Spalte verwendet, die Info heißt. Die Info Spalte wird als JSON-Typ erstellt. Ein JSON-Index wird auch in der Info Spalte mit Standardeinstellungen erstellt. Das folgende Codebeispiel zeigt die CREATE JSON INDEX Anweisung:

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

Verwenden Sie für die Beispielsuchausdrücke die folgenden JSON-Dokumente als Daten:

Verkaufsauftragsnummer	Info
`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-Funktion

Verwenden Sie die JSON_PATH_EXISTS-Funktion , um zu testen, ob ein angegebener SQL/JSON-Pfad in einem JSON-Dokument vorhanden ist.

Diese Abfrage veranschaulicht JSON_PATH_EXISTS eine JSON-Spalte, die mithilfe eines JSON-Index optimiert werden kann.

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

JSON-Index wird mit JSON_PATH_EXISTS Prädikat und den folgenden Operatoren unterstützt:

Vergleichsoperatoren (=)
IS [NOT] NULL Prädikat (derzeit nicht unterstützt)

JSON_VALUE-Funktion

Verwenden Sie die JSON_VALUE , um den JSON-Text/Skalarwert in einem angegebenen SQL/JSON-Pfad in einem JSON-Dokument zu extrahieren. Die folgenden Abfragen zeigen, wie ein JSON_VALUE Ausdruck in einer JSON-Spalte mithilfe eines JSON-Index optimiert werden kann.

Gleichheitssuche nach einer JSON-Zeichenfolge in einer Objekteigenschaft:

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

Gleichheitssuche nach einer JSON-Nummer in einer Objekteigenschaft nach dem Konvertieren des Werts in einen Int-Datentyp :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
```
Bereichssuche nach einer JSON-Nummer in einer Objekteigenschaft nach dem Konvertieren des Werts in einen Int-Datentyp :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
```

Bereichssuche nach einer JSON-Nummer in einer Objekteigenschaft nach dem Konvertieren des Werts in einen Dezimaldatentyp :

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

Der JSON-Index wird mit einem JSON_VALUE Prädikat und den folgenden Operatoren unterstützt:

Vergleichsoperatoren (=)
LIKE Prädikat (derzeit nicht unterstützt)
IS [NOT] NULL Prädikat (derzeit nicht unterstützt)

JSON_CONTAINS-Funktion

Die JSON_CONTAINS-Funktion unterstützt eine einfache Suche nach JSON-Werten in einem JSON-Dokument, die einen JSON-Index verwenden kann, wenn sie in einer JSON-Spalte vorhanden ist. Diese Funktion kann verwendet werden, um zu testen, ob ein JSON-Skalarwert, -Objekt oder -Array im angegebenen SQL/JSON-Pfad in einem JSON-Dokument enthalten ist. Die als SQL-Skalartypen angegebenen Suchwerte werden entsprechend den vorhandenen SQL/JSON-Typkonvertierungen konvertiert. Diese Regeln werden im Verhaltensabschnitt definiert.

Anforderung

Für die Tabelle, die die JSON-Spalte enthält, ist ein Clusteringschlüssel erforderlich. Wenn der Clusterschlüssel nicht vorhanden ist, wird ein Fehler ausgelöst. Der Clusterschlüssel ist auf 31 Spalten beschränkt, und die maximale Größe des Indexschlüssels sollte kleiner als 128 Bytes sein.

Erlaubnisse

Der Benutzer muss ALTER über die Berechtigung für die Tabelle verfügen, oder Mitglied der festen Serverrolle sysadmin oder der festen Datenbankrollen db_ddladmin und db_owner sein.

Einschränkungen

Für die JSON-Index-Anweisung gelten die folgenden Einschränkungen:

In einer JSON-Spalte in einer Tabelle kann nur ein JSON-Index erstellt werden.
Sie können bis zu 249 JSON-Indizes in einer Tabelle erstellen. Das Erstellen mehrerer JSON-Indexe für eine bestimmte JSON-Spalte wird nicht unterstützt.
Für berechnete JSON-Spalten kann kein JSON-Index erstellt werden.
Ein JSON-Index kann nicht in JSON-Spalten in einer Ansicht, einer Tabellenwertvariable oder einer speicheroptimierten Tabelle erstellt werden.
Ein JSON-Index kann nur offline erstellt oder geändert werden.
JSON-Pfade können in der Indexdefinition nicht überlappen. Beispielsweise überlappen sich $a und $a.b, und sind in der CREATE JSON INDEX Anweisung nicht zulässig.
Zum Ändern von Pfaden muss der JSON-Index neu gerechnet werden.
JSON-Indizes werden in Indexhinweisen nicht unterstützt.
Die Datenkomprimierungsoption wird nicht unterstützt.

Beispiele

Ein. Erstellen eines JSON-Indexes in einer JSON-Spalte

Im folgenden Beispiel wird eine Tabelle mit dem Namen docs erstellt, die eine Spalte vom Typ json enthält, content. Anschließend wird in der json_content_index Spalte ein JSON-Index contenterstellt. Im Beispiel wird der JSON-Index im gesamten JSON-Dokument oder alle SQL/JSON-Pfade im JSON-Dokument erstellt.

DROP TABLE IF EXISTS docs;

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

Ein. Erstellen eines JSON-Indexes in einer JSON-Spalte mit bestimmten Pfaden

Im folgenden Beispiel wird eine Tabelle mit dem Namen docs erstellt, die eine Spalte vom Typ json enthält, content. Anschließend wird in der json_content_index Spalte ein JSON-Index contenterstellt. Im Beispiel wird der JSON-Index für bestimmte SQL/JSON-Pfade im JSON-Dokument erstellt.
Im Beispiel wird auch der Index FILLFACTOR auf 80 gesetzt.

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);

Freigeben über