Expressões de demarcador JSON (SQL Server)

Aplica-se a:yes SQL Server 2016 (13.x) e posterior

Use expressões de demarcadores JSON para fazer referência às propriedades de objetos JSON.

Você precisa fornecer uma expressão de demarcador ao chamar as funções a seguir.

  • Quando você chama OPENJSON para criar uma exibição relacional de dados JSON. Para obter mais informações, consulte OPENJSON (Transact-SQL).

  • Quando você chama JSON_VALUE para extrair um valor de texto JSON. Para obter mais informações, consulte JSON_VALUE (Transact-SQL).

  • Quando você chama JSON_QUERY para extrair um objeto ou uma matriz JSON. Para obter mais informações, consulte JSON_QUERY (Transact-SQL).

  • Quando você chama JSON_MODIFY para atualizar o valor de uma propriedade em uma cadeia de caracteres JSON. Para obter mais informações, consulte JSON_MODIFY (Transact-SQL).

Partes de uma expressão de caminho

Uma expressão de demarcador tem dois componentes.

  1. O modo demarcador opcional, com valor de lax ou strict.

  2. O demarcador em si.

modo demarcador

No início da expressão de demarcador, opcionalmente, declare o modo demarcador especificando a palavra-chave lax ou strict. O padrão é lax.

  • No modo lax, as funções retornarão valores vazios se a expressão do demarcador contiver um erro. Por exemplo, se você solicitar o valor $.name e o texto JSON não contiver uma chave name, a função retornará nula, mas não gerará um erro.

  • No modo strict, a função gerará um erro se a expressão do demarcador contiver um erro.

A consulta a seguir especifica explicitamente o modo lax na expressão de demarcador.

DECLARE @json NVARCHAR(MAX);
SET @json=N'{ ... }';

SELECT * FROM OPENJSON(@json, N'lax $.info');

Caminho

Após a declaração de modo de demarcador opcional, especifique o demarcador em si.

  • O símbolo de cifrão ($) representa o item de contexto.

  • O demarcador de propriedade é um conjunto de etapas de demarcador. As etapas do demarcador podem conter os seguintes elementos e operadores.

    • Nomes de chave. Por exemplo, $.name e $."first name". Se o nome da chave começar com um sinal de cifrão ou contiver caracteres especiais como espaços, coloque-o entre aspas.

    • Elementos da matriz. Por exemplo, $.product[3]. Matrizes são baseadas em zero.

    • O operador ponto (.) indica um membro de um objeto. Por exemplo, em $.people[1].surname, surname é um filho de people.

Exemplos

Os exemplos nesta seção fazem referência ao texto JSON a seguir.

{
	"people": [{
		"name": "John",
		"surname": "Doe"
	}, {
		"name": "Jane",
		"surname": null,
		"active": true
	}]
}

A tabela a seguir mostra alguns exemplos de expressões de demarcador.

Expressão de demarcador Valor
$.people[0].name John
$.people[1] { "name": "Jane", "surname": null, "active": true }
$.people[1].surname null
$ { "people": [ { "name": "John", "surname": "Doe" },
{ "name": "Jane", "surname": null, "active": true } ] }

Como as funções internas tratam caminhos duplicados

Se o texto JSON contiver propriedades duplicadas (por exemplo, duas chaves com o mesmo nome no mesmo nível), as funções JSON_VALUE e JSON_QUERY retornarão apenas o primeiro valor que corresponde ao caminho. Para analisar um objeto JSON que contém chaves duplicadas e retornar todos os valores, use OPENJSON, conforme mostrado no exemplo a seguir.

DECLARE @json NVARCHAR(MAX);
SET @json=N'{"person":{"info":{"name":"John", "name":"Jack"}}}';

SELECT value
  FROM OPENJSON(@json,'$.person.info');

Saiba mais sobre JSON no SQL Server e no Banco de Dados SQL do Azure

Vídeos da Microsoft

Observação

Alguns dos links de vídeo nesta seção podem não funcionar no momento. A Microsoft está migrando conteúdo anteriormente no Canal 9 para uma nova plataforma. Atualizaremos os links à medida que os vídeos forem migrados para a nova plataforma.

Para obter uma introdução visual ao suporte interno para JSON no SQL Server e no Banco de Dados SQL do Azure, consulte os seguintes vídeos:

Consulte Também

OPENJSON (Transact-SQL)
JSON_VALUE (Transact-SQL)
JSON_QUERY (Transact-SQL)