Tipo de dados JSON

Aplica-se a: SQL Server 2025 (17.x) Base de Dados SQL do Azure AzureSQL Managed InstanceSQL database in Microsoft Fabric

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

O tipo json proporciona armazenamento de alta fidelidade de documentos JSON otimizado para consulta e manipulação. Oferece as seguintes vantagens 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 aceder a todo o documento.
  • Armazenamento mais eficiente, otimizado para compressão.
  • Sem alterações na compatibilidade com o código existente.

O tipo json armazena internamente as strings usando 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 dados json numa definição de coluna contida numa CREATE TABLE instrução. Por exemplo:

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

Especifique as 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 incorporado está disponível no Base de Dados SQL do Azure, Azure SQL Managed Instance e SQL Server 2025 (17.x).

Para mais informações sobre suporte JSON no SQL Server 2025 (17.x), consulte 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.

Note

O tipo de dados json e os índices JSON estão geralmente disponíveis em SQL Server 2025 (17.x), Base de Dados SQL do Azure, Azure SQL Managed Instance (com a política de atualização de data SQL Server 2025 ou Always-up-to, e a base de dados SQL em Microsoft Fabric.

O método modify

O tipo de dados json suporta o modify método. Use modify para alterar documentos JSON armazenados numa coluna. O modify método inclui otimizações que realizam modificações no local dos dados sempre que possível. É a forma preferida de modificar um documento JSON numa coluna json .

Para cadeias JSON, se o novo valor tiver o mesmo comprimento ou for mais curto do 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 um array 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 ou array JSON.

Use a função ISJSON para testar se uma cadeia contém JSON válido. Sem uma restrição de tipo, ISJSON aceita apenas um objeto ou array JSON ao nível superior, igual ao tipo de dados json . A VALUE restrição de tipo aceita qualquer valor JSON ao nível superior, incluindo um escalar, conforme permite o 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 de função

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

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

Indexes

Uma coluna json pode ser uma coluna incluída numa 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 num índice padrão.

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

No Base de Dados SQL do Azure, Azure SQL Managed Instance, SQL Server 2025 (17.x) e SQL database no Microsoft Fabric, pode criar um índice JSON para otimizar consultas que acedam aos valores dentro de documentos JSON.

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

Conversion

A conversão de json para char, nchar, varchar e nvarchar deve ser explícita. Utilizar 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 vector também pode ser implícita ou explícita.

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

Um valor que convertes para 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, o json mantém o primeiro valor e descarta os outros valores. Não ocorre qualquer erro.

A conversão de json para um tipo string devolve o texto JSON sem espaço em branco insignificante. Se o comprimento alvo for demasiado 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 sql_variant . Esta 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).

Precisão numérica

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

Se precisares de manter a precisão, especifica o número JSON como valor decimal. De forma semelhante, se precisar de preservar a representação textual do documento JSON, armazene o documento JSON como um tipo de dado de cadeia de caracteres.

Compatibility

Pode usar o tipo de dado json como parâmetro ou tipo de retorno numa função definida pelo utilizador, ou como parâmetro de um procedimento armazenado. O tipo json é compatível com gatilhos e visualizaçõ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 .

Não pode criar um tipo de alias para o tipo de dados 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 devolve o tipo de dado JSON conforme esperado.

Limitações do condutor

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 funcionalidade TDS. Drivers que não suportam esta 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) utiliza 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 da base de dados.

Limitações de tamanho

Limites de tamanho dos dados JSON no armazenamento:

Campo Limitação
Tamanho do tipo de dados JSON (binário) Até 2 GB
Número de chaves exclusivas Até 32.000
Por tamanho da cadeia de caracteres de tecla 7.998 bytes
Por tamanho de valor de cadeia de caracteres 536.870.911 bytes
Número de propriedades em um objeto Até 65.535
Número de elementos em uma matriz Até 65.535
Número de níveis aninhados no documento JSON 128

Conteúdo relacionado

  • Última atualização a