Compartilhar via

Expressões de caminho JSON no Mecanismo de Banco de Dados SQL

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (apenas pool SQL serverless)banco de dados SQL no Microsoft Fabric

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 do texto JSON.
  • Quando você chama JSON_QUERY para extrair um objeto JSON ou uma matriz.
  • 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 caminho em si.

Modo de percurso

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');

Path

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

Note

O suporte a caractere curinga e intervalo de matriz está atualmente em versão prévia e disponível apenas no SQL Server 2025 (17.x).

O SQL Server 2025 (17.x) expande a expressão de caminho ANSI SQL/JSON para dar suporte a um caractere 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:

Path Description
$[*] Todos os elementos
$[0] Primeiro elemento
$[0 to 2] Primeiros três elementos
$[last] Último elemento
$[last, 0] Invalid
$[last, 2, 0, last] Invalid
$.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 matriz creditcards.
$.credit_cards[0, 2].type Retorna o valor da propriedade type do primeiro e terceiro elemento na matriz creditcards.
$.credit_cards[1 to 3].type Retorna o valor da propriedade type do segundo ao quarto elemento na matriz 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 de tipo do último e do primeiro elemento na matriz creditcards.

Examples

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 caminho Value
$.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

Para obter uma introdução visual ao suporte interno ao JSON, consulte o seguinte vídeo:

Conteúdo relacionado

  • Last updated on