Compartilhar via

Expressões de demarcador JSON (SQL Server)

Aplica-se a: SQL Server 2016 (13.x) e 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.
  • Quando você chama JSON_VALUE para extrair um valor de texto JSON.
  • Quando você chama JSON_QUERY para extrair um objeto ou uma matriz JSON.
  • Quando você chama JSON_MODIFY para atualizar o valor de uma propriedade em uma cadeia de caracteres JSON.

Partes de uma expressão de caminho

Uma expressão de demarcador tem dois componentes.

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

  2. O demarcador em si.

modo demarcador

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

  • No lax modo, a função retornará valores vazios se a expressão de caminho contiver um erro. Por exemplo, se você solicitar o valor $.namee o texto JSON não contiver uma name chave, a função retornará nulo, mas não gerará um erro.

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

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

DECLARE @json AS 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.

    • Também há suporte para pesquisas de caractere curinga e intervalo de matriz se a entrada for um valor de tipo JSON.

Suporte a caractere curinga e intervalo de matriz

Observação

O recurso de suporte a caracteres curinga e intervalos de array está atualmente em fase de prévia e disponível apenas na versão prévia do SQL Server 2025 (17.x).

A versão prévia do SQL Server 2025 (17.x) expande a expressão de caminho ANSI SQL/JSON para dar suporte a um curinga de array. O curinga matriz permite que você especifique todos os elementos, intervalo de elementos, lista de elementos ou o token especial "last" para indicar o último valor em uma matriz JSON. Matrizes SQL/JSON usam índice baseado em zero. O caminho SQL/JSON com curingas pode ser usado em JSON_QUERY, JSON_PATH_EXISTS e JSON_CONTAINS.

Embora JSON_VALUE a função dê suporte à expressão de caminho SQL/JSON, o valor retornado de uma JSON_VALUE função é um escalar SQL e, portanto, a função sempre retorna NULL para qualquer caminho SQL/JSON que aponte para um objeto JSON ou matriz. Há suporte para curingas de array somente se a entrada for do tipo json.

A sintaxe a seguir mostra como o curinga, o intervalo e o token last especial podem ser usados:

path[elements ]

elements ::= {
*
| number
| number to number
| last
| {number...[, number] }
}

O token last especial pode ser usado em vez de valor numérico. Se um intervalo for especificado, o intervalo precisará ser especificado em ordem crescente.

Exemplos de algumas expressões de caminho SQL/JSON válidas:

Caminho Descrição
$[*] Todos os elementos
$[0] Primeiro elemento
$[0 to 2] Primeiros três elementos
$[last] Último elemento
$[last, 0] Inválido
$[last, 2, 0, last] Inválido
$.creditcards[0].type Retorna o valor da propriedade type do primeiro elemento na creditcards matriz
$.credit_cards[*].type Retorna o valor da propriedade type de todos os elementos na creditcards matriz
$.credit_cards[0, 2].type Retorna o valor da propriedade type do primeiro e terceiro elemento no array creditcards
$.credit_cards[1 to 3].type Retorna o valor da propriedade type do segundo ao quarto elemento no array creditcards
$.credit_cards[last].type Retorna o valor da propriedade type do último elemento da matriz creditcards
$.credit_cards[last, 0].type Retorna o valor da propriedade type do último e primeiro elemento na creditcards matriz

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 } ] }
$.people[last].name ["Jane"]
$.people[0 to 1].name ["John","Jane"]
$.people[0, 1].name ["John","Jane"]

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 AS 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

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

Conteúdo relacionado