UTWÓRZ INDEKS JSON (Transact-SQL)

Dotyczy: SQL Server 2025 (17.x)

Tworzy indeks JSON na określonej tabeli i kolumnie w SQL Server 2025 (17.x).

Indeksy JSON:

Można utworzyć przed pojawieniem się danych w tabeli.
Można utworzyć w tabelach w innej bazie danych, określając kwalifikowaną nazwę bazy danych.
Wymagaj, aby tabela miała klasterowany klucz podstawowy.
Nie można określić w widokach indeksowanych.

Uwaga / Notatka

Tworzenie indeksów JSON jest obecnie w wersji podglądowej i dostępne tylko w SQL Server 2025 (17.x).

Składnia

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

Argumenty (w programowaniu)

nazwa_indeksu

Nazwa indeksu. Nazwy indeksów muszą być unikatowe w tabeli, ale nie muszą być unikatowe w bazie danych. Nazwy indeksów muszą być zgodne z regułami identyfikatorów.

Obiekt< ON >( json_column_name )

Określa obiekt (bazę danych, schemat lub tabelę), na którym ma zostać utworzony indeks, oraz nazwę kolumny json .
json_column_name

Nazwa kolumny typu danych JSON , która table_name zawiera zero lub więcej określonych ścieżek SQL/JSON.
sql_json_path

Ścieżka SQL/JSON, która musi zostać wyodrębniona i zindeksowana z json_column_name. Wartość domyślna to sql_json_path$.
- Rekursywnie indeksuje wszystkie klucze i wartości od określonej ścieżki dalej.
- Obsługuje maksymalnie 128 poziomów w ścieżce dokumentu JSON.
- Nie zezwala na nakładanie się.
Na przykład $.a i $.a.b zgłaszają błąd, ponieważ ścieżka $.a obejmuje rekurencyjnie wszystkie ścieżki, a intencja użytkownika jest niejasna.

W filegroup_name

Tworzy określony indeks w określonej grupie plików. Jeśli nie określono lokalizacji i tabela nie jest partycjonowana, indeks używa tej samej grupy plików co tabela bazowa. Grupa plików musi już istnieć.

W POZYCJI "default"

Tworzy określony indeks w domyślnej grupie plików.

Termin domyślny, w tym kontekście, nie jest słowem kluczowym. Jest to identyfikator domyślnej grupy plików i musi być rozdzielany, tak jak w pliku ON "default" lub ON [default]. Jeśli "default" jest określona QUOTED_IDENTIFIER , opcja musi być ON dla bieżącej sesji. Jest to ustawienie domyślne. Aby uzyskać więcej informacji, zobacz SET QUOTED_IDENTIFIER.

<obiekt>:: =

W pełni kwalifikowany lub niew pełni kwalifikowany obiekt do indeksowania.

database_name

Nazwa bazy danych.
schema_name

Nazwa schematu, do którego należy tabela.
table_name

Nazwa tabeli do indeksowania.

OPTIMIZE_FOR_ARRAY_SEARCH = { ON | WYŁ. }

Określa, czy wyszukiwania tablic są zoptymalizowane w indeksie JSON. Wartość domyślna to OFF.

FILLFACTOR = wypełnienie

Określa wartość procentową wskazującą, jak pełny aparat bazy danych powinien ustawić poziom liścia każdej strony indeksu podczas tworzenia lub odbudowy indeksu. fillfactor musi być wartością całkowitą z 1 do 100. Wartość domyślna to 0. Jeśli fillfactor to 100 lub 0, aparat bazy danych tworzy indeksy ze stronami liści wypełnionymi do pełnej pojemności.

Uwaga / Notatka

Wartości współczynnika wypełnienia 0 i 100 są identyczne we wszystkich aspektach.

Ustawienie FILLFACTOR ma zastosowanie tylko podczas tworzenia lub odbudowy indeksu. Aparat bazy danych nie zachowuje dynamicznie określonego procentu pustego miejsca na stronach. Aby wyświetlić ustawienie współczynnika wypełnienia, użyj widoku wykazu sys.indexes .

Utworzenie indeksu klastrowanego z FILLFACTOR mniejszym niż 100 wpływa na ilość miejsca zajmowanego przez dane, ponieważ aparat bazy danych redystrybuuje dane podczas tworzenia indeksu klastrowanego.

Aby uzyskać więcej informacji, zobacz Określanie współczynnika wypełnienia dla indeksu.

DROP_EXISTING = { ON | WYŁ. }

Określa, że nazwany, wstępnie istniejących indeksów JSON jest porzucony i przebudowany. Wartość domyślna to OFF.

NA

Istniejący indeks jest porzucany i odbudowywany. Określona nazwa indeksu musi być taka sama jak aktualnie istniejący indeks; można jednak zmodyfikować definicję indeksu. Można na przykład określić różne kolumny, kolejność sortowania, schemat partycji lub opcje indeksu.
WYŁĄCZONE

Jeśli określona nazwa indeksu już istnieje, zostanie wyświetlony błąd.

Nie można zmienić typu indeksu przy użyciu polecenia DROP_EXISTING.

ONLINE = WYŁĄCZONE

Określa, że tabele bazowe i skojarzone indeksy nie są dostępne dla zapytań i modyfikacji danych podczas operacji indeksu. W tej wersji programu SQL Server kompilacje indeksów online nie są obsługiwane w przypadku indeksów JSON. Jeśli ta opcja jest ustawiona na ON dla indeksu JSON, zostanie zgłoszony błąd. Pomiń opcję ONLINE albo ustaw ONLINE na OFF.

Operacja indeksu w trybie offline, która tworzy, kompiluje lub usuwa indeks JSON, uzyskuje blokadę modyfikacji schematu (Sch-M) w tabeli. Zapobiega to dostępowi wszystkich użytkowników do tabeli bazowej przez czas trwania operacji.

Operacje indeksowania online nie są dostępne w każdej wersji programu SQL Server.

Aby uzyskać listę funkcji obsługiwanych przez wersje programu SQL Server w systemie Windows, zobacz:

ALLOW_ROW_LOCKS = { ON | WYŁ. }

Określa, czy blokady wierszy są dozwolone. Wartość domyślna to ON.

NA

Blokady wierszy są dozwolone podczas uzyskiwania dostępu do indeksu. Aparat bazy danych określa, kiedy są używane blokady wierszy.
WYŁĄCZONE

Blokady wierszy nie są używane.

ALLOW_PAGE_LOCKS = { ON | WYŁ. }

Określa, czy blokady strony są dozwolone. Wartość domyślna to ON.

NA

Blokady stron są dozwolone podczas uzyskiwania dostępu do indeksu. Aparat bazy danych określa, kiedy są używane blokady strony.
WYŁĄCZONE

Blokady stron nie są używane.

MAXDOP = max_degree_of_parallelism

Opcja konfiguracji max degree of parallelism jest zastępowana na czas trwania operacji indeksowania. Użyj MAXDOP polecenia , aby ograniczyć liczbę procesorów używanych w równoległym wykonywaniu planu. Maksymalna wartość to 64 procesory.

Ważne

MAXDOP Chociaż opcja jest obsługiwana syntatycznie, CREATE JSON INDEX obecnie zawsze używa tylko jednego procesora.

max_degree_of_parallelism może być jedną z następujących wartości.

Wartość	Opis
`1`	Zatrzymuje generowanie planu równoległego.
`>1`	Ogranicza maksymalną liczbę procesorów używanych w operacji indeksowania równoległego do określonej liczby lub mniejszej na podstawie bieżącego obciążenia systemu.
`0` (ustawienie domyślne)	Używa rzeczywistej liczby procesorów lub mniej na podstawie bieżącego obciążenia systemu.

Aby uzyskać więcej informacji, zobacz Konfigurowanie operacji indeksowania równoległego.

Operacje indeksowania równoległego nie są dostępne w każdej wersji programu SQL Server.

Aby uzyskać listę funkcji obsługiwanych przez wersje programu SQL Server w systemie Windows, zobacz:

DATA_COMPRESSION = { NONE | WIERSZ | STRONA }

Określa poziom kompresji danych używany przez indeks.

ŻADEN

Indeks nie użył kompresji danych
row

Kompresja wierszy stosowana dla danych za pomocą indeksu
STRONA

Kompresja strony stosowana na danych przez indeks

Uwagi

Każdą z opcji można określić tylko raz w CREATE JSON INDEX instrukcji. Określenie duplikatu dowolnej opcji powoduje wystąpienie błędu.

[ ON { filegroup_name | "domyślne" } ]

Jeśli określisz grupę plików dla indeksu JSON, indeks zostanie umieszczony w tej grupie plików, niezależnie od schematu partycjonowania tabeli.

Aby uzyskać więcej informacji na temat tworzenia indeksów, zobacz sekcję Uwagi w sekcji CREATE INDEX.

Predykaty obsługiwane za pomocą indeksu JSON

Operacje wyszukiwania w dokumentach JSON zawartych w kolumnie JSON w tabeli można zoptymalizować, jeśli indeks JSON istnieje w kolumnie json . Indeks JSON jest używany w zapytaniach z różnymi wyrażeniami opartymi na funkcjach JSON.

W poniższych przykładach użyto tabeli Sales.SalesOrderHeader w bazie danych AdventureWorks2025 z kolumną json o nazwie Info. Kolumna Info jest tworzona jako typ json . Indeks JSON jest również tworzony w kolumnie Info z ustawieniami domyślnymi. Poniższy przykład kodu pokazuje instrukcję CREATE JSON INDEX :

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

W przypadku przykładowych wyrażeń wyszukiwania użyj następujących dokumentów JSON jako danych:

numer zamówienia sprzedaży	Informacje
`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}}`

funkcja JSON_PATH_EXISTS

Użyj funkcji JSON_PATH_EXISTS , aby sprawdzić, czy określona ścieżka SQL/JSON istnieje w dokumencie JSON.

To zapytanie pokazuje JSON_PATH_EXISTS w kolumnie json , którą można zoptymalizować przy użyciu indeksu JSON:

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

Indeks JSON jest obsługiwany z predykatem JSON_PATH_EXISTS i następującymi operatorami:

Operatory porównania (=)
IS [NOT] NULL predykat (obecnie niewspierany)

Funkcja JSON_VALUE

Użyj JSON_VALUE , aby wyodrębnić tekst JSON / wartość skalarną w określonej ścieżce SQL/JSON w dokumencie JSON. Poniższe zapytania pokazują, jak wyrażenie JSON_VALUE na kolumnie JSON można zoptymalizować przy użyciu indeksu JSON.

Wyszukiwanie równości ciągu JSON we właściwości obiektu:

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

Wyszukiwanie równości numeru JSON we właściwości obiektu po przekonwertowaniu wartości na typ danych int :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
```

Wyszukiwanie zakresu numeru JSON we właściwości obiektu po przekonwertowaniu wartości na typ danych int :

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

Wyszukiwanie zakresu dla numeru JSON we właściwości obiektu po przekonwertowaniu wartości na typ danych dziesiętnych :

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

Indeks JSON jest obsługiwany z predykatem JSON_VALUE i następującymi operatorami:

Operatory porównania (=)
LIKE predykat (obecnie nieobsługiwany)
IS [NOT] NULL predykat (obecnie nieobsługiwany)

Funkcja JSON_CONTAINS

Funkcja JSON_CONTAINS obsługuje łatwe wyszukiwanie wartości JSON w dokumencie JSON, które może używać indeksu JSON, jeśli istnieje w kolumnie JSON . Ta funkcja może służyć do testowania, czy wartość skalarna, obiekt lub tablica JSON jest zawarta w określonej ścieżce SQL/JSON w dokumencie JSON. Wartości wyszukiwania określone jako typy skalarne SQL są konwertowane na istniejące konwersje typów SQL/JSON. Te reguły są definiowane w sekcji zachowania.

Wymaganie

Klucz klastrowania jest wymagany w tabeli zawierającej kolumnę JSON. Błąd jest zgłaszany, jeśli klucz klastrowania jest nieobecny. Klucz klastrowania jest ograniczony do 31 kolumn, a maksymalny rozmiar klucza indeksu powinien być mniejszy niż 128 bajtów.

Uprawnienia

Użytkownik musi mieć ALTER uprawnienia do tabeli lub być członkiem stałej roli serwera sysadmin lub stałych ról bazy danych db_ddladmin i db_owner.

Ograniczenia

Istnieją następujące ograniczenia dla instrukcji indeksu JSON:

W kolumnie JSON w tabeli można utworzyć tylko jeden indeks JSON .
W tabeli można utworzyć maksymalnie 249 indeksów JSON. Tworzenie więcej niż jednego indeksu JSON w określonej kolumnie JSON nie jest obsługiwane.
Nie można utworzyć indeksu JSON w obliczonych kolumnach json .
Nie można utworzyć indeksu JSON w kolumnach json w widoku, zmiennej wartości tabeli lub tabeli zoptymalizowanej pod kątem pamięci.
Indeks JSON można utworzyć lub zmienić tylko w tryb offline.
Ścieżki JSON nie mogą nakładać się na definicję indeksu. Na przykład $a i $a.b nakładają się na siebie i nie są dozwolone w instrukcji CREATE JSON INDEX .
Modyfikacja ścieżek wymaga ponownego utworzenia indeksu JSON.
Indeksy JSON nie są obsługiwane we wskazówkach dotyczących indeksu.
Opcja kompresji danych nie jest obsługiwana.

Przykłady

Odp. Tworzenie indeksu JSON w kolumnie JSON

W poniższym przykładzie zostanie utworzona tabela o nazwie docs zawierająca kolumnę typu json. content W tym przykładzie tworzony jest indeks JSON w json_content_indexkolumnie content . W przykładzie tworzony jest indeks JSON dla całego dokumentu JSON lub wszystkich ścieżek SQL/JSON w dokumencie JSON.

DROP TABLE IF EXISTS docs;

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

CREATE JSON INDEX json_content_index
    ON docs (content);

Odp. Tworzenie indeksu JSON w kolumnie JSON z określonymi ścieżkami

W poniższym przykładzie zostanie utworzona tabela o nazwie docs zawierająca kolumnę typu json. content W tym przykładzie tworzony jest indeks JSON w json_content_indexkolumnie content . W przykładzie tworzony jest indeks json dla określonych ścieżek SQL/JSON w dokumencie JSON.
W przykładzie ustawiono również indeks FILLFACTOR na 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. Indeks JSON z optymalizacją wyszukiwania tablicy

Poniższy przykład zwraca indeksy JSON dla tabeli dbo.Customers. Indeks JSON jest tworzony z włączoną opcją optymalizacji wyszukiwania tablicy.

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-27