SKAPA JSON-INDEX (Transact-SQL)

Gäller för: Förhandsversion av SQL Server 2025 (17.x)

Skapar ett JSON-index i en angiven tabell och kolumn i förhandsversionen av SQL Server 2025 (17.x).

JSON-indexer

• Kan skapas innan det finns data i tabellen.
• Kan skapas på tabeller i en annan databas genom att ange ett kvalificerat databasnamn.
• Kräv att tabellen har en klustrad primärnyckel.
• Det går inte att ange i indexerade vyer.

Transact-SQL syntaxkonventioner

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

Argumentpunkter

indexnamn

Namnet på indexet. Indexnamn måste vara unika i en tabell men behöver inte vara unika i en databas. Indexnamn måste följa reglerna för identifierare.

• ON-objekt <> ( json_column_name )

  Anger det objekt (databas, schema eller tabell) som indexet ska skapas på och namnet på json-kolumnen .

• json_column_name

  Namnet på kolumnen med json-datatypen i table_name som innehåller noll eller fler av de angivna SQL/JSON-sökvägarna.

• sql_json_path

  Den SQL/JSON-path som måste extraheras och indexeras från json_column_name. Standardvärdet för sql_json_path är $.

  • Rekursivt indexerar alla nycklar/värden från den angivna sökvägen och framåt.
  • Stöder upp till 128 nivåer i JSON-dokumentsökvägen.
  • Tillåter inte överlappning.

  Till exempel $.a och $.a.b generera ett fel, eftersom sökvägen $.a rekursivt innehåller alla sökvägar och användar avsikten är oklart.

PÅ filegroup_name

Skapar det angivna indexet för den angivna filgruppen. Om ingen plats anges och tabellen inte partitioneras använder indexet samma filgrupp som den underliggande tabellen. Filgruppen måste redan finnas.

PÅ "standard"

Skapar det angivna indexet för standardfilgruppen.

Termen standard i den här kontexten är inte ett nyckelord. Det är en identifierare för standardfilgruppen och måste avgränsas, som i ON "default" eller ON [default]. Om "default" anges måste alternativet QUOTED_IDENTIFIER vara ON för den aktuella sessionen. Det här är standardinställningen. Mer information finns i SET QUOTED_IDENTIFIER.

<object>:: =

Det fullständigt kvalificerade eller icke-fullständigt kvalificerade objekt som ska indexeras.

• database_name

  Namnet på databasen.

• schema_name

  Namnet på schemat som tabellen tillhör.

• table_name

  Namnet på den tabell som ska indexeras.

OPTIMIZE_FOR_ARRAY_SEARCH = { ON | AV }

Anger om matrissökningar är optimerade i JSON-indexet. Standardvärdet är OFF.

FILLFACTOR = fillfactor

Anger en procentandel som anger hur full databasmotorn ska göra lövnivån för varje indexsida när index skapas eller återskapas. fillfactor måste vara ett heltalsvärde från 1 till 100. Standardvärdet är 0. Om fillfactor är 100 eller 0skapar databasmotorn index med lövsidor fyllda till kapacitet.

Inställningen FILLFACTOR gäller endast när indexet skapas eller återskapas. Databasmotorn behåller inte dynamiskt den angivna procentandelen tomt utrymme på sidorna. Om du vill visa fyllningsfaktorinställningen använder du katalogvyn sys.indexes .

Att skapa ett grupperat index med mindre FILLFACTOR än 100 påverkar mängden lagringsutrymme som data upptar, eftersom databasmotorn omdistribuerar data när det skapar det klustrade indexet.

Mer information finns i Ange fyllningsfaktor för ett index.

DROP_EXISTING = { ON | AV }

Anger att det namngivna, befintliga JSON-indexet tas bort och återskapas. Standardvärdet är OFF.

• PÅ

  Det befintliga indexet tas bort och återskapas. Det angivna indexnamnet måste vara samma som ett befintligt index. Indexdefinitionen kan dock ändras. Du kan till exempel ange olika kolumner, sorteringsordning, partitionsschema eller indexalternativ.

• AV

  Ett fel visas om det angivna indexnamnet redan finns.

Indextypen kan inte ändras med hjälp DROP_EXISTINGav .

ONLINE = AV

Anger att underliggande tabeller och associerade index inte är tillgängliga för frågor och dataändringar under indexåtgärden. I den här versionen av SQL Server stöds inte onlineindexversioner för JSON-index. Om det här alternativet är inställt på ON för ett JSON-index utlöses ett fel. ONLINE Utelämna alternativet eller ange ONLINE till OFF.

En offlineindexåtgärd som skapar, återskapar eller tar bort ett JSON-index förvärvar ett lås för schemaändring (Sch-M) på tabellen. Detta förhindrar all användaråtkomst till den underliggande tabellen under hela åtgärden.

Onlineindexåtgärder är inte tillgängliga i varje version av SQL Server.

En lista över funktioner som stöds av versionerna av SQL Server i Windows finns i:

• Utgåvor och funktioner som stöds i förhandsversionen av SQL Server 2025
• Utgåvor och funktioner som stöds i SQL Server 2022
• Utgåvor och funktioner som stöds i SQL Server 2019
• Utgåvor och funktioner som stöds i SQL Server 2017
• Utgåvor och funktioner som stöds i SQL Server 2016

ALLOW_ROW_LOCKS = { ON | AV }

Anger om radlås tillåts. Standardvärdet är ON.

• PÅ

  Radlås tillåts vid åtkomst till indexet. Databasmotorn avgör när radlås används.

• AV

  Radlås används inte.

ALLOW_PAGE_LOCKS = { ON | AV }

Anger huruvida sidlås är tillåtna. Standardvärdet är ON.

• PÅ

  Sidlås tillåts vid åtkomst till indexet. Databasmotorn avgör när sidlås används.

• AV

  Sidlås används inte.

MAXDOP = max_degree_of_parallelism

Åsidosätter max degree of parallelism konfigurationsalternativet under hela indexåtgärden. Använd MAXDOP för att begränsa antalet processorer som används i en parallell plankörning. Maximalt är 64 processorer.

max_degree_of_parallelism kan vara något av följande värden.

Mer information finns i Konfigurera parallella indexåtgärder.

Parallella indexåtgärder är inte tillgängliga i varje version av SQL Server.

En lista över funktioner som stöds av versionerna av SQL Server i Windows finns i:

• Utgåvor och funktioner som stöds i förhandsversionen av SQL Server 2025
• Utgåvor och funktioner som stöds i SQL Server 2022
• Utgåvor och funktioner som stöds i SQL Server 2019
• Utgåvor och funktioner som stöds i SQL Server 2017
• Utgåvor och funktioner som stöds i SQL Server 2016

DATA_COMPRESSION = { NONE | RAD | SIDOR }

Avgör vilken nivå av datakomprimering som används av indexet.

• INGEN

  Ingen komprimering används på data av indexet

• RAD

  Radkomprimering används på data av indexet

• SIDA

  Sidkomprimering används på data i indexet

Anmärkningar

Varje alternativ kan bara anges en gång per CREATE JSON INDEX instruktion. Om du anger en dubblett av ett alternativ genereras ett fel.

[ PÅ { filegroup_name | "default" } ]

Om du anger en filgrupp för ett JSON-index placeras indexet i den filgruppen, oavsett tabellens partitioneringsschema.

Mer information om hur du skapar index finns i avsnittet Kommentarer i CREATE INDEX.

Predikat som stöds med ett JSON-index

Sökningsåtgärder i JSON-dokument som finns i en json-kolumn i en tabell kan optimeras om det finns ett JSON-index i json-kolumnen . JSON-indexet används i frågor med olika JSON-funktionsbaserade uttryck.

I följande exempel används tabellen Sales.SalesOrderHeader i AdventureWorks2022 databasen med en json-kolumn med namnet Info. Kolumnen Info skapas som en json-typ . Ett JSON-index skapas också i Info kolumnen med standardinställningar. Följande kodexempel visar den CREATE JSON INDEX-instruktionen:

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

För exempelsökningsuttrycken använder du följande JSON-dokument som data:

JSON_PATH_EXISTS-funktionen

Använd funktionen JSON_PATH_EXISTS för att testa om det finns en angiven SQL/JSON-sökväg i ett JSON-dokument.

Den här frågan visar JSON_PATH_EXISTS på en json-kolumn som kan optimeras med hjälp av ett JSON-index:

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

JSON-index stöds med JSON_PATH_EXISTS predikat och följande operatorer:

• Jämförelseoperatorer (=)
• IS [NOT] NULL predikat (stöds inte för närvarande)

JSON_VALUE-funktionen

Använd JSON_VALUE för att extrahera JSON-text/skalärvärdet i en angiven SQL/JSON-sökväg i ett JSON-dokument. Följande frågor visar hur ett JSON_VALUE uttryck i en json-kolumn kan optimeras med hjälp av ett JSON-index.

• Likhetssökning efter en JSON-sträng i en objektegenskap:

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

• Likhetssökning efter ett JSON-nummer i en objektegenskap efter konvertering av värdet till en int-datatyp :

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

• Intervallsökning efter ett JSON-nummer i en objektegenskap efter konvertering av värdet till en int-datatyp :

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

• Intervallsökning efter ett JSON-nummer i en objektegenskap efter konvertering av värdet till en decimaldatatyp :

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

JSON-indexet stöds med ett JSON_VALUE predikat och följande operatorer:

• Jämförelseoperatorer (=)
• LIKE predikat (stöds inte för närvarande)
• IS [NOT] NULL predikat (stöds inte för närvarande)

funktionen JSON_CONTAINS

Funktionen JSON_CONTAINS stöder enkel sökning av JSON-värden i ett JSON-dokument som kan använda ett JSON-index om det finns i en json-kolumn . Den här funktionen kan användas för att testa om ett JSON-skalärt värde, objekt eller matris finns i den angivna SQL/JSON-sökvägen i ett JSON-dokument. Sökvärdena som anges som SQL-skalärtyper konverteras enligt befintliga SQL/JSON-typkonverteringar. Dessa regler definieras i avsnittet beteende.

Krav

En klustringsnyckel krävs i tabellen som innehåller JSON-kolumnen. Ett fel uppstår om klustringsnyckeln saknas. Klustringsnyckeln är begränsad till 31 kolumner och indexnyckelns maximala storlek bör vara mindre än 128 byte.

Behörigheter

Användaren måste ha ALTER behörighet i tabellen eller vara medlem i den fasta serverrollen sysadmin eller db_ddladmin och db_owner fasta databasroller.

Begränsningar

Följande begränsningar finns för JSON-indexsatsen:

• Endast ett JSON-index kan skapas på en json-kolumn i en tabell.
• Du kan skapa upp till 249 JSON-index i en tabell. Det går inte att skapa fler än ett JSON-index i en specifik JSON-kolumn.
• Det går inte att skapa ett JSON-index på beräknade json-kolumner .
• Det går inte att skapa ett JSON-index på json-kolumner i en vy, tabellvärdesvariabel eller minnesoptimerad tabell.
• Ett JSON-index kan bara skapas eller ändras offline.
• JSON-sökvägar kan inte överlappa indexdefinitionen. Till exempel $a och $a.b överlappar, och tillåts inte i instruktionen CREATE JSON INDEX.
• Ändring av sökvägar kräver att JSON-indexet återskapas.
• JSON-index stöds inte i indextips.
• Datakomprimeringsalternativet stöds inte.

Exempel

A. Skapa ett JSON-index i en JSON-kolumn

I följande exempel skapas en tabell med namnet docs som innehåller en json-typkolumn , content. Exemplet skapar sedan ett JSON-index, json_content_index, i content kolumnen. I exemplet skapas json-indexet för hela JSON-dokumentet eller alla SQL/JSON-sökvägar i JSON-dokumentet.

DROP TABLE IF EXISTS docs;

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

CREATE JSON INDEX json_content_index
    ON docs (content);

A. Skapa ett JSON-index på en JSON-kolumn med specifika sökvägar

I följande exempel skapas en tabell med namnet docs som innehåller en json-typkolumn , content. Exemplet skapar sedan ett JSON-index, json_content_index, i content kolumnen. I exemplet skapas json-indexet för specifika SQL/JSON-sökvägar i JSON-dokumentet.
Exemplet anger även indexet FILLFACTOR till 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 med matrissökningsoptimering

I följande exempel returneras JSON-index för tabellen dbo.Customers. JSON-indexet skapas med optimeringsalternativet för matrissökning aktiverat.

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

Relaterat innehåll

• DROP-INDEX (Transact-SQL)
• JSON-data i SQL-Servern
• HÄNDELSEDATA (Transact-SQL)
• sys.index_columns (Transact-SQL)
• sys.indexes (Transact-SQL)