CRIAR ÍNDICE JSON (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x)

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

Í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 é possível especificar em exibições indexadas.

Observação

Criar índices JSON está atualmente em prévia e disponível apenas no SQL Server 2025 (17.x).

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

Argumentos

nome_do_indice

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

Objeto< ON >(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 de json_column_name. O padrão para sql_json_path é $.
- Indexa recursivamente todas as chaves/valores do caminho especificado em diante.
- Dá suporte a até 128 níveis no caminho do documento JSON.
- Não permite sobreposição.
Por exemplo, $.a e $.a.b geram um erro, pois o caminho $.a inclui todos os caminhos de forma recursiva e a intenção do usuário não está claramente definida.

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 opção QUOTED_IDENTIFIER deverá ser ON para a sessão atual. Essa é a configuração padrão. Para saber mais, confira 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.

OPTIMIZE_FOR_ARRAY_SEARCH = { ON | DESLIGADO }

Especifica se as pesquisas de matriz são otimizadas no índice JSON. O padrão é OFF.

FILLFACTOR = fillfactor de preenchimento

Especifica uma porcentagem que indica quanto o Mecanismo de Banco de Dados deve preencher o nível folha de cada página de índice durante a criação ou recriação do índice. fillfactor deve ser um valor inteiro de 1 para 100. O padrão é 0. Se fillfactor for 100 ou 0, o Mecanismo de Banco de Dados criará índices com páginas de folha totalmente preenchidas.

Observação

Os valores dos fatores de preenchimento 0 e 100 são os mesmos em todos os aspectos.

A configuração FILLFACTOR se aplica somente quando o índice é criado ou recriado. O Mecanismo de Banco de Dados não mantém dinamicamente o percentual especificado de espaço vazio nas páginas. Para visualizar a configuração do fator de preenchimento, use a visão 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, veja Especificar fator de preenchimento para um índice.

DROP_EXISTING = { ON | DESLIGADO }

Especifica que o índice JSON nomeado e pré-existente é descartado e recriado. O padrão é OFF.

ATIVADO

O índice existente é descartado e recriado. O nome do índice especificado deve ser o mesmo que um índice existente no momento; no entanto, a definição de í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 do índice especificado já existir.

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

ON-LINE = DESLIGADO

Especifica que tabelas subjacentes e í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 builds de índice online para índices JSON. Se essa opção estiver definida ON para um índice JSON, um erro será gerado. Omita a opção ONLINE ou defina ONLINE como OFF.

Uma operação de índice offline que cria, recria ou descarta um índice JSON, adquire um bloqueio de modificação de esquema (Sch-M) na tabela. Isso evita o acesso de todos os usuários à tabela subjacente enquanto durar 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 dos recursos compatíveis com as edições do SQL Server no Windows, confira:

ALLOW_ROW_LOCKS = { ON | DESLIGADO }

Especifica se os bloqueios de linha são permitidos. O padrão é ON.

ATIVADO

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

Bloqueios de linha não são usados.

PERMITIR_TRAVAS_DE_PÁGINA = { LIGADO | DESLIGADO }

Especifica se os bloqueios de página são permitidos. O padrão é ON.

ATIVADO

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

Bloqueios de página não serão usados.

MAXDOP = max_degree_of_parallelism

Substitui a opção max degree of parallelism de configuração durante a 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 opção MAXDOP tenha suporte sintático, CREATE JSON 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 plano paralelo.
`>1`	Restringe o número máximo de processadores usados em uma operação de índice paralela 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 paralelas não estão disponíveis em todas as edições do SQL Server.

Para obter uma lista dos recursos compatíveis com as edições do SQL Server no Windows, confira:

DATA_COMPRESSION = { NONE | LINHA | PÁGINA }

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

NENHUM

Nenhuma compactação foi usada nos dados pelo índice
LINHA

Compactação de linha usada em dados pelo índice
PÁGINA

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

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.

[ ON { 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 compatíveis com um índice JSON

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

Os exemplos a seguir usam a Sales.SalesOrderHeader tabela no AdventureWorks2025 banco de dados com uma coluna json chamada Info. A Info coluna é criada como um tipo json . Um índice JSON também é criado na Info coluna com configurações padrão. O seguinte exemplo de código 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úmero do Pedido de Venda	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}}`

A 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.

Essa 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;

Há suporte para o índice JSON com o predicado JSON_PATH_EXISTS e os seguintes operadores:

Operadores de comparação (=)
IS [NOT] NULL predicado (sem suporte no momento)

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 cadeia de caracteres JSON em uma propriedade de 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;
```
Realize a busca por alcance de um número JSON em uma propriedade de objeto após converter o valor para o tipo de dados int.
```
SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
```

Pesquisa de intervalo para um número JSON em uma propriedade do objeto após converter o valor para o 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 por um JSON_VALUE predicado e pelos seguintes operadores:

Operadores de comparação (=)
LIKE predicado (sem suporte no momento)
IS [NOT] NULL predicado (sem suporte no momento)

função JSON_CONTAINS

A função JSON_CONTAINS dá suporte à pesquisa fácil de valores JSON em um documento JSON que pode usar um índice JSON se estiver presente em uma coluna json . Essa função pode ser usada para testar se um valor escalar JSON, um objeto ou uma matriz 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 menor que 128 bytes.

Permissões

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

Limitações

As seguintes limitações existem para a instrução de índice JSON:

Somente 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 exibição, variável do tipo tabela ou tabela otimizada para memória.
Um índice JSON pode ser criado ou alterado apenas 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 recriar o índice JSON.
Não há suporte para índices JSON em dicas de índice.
Não há suporte para a opção de compactação de dados.

Exemplos

Um. Criar um índice JSON em uma coluna JSON

O exemplo a seguir cria uma tabela nomeada docs que contém uma coluna de tipo json. content Em seguida, o exemplo cria um índice JSON, json_content_indexna content coluna. O exemplo cria o índice json em todo o documento JSON ou em 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 nomeada docs que contém uma coluna de tipo json. content Em seguida, o exemplo cria um índice JSON, json_content_indexna content coluna. 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);

B. Índice JSON com otimização de pesquisa de matriz

O exemplo a seguir retorna índices JSON para a tabela dbo.Customers. O índice JSON é criado com a opção de otimização de pesquisa de matriz habilitada.

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

Comentários

Esta página foi útil?

Last updated on 2025-10-27