Expressões de demarcador JSON (SQL Server)

  • Artigo

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores Banco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse Analytics (somente pool de SQL sem servidor)

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, veja OPENJSON (Transact-SQL).

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

  • Quando você chama JSON_QUERY para extrair um objeto ou uma matriz JSON. Para obter mais informações, veja 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, veja 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 ou operadores de ponto (.), 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 nulo
$ { "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 armazenado 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:

Confira também

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