Condividi tramite

CREATE JSON INDEX (Transact-SQL)

Si applica a: Anteprima di SQL Server 2025 (17.x)

Crea un indice JSON su una tabella e una colonna specificate in anteprima di SQL Server 2025 (17.x).

Indici JSON:

  • È possibile creare prima che siano presenti dati nella tabella.
  • È possibile creare su tabelle in un altro database specificando un nome di database qualificato.
  • Richiedere alla tabella di avere una chiave primaria clusterizzata.
  • Non può essere specificato nelle viste indicizzate.

Annotazioni

La creazione di indici JSON è attualmente disponibile in anteprima e disponibile solo nell'anteprima di SQL Server 2025 (17.x).

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

index_name

Nome dell'indice. I nomi degli indici devono essere univoci all'interno di una tabella, ma non devono essere univoci all'interno di un database. I nomi degli indici devono seguire le regole degli identificatori.

  • ON <oggetto> ( json_column_name )

    Specifica l'oggetto (database, schema o tabella) in cui deve essere creato l'indice e il nome della colonna json .

  • json_column_name

    Nome della colonna del tipo di dati JSON in table_name che contiene zero o più percorsi SQL/JSON specificati.

  • sql_json_path

    Percorso SQL/JSON che deve essere estratto e indicizzato da json_column_name. L'impostazione predefinita per sql_json_path è $.

    • Indicizza in modo ricorsivo tutti i valori/chiavi dal percorso specificato in poi.
    • Supporta fino a 128 livelli nel percorso del documento JSON.
    • Non consente la sovrapposizione.

    Ad esempio, $.a e $.a.b genera un errore, poiché il percorso $.a include in modo ricorsivo tutti i percorsi e la finalità dell'utente non è chiara.

ON filegroup_name

Crea l'indice specificato nel filegroup specificato. Se non viene specificata alcuna posizione e la tabella non è partizionata, l'indice usa lo stesso filegroup della tabella sottostante. Il filegroup deve già esistere.

ON "predefinito"

Crea l'indice specificato nel filegroup predefinito.

Il termine predefinito, in questo contesto, non è una parola chiave. Si tratta di un identificatore per il filegroup predefinito e deve essere delimitato, come in ON "default" o ON [default]. Se "default" è specificato, l'opzione QUOTED_IDENTIFIER deve essere ON per la sessione corrente. Questa è l'impostazione predefinita. Per altre informazioni, vedere SET QUOTED_IDENTIFIER.

<oggetto>:: =

L'oggetto completamente qualificato o non completamente qualificato da indicizzare.

  • database_name

    Nome del database.

  • schema_name

    Nome del processo a cui appartiene la tabella.

  • table_name

    Nome della tabella da indicizzare.

FILLFACTOR = fillfactor

Specifica una percentuale che indica il livello di riempimento del livello foglia di ogni pagina di indice da parte del motore di database durante la creazione o la ricompilazione dell'indice. fillfactor deve essere un valore intero compreso tra 1 e 100. Il valore predefinito è 0. Se fillfactor è 100 o 0, il motore di database crea indici con pagine foglia riempite completamente.

Annotazioni

I valori 0 del fattore di riempimento e 100 sono uguali in tutti i confronti.

L'impostazione FILLFACTOR viene applicata solo in fase di creazione o ricompilazione dell'indice. La percentuale specificata di spazio vuoto delle pagine non viene mantenuta in modo dinamico dal motore di database. Per visualizzare l'impostazione del fattore di riempimento, usare la vista del catalogo sys.indexes .

La creazione di un indice cluster con un FILLFACTOR valore minore di 100 influisce sulla quantità di spazio di archiviazione occupato dai dati, perché il motore di database ridistribuisce i dati quando crea l'indice cluster.

Per altre informazioni, vedere Specificare un fattore di riempimento per un indice.

DROP_EXISTING = { ATTIVO | SPENTO }

Specifica che l'indice spaziale denominato e preesistente viene eliminato e ricostruito. Il valore predefinito è OFF.

  • ACCESO

    L'indice esistente viene eliminato e ricostruito. Il nome dell'indice specificato deve essere uguale a un indice attualmente esistente; Tuttavia, la definizione dell'indice può essere modificata. Ad esempio, è possibile specificare colonne diverse, ordinare, schema di partizione o opzioni di indice.

  • SPENTO

    Se il nome di indice specificato esiste già, viene visualizzato un errore.

Non è possibile modificare il tipo di indice usando DROP_EXISTING.

ONLINE = OFF

Specifica che le tabelle sottostanti e gli indici associati non sono disponibili per le query e la modifica dei dati durante l'operazione sull'indice. In questa versione di SQL Server le compilazioni di indici online non sono supportate per gli indici JSON. Se questa opzione è impostata ON su per un indice JSON, viene generato un errore. Omettere l'opzione ONLINE o impostare su ONLINEOFF.

Un'operazione sull'indice offline che crea, ricompila o elimina un indice JSON acquisisce un blocco di modifica dello schema (Sch-M) nella tabella. Il blocco impedisce agli utenti di accedere alla tabella sottostante per la durata dell'operazione.

Le operazioni online sugli indici non sono disponibili in tutte le edizioni di SQL Server.

Per un elenco delle caratteristiche supportate dalle edizioni di SQL Server su Windows, vedi:

ALLOW_ROW_LOCKS = { ON | OFF }

Specifica se sono consentiti blocchi di riga. Il valore predefinito è ON.

  • ACCESO

    I blocchi di riga sono consentiti durante l'accesso all'indice. Il motore di database determina quando usare i blocchi di riga.

  • SPENTO

    I blocchi di riga non vengono usati.

ALLOW_PAGE_LOCKS = { ATTIVO | DISATTIVO }

Specifica se sono consentiti blocchi di pagina. Il valore predefinito è ON.

  • ACCESO

    I blocchi a livello di pagina sono consentiti durante l'accesso all'indice. Il motore di database determina quando usare i blocchi di pagina.

  • SPENTO

    I blocchi di pagina non vengono usati.

MAXDOP = max_degree_of_parallelism

Sostituisce l'opzione di configurazione max degree of parallelism per la durata dell'operazione sull'indice. Usare MAXDOP per limitare il numero di processori usati in un'esecuzione di piano parallela. Il massimo è 64 processori.

Importante

Anche se l'opzione MAXDOP è supportata sintatticamente, CREATE SPATIAL INDEX attualmente usa sempre un solo processore.

max_degree_of_parallelism può essere uno dei valori seguenti.

Valore Descrizione
1 Disattiva la generazione di piani paralleli.
>1 Consente di limitare al valore specificato, o a un valore più basso in base al carico di lavoro corrente del sistema, il numero massimo di processori utilizzati in un'operazione parallela sugli indici.
0 (impostazione predefinita) Utilizza il numero effettivo di processori o un numero inferiore in base al carico di lavoro corrente del sistema.

Per altre informazioni, vedere Configurazione di operazioni parallele sugli indici.

Le operazioni parallele sugli indici non sono disponibili in tutte le edizioni di SQL Server.

Per un elenco delle caratteristiche supportate dalle edizioni di SQL Server su Windows, vedi:

DATA_COMPRESSION = { NONE | RIGA | PAGINA }

Determina il livello di compressione dei dati utilizzato dall'indice.

  • NESSUNO

    Nessuna compressione utilizzata per i dati dall'indice

  • row

    Compressione di riga usata dall'indice sui dati

  • PAGINA

    Compressione di pagina usata nei dati dall'indice

Osservazioni:

Ogni opzione può essere specificata una sola volta per CREATE JSON INDEX istruzione. Se si specifica un duplicato di qualsiasi opzione, viene generato un errore.

[ ON { filegroup_name | "default" } ]

Se si specifica un filegroup per un indice JSON, l'indice viene inserito in tale filegroup, indipendentemente dallo schema di partizionamento della tabella.

Per altre informazioni sulla creazione di indici, vedere la sezione Osservazioni in CREATE INDEX.

Predicati supportati con un indice JSON

Le operazioni di ricerca sui documenti JSON contenuti in una colonna JSON in una tabella possono essere ottimizzate se esiste un indice JSON nella colonna json . L'indice JSON viene usato nelle query con varie espressioni basate su funzioni JSON.

Gli esempi seguenti usano la Sales.SalesOrderHeader tabella nel AdventureWorks2022 database con una colonna json denominata Info. La Info colonna viene creata come tipo json . Viene creato anche un indice JSON nella Info colonna con le impostazioni predefinite. L'esempio di codice seguente illustra l'istruzione CREATE JSON INDEX :

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

Per le espressioni di ricerca di esempio, usare i documenti JSON seguenti come dati:

Numero Ordine di Vendita Informazioni
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}}

funzione JSON_PATH_EXISTS

Usare la funzione JSON_PATH_EXISTS per verificare se un percorso SQL/JSON specificato esiste in un documento JSON.

Questa query illustra JSON_PATH_EXISTS in una colonna JSON che può essere ottimizzata usando un indice JSON:

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

L'indice JSON è supportato con JSON_PATH_EXISTS predicato e gli operatori seguenti:

  • Operatori di confronto (=)
  • IS [NOT] NULL predicato (attualmente non supportato)

funzione JSON_VALUE

Usa JSON_VALUE per estrarre il valore testo JSON o valore scalare in un percorso SQL/JSON specificato in un documento JSON. Le query seguenti illustrano come ottimizzare un'espressione JSON_VALUE in una colonna JSON usando un indice JSON.

  • Ricerca di uguaglianza per una stringa JSON in una proprietà dell'oggetto:

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

  • Ricerca di uguaglianza per un numero JSON in una proprietà dell'oggetto dopo la conversione del valore in un tipo di dati int :

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

  • Ricerca di un numero JSON in una proprietà dell'oggetto dopo la conversione del valore in un tipo di dati int :

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

  • Ricerca di un numero in formato JSON in una proprietà di un oggetto dopo la conversione del valore al tipo di dati decimale.

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

L'indice JSON è supportato con un JSON_VALUE predicato e gli operatori seguenti:

  • Operatori di confronto (=)
  • LIKE predicato (attualmente non supportato)
  • IS [NOT] NULL predicato (attualmente non supportato)

funzione JSON_CONTAINS

La funzione JSON_CONTAINS supporta una semplice ricerca di valori JSON in un documento JSON che può usare un indice JSON se presente in una colonna JSON . Questa funzione può essere usata per verificare se un valore scalare JSON, un oggetto o una matrice è contenuto nel percorso SQL/JSON specificato in un documento JSON. I valori di ricerca specificati come tipi scalari SQL vengono convertiti per conversioni di tipi SQL/JSON esistenti. Queste regole sono definite nella sezione relativa al comportamento.

Requisito

Nella tabella che contiene la colonna JSON è necessaria una chiave di clustering. Se la chiave di clustering è assente, viene generato un errore. La chiave di clustering è limitata a 31 colonne e le dimensioni massime della chiave di indice devono essere inferiori a 128 byte.

Autorizzazioni

L'utente deve disporre dell'autorizzazione ALTER per la tabella, oppure essere membro del ruolo predefinito del server sysadmin, o dei ruoli predefiniti del database db_ddladmin e db_owner.

Limitazioni

Esistono le limitazioni seguenti per l'istruzione di indice JSON:

  • È possibile creare un solo indice JSON in una colonna JSON in una tabella.
  • È possibile creare fino a 249 indici JSON in una tabella. La creazione di più indici JSON in una colonna JSON specifica non è supportata.
  • Non è possibile creare un indice JSON nelle colonne JSON calcolate.
  • Non è possibile creare un indice JSON in colonne JSON in una vista, una variabile con valori di tabella o una tabella ottimizzata per la memoria.
  • Un indice JSON può essere creato o modificato solo in modo offline.
  • I percorsi JSON non possono sovrapporsi nella definizione dell'indice. Ad esempio, $a e $a.b si sovrappongono e non sono consentiti nell'istruzione CREATE JSON INDEX .
  • La modifica dei percorsi richiede la ricreazione dell'indice JSON.
  • Gli indici JSON non sono supportati negli hint di indice.
  • L'opzione di compressione dei dati non è supportata.

Esempi

Un. Creare un indice JSON in una colonna JSON

Nell'esempio seguente viene creata una tabella denominata docs contenente una colonna di tipo JSON , content. L'esempio crea quindi un indice JSON, json_content_index, nella content colonna . L'esempio crea l'indice JSON nell'intero documento JSON o in tutti i percorsi SQL/JSON nel documento 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. Creare un indice JSON in una colonna JSON con percorsi specifici

Nell'esempio seguente viene creata una tabella denominata docs contenente una colonna di tipo JSON , content. L'esempio crea quindi un indice JSON, json_content_index, nella content colonna . L'esempio crea l'indice JSON in percorsi SQL/JSON specifici nel documento JSON.
L'esempio imposta anche l'indice FILLFACTOR su 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);

Contenuti correlati