CRIAR ÍNDICE JSON (Transact-SQL)

2025-05-27

Aplica-se a: Visualização do SQL Server 2025 (17.x)

Cria um índice JSON em uma tabela e coluna especificadas no SQL Server 2025 (17.x) Preview.

Índices JSON:

Pode ser criado antes que haja dados na tabela.
Pode ser criado em tabelas em outro banco de dados especificando um nome de banco de dados qualificado.
Exigir que a tabela tenha uma chave primária clusterizada.
Não pode ser especificado em vistas indexadas.

Observação

A criação de índices JSON está atualmente em pré-visualização e disponível apenas na Pré-visualização do SQL Server 2025 (17.x).

Transact-SQL convenções de sintaxe

Sintaxe

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

Argumentos

nome_do_índice

O nome do índice. Os nomes de índice devem ser exclusivos dentro de uma tabela, mas não precisam ser exclusivos dentro de um banco de dados. Os nomes dos índices devem seguir as regras dos identificadores.

ON <Objeto> ( json_column_name )

Especifica o objeto (banco de dados, esquema ou tabela) no qual o índice deve ser criado e o nome da coluna json .
json_column_name

O nome da coluna de tipo de dados json em table_name, que contém zero ou mais dos caminhos SQL/JSON especificados.
sql_json_path

O caminho SQL/JSON que precisa ser extraído e indexado a partir de json_column_name. O padrão para sql_json_path é $.
- Indexa recursivamente todas as chaves/valores do caminho especificado em diante.
- Suporta até 128 níveis no caminho do documento JSON.
- Não permite sobreposição.
Por exemplo, $.a e $.a.b geram um erro, uma vez que o caminho $.a recursivamente inclui todos os caminhos e a intenção do utilizador não é clara.

EM filegroup_name

Cria o índice especificado no grupo de arquivos especificado. Se nenhum local for especificado e a tabela não for particionada, o índice usará o mesmo grupo de arquivos que a tabela subjacente. O grupo de arquivos já deve existir.

ON "padrão"

Cria o índice especificado no grupo de arquivos padrão.

O termo padrão, neste contexto, não é uma palavra-chave. É um identificador para o grupo de arquivos padrão e deve ser delimitado, como em ON "default" ou ON [default]. Se "default" for especificado, a QUOTED_IDENTIFIER opção deve ser ON para a sessão atual. Esta é a configuração padrão. Para obter mais informações, consulte SET QUOTED_IDENTIFIER.

<objeto>:: =

O objeto totalmente qualificado ou não totalmente qualificado a ser indexado.

database_name

O nome do banco de dados.
schema_name

O nome do esquema ao qual a tabela pertence.
table_name

O nome da tabela a ser indexada.

FILLFACTOR = fator de enchimento

Especifica uma porcentagem que indica o quão cheio o Mecanismo de Banco de Dados deve tornar o nível de folha de cada página de índice durante a criação ou reconstrução do índice. fillfactor deve ser um valor inteiro de 1 até 100. A predefinição é 0. Se fillfactor for 100 ou 0, o Mecanismo de Banco de Dados criará índices com páginas de folha preenchidas até sua capacidade total.

Observação

Os valores do fator de preenchimento 0 e 100 são os mesmos em todos os aspetos.

A configuração FILLFACTOR se aplica somente quando o índice é criado ou reconstruído. O Mecanismo de Banco de Dados não mantém dinamicamente a porcentagem especificada de espaço vazio nas páginas. Para exibir a configuração do fator de preenchimento, use a vista do catálogo sys.indexes.

A criação de um índice clusterizado com um FILLFACTOR menor que 100 afeta a quantidade de espaço de armazenamento que os dados ocupam, porque o Mecanismo de Banco de Dados redistribui os dados quando cria o índice clusterizado.

Para obter mais informações, consulte Especificar fator de preenchimento para um índice.

DROP_EXISTING = { EM | DESLIGADO }

Especifica que o índice espacial preexistente nomeado é descartado e reconstruído. A predefinição é OFF.

LIGADO

O índice existente é descartado e reconstruído. O nome do índice especificado deve ser o mesmo que um índice existente no momento; no entanto, a definição do índice pode ser modificada. Por exemplo, você pode especificar colunas diferentes, ordem de classificação, esquema de partição ou opções de índice.
DESLIGADO

Um erro será exibido se o nome de índice especificado já existir.

O tipo de índice não pode ser alterado usando DROP_EXISTING.

ONLINE = DESLIGADO

Especifica que as tabelas subjacentes e os índices associados não estão disponíveis para consultas e modificação de dados durante a operação de índice. Nesta versão do SQL Server, não há suporte para compilações de índice online para índices JSON. Se essa opção estiver definida como ON para um índice JSON, um erro será gerado. Omita a ONLINE opção ou defina ONLINE como OFF.

Uma operação de índice offline que cria, reconstrói ou descarta um índice JSON, adquire um bloqueio de modificação de esquema (Sch-M) na tabela. Isso impede que todo o usuário acesse a tabela subjacente durante a operação.

As operações de índice online não estão disponíveis em todas as edições do SQL Server.

Para obter uma lista de recursos suportados pelas edições do SQL Server no Windows, consulte:

ALLOW_ROW_LOCKS = { EM | DESLIGADO }

Especifica se os bloqueios de linha são permitidos. A predefinição é ON.

LIGADO

Bloqueios de linha são permitidos ao acessar o índice. O Mecanismo de Banco de Dados determina quando os bloqueios de linha são usados.
DESLIGADO

Os bloqueios de linha não são usados.

ALLOW_PAGE_LOCKS = { EM | DESLIGADO }

Especifica se os bloqueios de página são permitidos. A predefinição é ON.

LIGADO

Bloqueios de página são permitidos ao acessar o índice. O Mecanismo de Banco de Dados determina quando os bloqueios de página são usados.
DESLIGADO

Os bloqueios de página não são usados.

MAXDOP = max_degree_of_parallelism

Sobrescreve a opção de configuração max degree of parallelism durante a execução da operação de indexação. Use MAXDOP para limitar o número de processadores usados em uma execução de plano paralelo. O máximo é de 64 processadores.

Importante

Embora a MAXDOP opção seja sintaticamente suportada, CREATE SPATIAL INDEX atualmente sempre usa apenas um único processador.

max_degree_of_parallelism pode ser um dos seguintes valores.

Valor	Descrição
`1`	Suprime a geração de planos paralelos.
`>1`	Restringe o número máximo de processadores usados em uma operação de índice paralelo ao número especificado ou menos com base na carga de trabalho atual do sistema.
`0` (padrão)	Usa o número real de processadores ou menos com base na carga de trabalho atual do sistema.

Para obter mais informações, consulte Configurar operações de índice paralelo.

As operações de índice paralelo não estão disponíveis em todas as edições do SQL Server.

Para obter uma lista de recursos suportados pelas edições do SQL Server no Windows, consulte:

DATA_COMPRESSION = { NENHUM | LINHA | PÁGINA }

Determina o nível de compactação de dados usado pelo índice.

NENHUM

Não foi utilizada compressão nos dados pelo índice
LINHA

Compactação de linha utilizada pelo índice nos dados
PÁGINA

Compactação de página utilizada pelo índice nos dados

Observações

Cada opção pode ser especificada apenas uma vez por CREATE JSON INDEX instrução. Especificar uma duplicata de qualquer opção gera um erro.

[ EM { filegroup_name | "padrão" } ]

Se você especificar um grupo de arquivos para um índice JSON, o índice será colocado nesse grupo de arquivos, independentemente do esquema de particionamento da tabela.

Para obter mais informações sobre como criar índices, consulte a seção Comentários em CREATE INDEX.

Predicados suportados com um índice JSON

As operações de pesquisa em documentos JSON contidos em uma coluna json em uma tabela podem ser otimizadas se existir um índice JSON na coluna json . O índice JSON é usado em consultas com várias expressões baseadas em função JSON.

Os exemplos seguintes usam a tabela Sales.SalesOrderHeader no banco de dados AdventureWorks2022 com uma coluna json chamada Info. A Info coluna é criada como um tipo json . Um índice JSON também é criado na Info coluna com as configurações padrão. O exemplo de código a seguir mostra a CREATE JSON INDEX instrução:

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

Para as expressões de pesquisa de exemplo, use os seguintes documentos JSON como dados:

NúmeroDaOrdemDeVenda	Informações
`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}}`

Função JSON_PATH_EXISTS

Use a função JSON_PATH_EXISTS para testar se existe um caminho SQL/JSON especificado em um documento JSON.

Esta consulta demonstra JSON_PATH_EXISTS em uma coluna json que pode ser otimizada usando um índice JSON:

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

O índice JSON é suportado com o predicado JSON_PATH_EXISTS e os seguintes operadores:

Operadores de comparação (=)
IS [NOT] NULL predicado (Atualmente não suportado)

Função JSON_VALUE

Use o JSON_VALUE para extrair o texto JSON / valor escalar em um caminho SQL/JSON especificado em um documento JSON. As consultas a seguir mostram como uma JSON_VALUE expressão em uma coluna json pode ser otimizada usando um índice JSON.

Pesquisa de igualdade para uma string JSON numa propriedade de um objeto.

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

Pesquisa de igualdade para um número JSON em uma propriedade de objeto depois de converter o valor em um tipo de dados int :
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
```
Pesquisa de intervalo para um número JSON numa propriedade de um objeto após converter o valor para um tipo de dados int
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
```
Pesquisa de intervalo de valores para um número JSON numa propriedade do objeto depois de converter o valor num tipo de dados decimal
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Order.TotalDue RETURNING decimal(20, 4)) BETWEEN 1000 and 2000;
```

O índice JSON é suportado com um JSON_VALUE predicado e os seguintes operadores:

Operadores de comparação (=)
LIKE predicado (não suportado atualmente)
IS [NOT] NULL predicado (não suportado atualmente)

Função JSON_CONTAINS

A função JSON_CONTAINS suporta a pesquisa fácil de valores JSON em um documento JSON que pode usar um índice JSON se presente em uma coluna json . Essa função pode ser usada para testar se um valor, objeto ou matriz escalar JSON está contido no caminho SQL/JSON especificado em um documento JSON. Os valores de pesquisa especificados como tipos escalares SQL são convertidos por conversões de tipo SQL/JSON existentes. Essas regras são definidas na seção de comportamento.

Requisito

Uma chave de clustering é necessária na tabela que contém a coluna JSON. Um erro será gerado se a chave de clustering estiver ausente. A chave de clustering é limitada a 31 colunas e o tamanho máximo da chave de índice deve ser inferior a 128 bytes.

Permissões

O utilizador deve ter ALTER permissão na tabela, ou ser membro da função de servidor fixa sysadmin ou das funções de base de dados fixas db_ddladmin e db_owner.

Limitações

Existem as seguintes limitações para a instrução de índice JSON:

Apenas um índice JSON pode ser criado em uma coluna json em uma tabela.
Você pode criar até 249 índices JSON em uma tabela. Não há suporte para a criação de mais de um índice JSON em uma coluna JSON específica.
Um índice JSON não pode ser criado em colunas json computadas.
Um índice JSON não pode ser criado em colunas json em uma vista, variável de valor de tabela ou tabela otimizada em memória.
Um índice JSON pode ser criado ou alterado somente de maneira offline.
Os caminhos JSON não podem se sobrepor na definição de índice. Por exemplo, $a e $a.b sobrepõem-se, e não são permitidos na declaração CREATE JSON INDEX.
A modificação de caminhos requer a recriação do índice JSON.
Os índices JSON não são suportados em sugestões de índice.
A opção de compactação de dados não é suportada.

Exemplos

Um. Criar um índice JSON em uma coluna JSON

O exemplo a seguir cria uma tabela chamada docs que contém uma coluna de tipo json , content. Em seguida, o exemplo cria um índice JSON, json_content_index, na coluna content. O exemplo cria o índice json em todo o documento JSON ou todos os caminhos SQL/JSON no 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);

Um. Criar um índice JSON em uma coluna JSON com caminhos específicos

O exemplo a seguir cria uma tabela chamada docs que contém uma coluna de tipo json , content. Em seguida, o exemplo cria um índice JSON, json_content_index, na coluna content. O exemplo cria o índice json em caminhos SQL/JSON específicos no documento JSON.
O exemplo também define o índice FILLFACTOR como 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);

Partilhar via