Partilhar via

Tipo de dados JSON

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database AzureSQL Managed InstanceSQL database in 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 otimizado 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á está 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 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 de 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, estando também 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:

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

O método modify

Note

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

O tipo de dados json suporta o 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 preferida 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 estiver dentro do intervalo do valor existente, a modificação in-loco é 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 de função

Todas as funções JSON suportam o tipo de dados json sem alterações de código ou diferença de uso necessárias.

  • OPENJSON Atualmente não suporta o tipo de dados JSON em algumas plataformas. Para obter mais informações, consulte Limitações.

Para obter uma lista completa das 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 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 para os tipos char, nchar, varchar e nvarchar . Todas as conversões implícitas não são permitidas, semelhante ao comportamento do xml. Da mesma forma, apenas char, nchar, varchar e nvarchar podem ser explicitamente convertidos para o 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 sql_variant . Essa restrição é semelhante aos tipos de dados baseados em varchar(max),varbinary(max), nvarchar(max), xml e CLR.

Você pode converter colunas existentes como varchar(max) para json usando ALTER TABLE. Semelhante ao tipo de dados xml , você não pode converter uma coluna json em qualquer um 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 visualizaçõ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 do 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 dados CAST ( ... AS 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 agrupamento 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 para nvarchar(max) primeiro.

Limitações de tamanho

Limites de tamanho dos dados JSON no armazenamento:

Campo Limitação
Tamanho do tipo de dados JSON (binário) Até 2GB
Número de chaves exclusivas Até 32K
Por tamanho da cadeia de caracteres de tecla 7998 bytes
Por tamanho de valor de cadeia de caracteres 536870911 bytes
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