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 dado json armazena documentos JSON em formato binário.

O tipo json oferece armazenamento de alta fidelidade de documentos JSON otimizado para consulta e manipulação. Ele oferece os seguintes benefícios em relação ao armazenamento de dados JSON como varchar ou nvarchar:

• Leituras mais eficientes, pois o documento já está analisado.
• Escritas mais eficientes, pois a consulta pode atualizar valores individuais sem acessar o documento inteiro.
• Armazenamento mais eficiente, otimizado para compressão.
• Nenhuma alteração na compatibilidade com o código existente.

O tipo json armazena internamente as strings usando a codificação UTF-8 (Latin1_General_100_BIN2_UTF8). Outros tipos de dados são armazenados como tipos nativos. 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 ) ]

Use o tipo de dado json em uma definição de coluna contida em uma CREATE TABLE instrução. Por exemplo:

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

Especifique restrições 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 para funções JSON foi introduzido no SQL Server 2016 (13.x). O tipo de dado json embutido está disponível no Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e SQL Server 2025 (17.x).

Para mais informações sobre suporte a JSON no SQL Server 2025 (17.x), veja Principais capacidades JSON no SQL Server 2025.

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

O método de modificação

O tipo de dados json dá suporte ao modify método. Use modify para alterar documentos JSON armazenados em uma coluna. O modify método inclui otimizações que realizam modificações no local nos dados sempre que possível. É a forma preferida de modificar um documento JSON em uma coluna json .

Para cadeias JSON, se o novo valor tiver o mesmo comprimento ou for menor que o valor existente, o método pode modificar os dados no local.

Para números JSON, se o novo valor for do mesmo tipo ou se encaixar no intervalo do valor existente, o método pode modificar os dados no local.

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;

Dados válidos

A entrada para o tipo de dados json deve ser um objeto JSON ou uma matriz JSON. Escalares, booleanos e NULL valores não são suportados. O tipo de dados JSON está em conformidade com o IETF RFC 4627, que permite apenas um objeto JSON ou matriz.

Use a função ISJSON para testar se uma string contém JSON válido. Sem uma restrição de tipo, ISJSON aceita apenas um objeto ou array JSON no nível superior, igual ao tipo de dado json . A VALUE restrição de tipo aceita qualquer valor JSON no nível superior, incluindo um escalar, conforme permitido pelo IETF RFC 8259. As ARRAYrestrições , OBJECT, e SCALAR de tipo aceitam apenas esse tipo.

Por exemplo:

DECLARE @true AS JSON = 'true'; -- invalid
DECLARE @false AS JSON = 'false'; -- invalid
DECLARE @number AS JSON = '1234.56'; -- invalid
DECLARE @string AS JSON = '"contoso"'; -- invalid
DECLARE @null AS JSON = 'null'; -- invalid

DECLARE @null AS JSON = NULL; -- valid
DECLARE @object AS JSON = '{}'; -- valid
DECLARE @array AS JSON = '[]'; -- valid

Suporte à função

Todas as funções JSON suportam o tipo de dado json sem exigir alterações no código.

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

Indexes

Uma coluna json pode ser uma coluna incluída em uma definição de índice, ou aparecer na WHERE cláusula de um índice filtrado. Uma coluna json não pode ser usada como coluna chave em um índice padrão.

Para obter mais informações, consulte CREATE INDEX.

No Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, SQL Server 2025 (17.x) e SQL Database no Microsoft Fabric, você pode criar um índice JSON para otimizar consultas que acessam valores dentro de documentos JSON.

Para obter mais informações, consulte CREATE JSON INDEX.

Conversion

A conversão de json para char, nchar, varchar e nvarchar deve ser explícita. Use CAST ou CONVERT.

A conversão de char, nchar, varchar, nvarchar e vector para json pode ser implícita ou explícita. A conversão de json para vetor também pode ser implícita ou explícita.

Conversão entre json e todos os outros tipos de dados não é permitida.

Um valor que você converte em json deve ser um objeto JSON ou um array JSON. Um escalar JSON, como 1, "abc", true, ou null, causa o erro 13609. Uma cadeia vazia também causa o erro 13609. Se um objeto tiver chaves duplicadas, json mantém o primeiro valor e descarta os outros valores. Nenhum erro ocorre.

A conversão de json para um tipo string retorna o texto JSON sem espaço em branco insignificante. Se o comprimento alvo for muito curto para o texto JSON, ocorre o erro 13639. O valor não é truncado.

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 aos tipos de dados baseados em varchar(max),varbinary(max), nvarchar(max), xml e 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).

Precisão numérica

Quando você converte para json a partir de char, nchar, varchar ou nvarchar, o texto JSON contendo um número JSON pode ser arredondado com base no formato numérico.

Se precisar manter a precisão, especifique o número JSON como um valor decimal. Da mesma forma, se você precisar preservar a representação textual do documento JSON, armazene o documento JSON como um tipo de dado de string de caracteres.

Compatibility

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

Atualmente, o formato nativo da ferramenta bcp representa os dados json como varchar ou nvarchar. Você deve especificar um arquivo de formato para designar uma coluna json .

Você não pode criar um tipo de alias para o tipo de dado json com CREATE TYPE. 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

CAST e CONVERT retorne o tipo de dado JSON conforme esperado.

Limitações do driver

O procedimento armazenado do sistema sp_describe_first_result_set retorna corretamente o tipo de dado json se o driver suportar a JSONSUPPORT extensão de recurso TDS. Drivers que não suportam essa extensão vejam varchar ou nvarchar em vez disso.

SqlClient (>= 6.0) e JDBC (>= 13.2.0) suportam JSONSUPPORT. Por exemplo, a versão mais recente do SQL Server Management Studio (SSMS) usa o driver mais recente do SqlClient e reporta corretamente o tipo json nos metadados do conjunto de resultados.

• Sem JSONSUPPORT, TDS >= 7,4 (com UTF-8) reporta varchar(max) com Latin1_General_100_BIN2_UTF8.
• Sem JSONSUPPORT, o TDS < 7.4 reporta nvarchar(max) com a colação do banco de dados.

Limitações de tamanho

Limites de tamanho de dados JSON no armazenamento:

Conteúdo relacionado

• Armazenar documentos JSON
• Dados JSON no SQL Server