Compartilhar via

Tipo de dados JSON

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureBanco de DadosSQL do Azure Banco de Dados SQL banco de dados SQL do Banco de Dados SQL do Azurebanco de dados SQL no Microsoft Fabric

O tipo de dados json armazena documentos JSON em um formato binário nativo.

O tipo json fornece um armazenamento de alta fidelidade de documentos JSON otimizados para fácil consulta e manipulação e fornece os seguintes benefícios sobre o armazenamento de dados JSON como varchar ou nvarchar:

  • Leituras mais eficientes, pois o documento já foi analisado
  • Gravações mais eficientes, pois a consulta pode atualizar valores individuais sem acessar o documento inteiro
  • Armazenamento mais eficiente, otimizado para compactação
  • Nenhuma alteração na compatibilidade com o código existente

O tipo json armazena internamente dados usando a codificação UTF-8. Latin1_General_100_BIN2_UTF8 Esse comportamento corresponde à especificação JSON.

Para obter mais informações sobre como consultar dados JSON, consulte Dados JSON no SQL Server.

Sintaxe de exemplo

A sintaxe de uso para o tipo json é semelhante a todos os outros tipos de dados do SQL Server em uma tabela.

column_name JSON [ NOT NULL | NULL ] [CHECK ( constraint_expression ) ] [ DEFAULT ( default_expression ) ]

O tipo de dados json pode ser usado na definição de coluna contida em uma CREATE TABLE instrução. Por exemplo:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
);

As restrições podem ser especificadas como parte da definição da coluna. Por exemplo:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
        CHECK (JSON_PATH_EXISTS(order_details, '$.basket') = 1)
);

Disponibilidade de funcionalidades

O suporte à função JSON foi introduzido pela primeira vez no SQL Server 2016 (13.x). O tipo nativo json foi introduzido no Azure SQL Database e Azure SQL Managed Instance, e também está disponível no SQL Server 2025 (17.x).

O tipo de dados json está disponível em todos os níveis de compatibilidade do banco de dados.

Note

O tipo de dados JSON:

  • geralmente está disponível para o Banco de Dados SQL do Azure e a Instância Gerenciada de SQL do Azure com a política de atualizaçãodo SQL Server 2025 ou Always-up-to-date.
  • está em versão prévia do SQL Server 2025 (17.x) e do banco de dados SQL no Fabric.

O método de modificação

Note

O modify método está atualmente em prévia e disponível apenas no SQL Server 2025 (17.x).

O tipo de dados json dá suporte ao modify método. Use modify para modificar documentos JSON armazenados em uma coluna. O modify método tem otimizações para executar modificações in-loco nos dados sempre que possível e é a maneira preferencial de modificar um documento JSON em uma coluna json .

Para cadeias de caracteres JSON, se o novo valor for menor ou igual ao valor existente, a modificação in-loco será possível.

Para números JSON, se o novo valor for do mesmo tipo ou dentro do intervalo do valor existente, a modificação in-loco será possível.

DROP TABLE IF EXISTS JsonTable;

CREATE TABLE JsonTable
(
    id INT PRIMARY KEY,
    d JSON
);

INSERT INTO JsonTable (id, d)
VALUES (1, '{"a":1, "b":"abc", "c":true}');

UPDATE JsonTable
SET d.modify('$.a', 14859)
WHERE id = 1;

UPDATE JsonTable
SET d.modify('$.b', 'def')
WHERE id = 1;

Suporte à função

Todas as funções JSON dão suporte ao tipo de dados json sem nenhuma alteração de código ou diferença de uso necessária.

  • OPENJSON atualmente não dá suporte ao tipo de dados json em algumas plataformas. Para obter mais informações, consulte Limitações.

Para obter uma lista completa de funções JSON, consulte funções JSON.

Indexes

Não há tipos de índice especiais para dados JSON.

O tipo json não pode ser usado como coluna de chave em uma CREATE INDEX instrução. No entanto, uma coluna json pode ser especificada como uma coluna incluída em uma definição de índice. Além disso, uma coluna json pode aparecer na WHERE cláusula de um índice filtrado.

Conversion

A conversão explícita usando CAST ou CONVERT do tipo json pode ser feita em tipos char, nchar, varchar e nvarchar . Todas as conversões implícitas não são permitidas, semelhante ao comportamento de xml. Da mesma forma, somente char, nchar, varchar e nvarchar podem ser convertidos explicitamente no tipo de dados json .

O tipo de dados json não pode ser usado com o tipo sql_variant ou atribuído a uma variável ou coluna de sql_variant . Essa restrição semelhante a varchar(max), varbinary(max), nvarchar(max), xml e tipos de dados baseados em CLR.

Você pode converter colunas existentes como varchar(max) em json usando ALTER TABLE. Semelhante ao tipo de dados xml , você não pode converter uma coluna json em nenhum dos tipos de cadeia de caracteres ou binários usando ALTER TABLE.

Para obter mais informações, consulte Conversão de tipo de dados (Mecanismo de Banco de Dados).

Compatibility

O tipo de dados json pode ser usado como um parâmetro ou tipo de retorno em uma função definida pelo usuário ou o parâmetro de um procedimento armazenado. O tipo json é compatível com gatilhos e exibições.

Atualmente, o formato nativo da ferramenta bcp contém o documento json como varchar ou nvarchar. Você deve especificar um arquivo de formato para designar uma coluna json .

A criação de tipo de alias usando CREATE TYPE para o tipo de dados json não é permitida. Esse comportamento é o mesmo que o tipo de dados xml .

Usar SELECT ... INTO com o tipo de dados json cria uma tabela com o tipo json .

Limitations

O comportamento de retorna um tipo de CAST ( ... AS JSON) dados json , mas o procedimento armazenado do sistema sp_describe_first_result_set não retorna corretamente o tipo de dados json . Portanto, muitos clientes de acesso a dados e driver veem um tipo de dados varchar ou nvarchar .

  • Atualmente, TDS >= 7,4 (com UTF-8) vê varchar(max) com Latin_General_100_bin2_utf8.
  • Atualmente, o TDS < 7.4 vê nvarchar(max) com ordenação de banco de dados.

Atualmente, a OPENJSON() função não aceita o tipo de dados json em algumas plataformas. Atualmente, é uma conversão implícita. Converta explicitamente em nvarchar(max) primeiro.

Limitações de tamanho

Limites de tamanho de dados JSON no armazenamento:

Campo Limitation
Tamanho do tipo de dados JSON (binário) Até 2 GB
Número de chaves exclusivas Até 32 mil
Tamanho da cadeia de caracteres por chave 7998 bytes
Tamanho do valor por cadeia de caracteres bytes 536870911
Número de propriedades em um objeto Até 65535
Número de elementos em uma matriz Até 65535
Número de níveis aninhados no documento JSON 128

Conteúdo relacionado

  • Last updated on