MAAK JSON INDEKS (Transact-SQL)

Van toepassing op: SQL Server 2025 (17.x) Preview

Hiermee maakt u een JSON-index voor een opgegeven tabel en kolom in SQL Server 2025 (17.x) Preview.

JSON-indexen:

• Kan worden gemaakt voordat er gegevens in de tabel staan.
• Kan worden gemaakt op tabellen in een andere database door een gekwalificeerde databasenaam op te geven.
• Vereisen dat de tabel een geclusterde primaire sleutel heeft.
• Kan niet worden opgegeven voor geïndexeerde weergaven.

Transact-SQL syntaxis-conventies

Syntaxis

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

Argumenten

indexnaam

De naam van de index. Indexnamen moeten uniek zijn binnen een tabel, maar hoeven niet uniek te zijn binnen een database. Indexnamen moeten de regels van id's volgen.

• ON-object <> ( json_column_name )

  Hiermee geeft u het object (database, schema of tabel) waarop de index moet worden gemaakt en de naam van de json-kolom .

• json_column_name

  De naam van de kolom van het JSON-gegevenstype in table_name die nul of meer van de opgegeven SQL/JSON-paden bevat.

• sql_json_path

  Het SQL/JSON-pad dat moet worden geëxtraheerd en geïndexeerd vanuit json_column_name. De standaardwaarde sql_json_path is $.

  • Recursief indexeert alle sleutels/waarden vanaf het opgegeven pad.
  • Ondersteunt maximaal 128 niveaus in het JSON-documentpad.
  • Staat overlapping niet toe.

  $.a en $.a.b veroorzaken een fout, omdat het pad $.a recursief alle paden omvat en de intentie van de gebruiker onduidelijk is.

OP filegroup_name

Hiermee maakt u de opgegeven index voor de opgegeven bestandsgroep. Als er geen locatie is opgegeven en de tabel niet is gepartitioneerd, gebruikt de index dezelfde bestandsgroep als de onderliggende tabel. De bestandsgroep moet al bestaan.

AAN "standaard"

Hiermee maakt u de opgegeven index voor de standaardbestandsgroep.

De standaardterm is in deze context geen trefwoord. Het is een id voor de standaardbestandsgroep en moet worden gescheiden, zoals in ON "default" of ON [default]. Als "default" dit is opgegeven, moet de QUOTED_IDENTIFIER optie voor de huidige sessie zijn ON . Dit is de standaardinstelling. Zie SET QUOTED_IDENTIFIERvoor meer informatie.

<object>:: =

Het volledig gekwalificeerde of niet-gekwalificeerde object dat moet worden geïndexeerd.

• database_name

  De naam van de database.

• schema_name

  De naam van het schema waartoe de tabel behoort.

• table_name

  De naam van de tabel die moet worden geïndexeerd.

OPTIMIZE_FOR_ARRAY_SEARCH = { ON | UIT }

Hiermee geeft u op of matrixzoekopdrachten zijn geoptimaliseerd in de JSON-index. De standaardwaarde is OFF.

FILLFACTOR = fillfactor

Hiermee geeft u een percentage op dat aangeeft hoe vol de database-engine het bladniveau van elke indexpagina moet maken tijdens het maken of opnieuw opbouwen van de index. fillfactor moet een geheel getal zijn van 1 tot 100. De standaardwaarde is 0. Als fillfactor100 of 0 is, maakt het databasesysteem indexen met bladpagina's die volledig gevuld zijn.

De instelling FILLFACTOR is alleen van toepassing wanneer de index wordt gemaakt of opnieuw wordt opgebouwd. De database-engine behoudt niet dynamisch het opgegeven percentage lege ruimte op de pagina's. Als u de instelling voor de vulfactor wilt weergeven, gebruikt u de catalogusweergave sys.indexes .

Het maken van een geclusterde index met een FILLFACTOR minder dan 100 beïnvloedt de hoeveelheid opslagruimte die de gegevens in beslag nemen, omdat de Database Engine de gegevens herdistribueert wanneer de geclusterde index wordt aangemaakt.

Zie Vulfactor opgeven voor een index-voor meer informatie.

DROP_EXISTING = { ON | UIT }

Hiermee geeft u op dat de benoemde, bestaande JSON-index wordt verwijderd en opnieuw wordt opgebouwd. De standaardwaarde is OFF.

• OP

  De bestaande index wordt verwijderd en opnieuw opgebouwd. De opgegeven indexnaam moet hetzelfde zijn als een bestaande index; De indexdefinitie kan echter worden gewijzigd. U kunt bijvoorbeeld verschillende kolommen, sorteervolgorde, partitieschema of indexopties opgeven.

• UIT

  Er wordt een fout weergegeven als de opgegeven indexnaam al bestaat.

Het indextype kan niet worden gewijzigd met behulp van DROP_EXISTING.

ONLINE = UIT

Hiermee geeft u op dat onderliggende tabellen en bijbehorende indexen niet beschikbaar zijn voor query's en gegevenswijziging tijdens de indexbewerking. In deze versie van SQL Server worden online index builds niet ondersteund voor JSON-indexen. Als deze optie is ingesteld ON op een JSON-index, wordt er een fout gegenereerd. Laat de ONLINE optie weg of stel deze in ONLINE op OFF.

Een offline indexbewerking die een JSON-index maakt, herbouwt of verwijdert, verkrijgt een schemawijzigingsvergrendeling (Sch-M) op de tabel. Hiermee voorkomt u dat alle gebruikers toegang hebben tot de onderliggende tabel voor de duur van de bewerking.

Online indexbewerkingen zijn niet beschikbaar in elke editie van SQL Server.

Zie voor een lijst met functies die worden ondersteund door de edities van SQL Server in Windows:

• Edities en ondersteunde functies van SQL Server 2025 Preview
• Edities en ondersteunde functies van SQL Server 2022
• Edities en ondersteunde functies van SQL Server 2019
• Edities en ondersteunde functies van SQL Server 2017
• Edities en ondersteunde functies van SQL Server 2016

ALLOW_ROW_LOCKS = { AAN | UIT }

Hiermee geeft u op of rijvergrendelingen zijn toegestaan. De standaardwaarde is ON.

• OP

  Rijvergrendelingen zijn toegestaan bij toegang tot de index. De database-engine bepaalt wanneer rijvergrendelingen worden gebruikt.

• UIT

  Rijvergrendelingen worden niet gebruikt.

ALLOW_PAGE_LOCKS = { AAN | UIT }

Hiermee geeft u op of paginavergrendelingen zijn toegestaan. De standaardwaarde is ON.

• OP

  Paginavergrendelingen zijn toegestaan bij toegang tot de index. De database-engine bepaalt wanneer paginavergrendelingen worden gebruikt.

• UIT

  Paginavergrendelingen worden niet gebruikt.

MAXDOP = max_degree_of_parallelism

Hiermee wordt de max degree of parallelism configuratieoptie voor de duur van de indexbewerking overschreven. Gebruik MAXDOP dit om het aantal processors dat wordt gebruikt in een parallelle uitvoering van een plan te beperken. Het maximum is 64 processoren.

max_degree_of_parallelism kan een van de volgende waarden zijn.

Zie Parallelle indexbewerkingen configurerenvoor meer informatie.

Parallelle indexbewerkingen zijn niet beschikbaar in elke editie van SQL Server.

Zie voor een lijst met functies die worden ondersteund door de edities van SQL Server in Windows:

• Edities en ondersteunde functies van SQL Server 2025 Preview
• Edities en ondersteunde functies van SQL Server 2022
• Edities en ondersteunde functies van SQL Server 2019
• Edities en ondersteunde functies van SQL Server 2017
• Edities en ondersteunde functies van SQL Server 2016

DATA_COMPRESSION = { NONE | RIJ | PAGE }

Bepaalt het gegevenscompressieniveau dat door de index wordt gebruikt.

• GEEN

  Er wordt geen compressie toegepast op gegevens door de index

• RIJ-

  Rijcompressie gebruikt door de index op gegevens

• BLADZIJDE

  Paginacompressie toegepast op gegevens door middel van de index

Opmerkingen

Elke optie kan slechts één keer per CREATE JSON INDEX instructie worden opgegeven. Als u een duplicaat van een optie opgeeft, wordt er een fout gegenereerd.

[ AAN { filegroup_name | "default" } ]

Als u een bestandsgroep opgeeft voor een JSON-index, wordt de index op die bestandsgroep geplaatst, ongeacht het partitioneringsschema van de tabel.

Zie de sectie Opmerkingen in CREATE INDEX voor meer informatie over het maken van indexen.

Predicaten die worden ondersteund met een JSON-index

Zoekbewerkingen op JSON-documenten in een json-kolom in een tabel kunnen worden geoptimaliseerd als er een JSON-index bestaat in de json-kolom . De JSON-index wordt gebruikt in query's met verschillende expressies op basis van JSON-functies.

In de volgende voorbeelden wordt de Sales.SalesOrderHeader tabel in de AdventureWorks2022 database gebruikt met een json-kolom genaamd Info. De Info kolom wordt gemaakt als json-type . Er wordt ook een JSON-index gemaakt in de Info kolom met standaardinstellingen. In het volgende codevoorbeeld ziet u de CREATE JSON INDEX instructie:

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

Gebruik voor de voorbeeldzoekexpressies de volgende JSON-documenten als gegevens:

JSON_PATH_EXISTS functie

Gebruik de JSON_PATH_EXISTS-functie om te testen of er een opgegeven SQL/JSON-pad bestaat in een JSON-document.

Deze query demonstreert JSON_PATH_EXISTS op een json-kolom die kan worden geoptimaliseerd met behulp van een JSON-index:

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

JSON-index wordt ondersteund met JSON_PATH_EXISTS predicaat en de volgende operators:

• Vergelijkingsoperatoren (=)
• IS [NOT] NULL predicaat (momenteel niet ondersteund)

JSON_VALUE functie

Gebruik de JSON_VALUE om de JSON-tekst/scalaire waarde in een opgegeven SQL/JSON-pad in een JSON-document te extraheren. De volgende query's laten zien hoe een JSON_VALUE expressie in een json-kolom kan worden geoptimaliseerd met behulp van een JSON-index.

• Gelijkheid zoeken naar een JSON-tekenreeks in een objecteigenschap:

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

• Gelijkheid zoeken naar een JSON-getal in een objecteigenschap na het converteren van de waarde naar een gegevenstype int :

  SELECT *
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
  

• Zoek in het bereik naar een JSON-getal in een objecteigenschap nadat de waarde is geconverteerd naar een gegevenstype int :

  SELECT *
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
  

• Zoeken naar een JSON-getal in een objecteigenschap nadat de waarde is geconverteerd naar een decimaal gegevenstype:

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

De JSON-index wordt ondersteund met een JSON_VALUE predicaat en de volgende operators:

• Vergelijkingsoperatoren (=)
• LIKE predicaat (momenteel niet ondersteund)
• IS [NOT] NULL predicaat (momenteel niet ondersteund)

JSON_CONTAINS functie

De functie JSON_CONTAINS ondersteunt het eenvoudig doorzoeken van JSON-waarden in een JSON-document dat een JSON-index kan gebruiken als deze aanwezig is in een json-kolom . Deze functie kan worden gebruikt om te testen of een scalaire JSON-waarde, -object of -matrix is opgenomen in het opgegeven SQL/JSON-pad in een JSON-document. De zoekwaarden die zijn opgegeven als scalair SQL-typen, worden geconverteerd volgens de bestaande SQL/JSON-typeconversies. Deze regels worden gedefinieerd in de sectie Gedrag.

Voorwaarde

Een clustersleutel is vereist in de tabel die de JSON-kolom bevat. Er treedt een fout op als de clusteringsleutel ontbreekt. De clusteringsleutel is beperkt tot 31 kolommen en de maximale grootte van de indexsleutel moet kleiner zijn dan 128 bytes.

Machtigingen

De gebruiker moet ALTER machtigingen hebben voor de tabel, of lid zijn van de vaste serverrol sysadmin, of lid zijn van de vaste databaserollen db_ddladmin en db_owner.

Beperkingen

De volgende beperkingen gelden voor de JSON-indexinstructie:

• Er kan slechts één JSON-index worden gemaakt in een json-kolom in een tabel.
• U kunt maximaal 249 JSON-indexen maken in een tabel. Het maken van meer dan één JSON-index voor een specifieke JSON-kolom wordt niet ondersteund.
• Er kan geen JSON-index worden gemaakt voor berekende json-kolommen .
• Een JSON-index kan niet worden gemaakt in json-kolommen in een weergave, tabelwaardevariabele of geoptimaliseerde tabel met geheugen.
• Een JSON-index kan alleen op een offline manier worden gemaakt of gewijzigd.
• JSON-paden kunnen niet overlappen in de indexdefinitie. $a en $a.b overlappen bijvoorbeeld en zijn niet toegestaan in de CREATE JSON INDEX instructie.
• Voor het wijzigen van paden moet de JSON-index opnieuw worden samengesteld.
• JSON-indexen worden niet ondersteund in indexhints.
• De optie voor gegevenscompressie wordt niet ondersteund.

Voorbeelden

Eén. Een JSON-index maken in een JSON-kolom

In het volgende voorbeeld wordt een tabel gemaakt met de naam docs die een kolom van het json-type bevat. content In het voorbeeld wordt vervolgens een JSON-index gemaakt, json_content_indexin de content kolom. In het voorbeeld wordt de json-index gemaakt voor het hele JSON-document of alle SQL/JSON-paden in het JSON-document.

DROP TABLE IF EXISTS docs;

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

CREATE JSON INDEX json_content_index
    ON docs (content);

Eén. Een JSON-index maken in een JSON-kolom met specifieke paden

In het volgende voorbeeld wordt een tabel gemaakt met de naam docs die een kolom van het json-type bevat. content In het voorbeeld wordt vervolgens een JSON-index gemaakt, json_content_indexin de content kolom. In het voorbeeld wordt de json-index gemaakt voor specifieke SQL/JSON-paden in het JSON-document.
In het voorbeeld wordt de index FILLFACTOR ook ingesteld op 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. JSON-index met optimalisatie van matrixzoekopdrachten

In het volgende voorbeeld worden JSON-indexen voor de tabel dbo.Customersgeretourneerd. De JSON-index wordt gemaakt met de optie voor optimalisatie van matrixzoekopdrachten ingeschakeld.

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

Verwante inhoud

• DROP INDEX (Transact-SQL)
• JSON-gegevens in SQL Server
• GEBEURTENISGEGEVENS (Transact-SQL)
• sys.index_columns (Transact-SQL)
• sys.indexes (Transact-SQL)