Partilhar via

Expressões de caminho JSON no Motor de Base de Dados SQL

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

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

Você precisa fornecer uma expressão de caminho quando você chama as seguintes funções.

  • 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 caminho tem dois componentes.

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

  2. O caminho em si.

Modo de trajecto

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

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

  • No strict modo, a função gera um erro se a expressão do caminho contiver um erro.

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

DECLARE @json AS NVARCHAR (MAX);

SET @json = N'{ ... }';

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

Path

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

  • O símbolo de dólar ($) representa o item de contexto.

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

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

    • Elementos de matriz. Por exemplo, $.product[3]. As matrizes são baseadas em zero.

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

    • As pesquisas de caracteres especiais e de intervalo em matrizes também são suportadas se a entrada for um valor de tipo JSON.

Suporte a curinga e intervalo de array

Note

O suporte a wildcard e ranges de array está atualmente em pré-visualização 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 suportar um wildcard de array. O curinga Array permite especificar todos os elementos, intervalo de elementos, lista de elementos ou o token especial "last" para indicar o último valor em uma matriz JSON. As 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 ofereça suporte à expressão de caminho SQL/JSON, o valor de retorno 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 ou matriz JSON. Os curingas de matriz são suportados 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 do 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] Três primeiros 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 creditcards matriz
$.credit_cards[0, 2].type Retorna o valor da propriedade type do primeiro e terceiro elemento na creditcards matriz
$.credit_cards[1 to 3].type Retorna o valor da propriedade tipo do segundo ao quarto elemento no array creditcards.
$.credit_cards[last].type Retorna o valor da propriedade tipo do último elemento no creditcards array
$.credit_cards[last, 0].type Retorna o valor da propriedade type do primeiro e do último elemento no array creditcards.

Examples

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

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

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

Expressão do 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 lidam com caminhos duplicados

Se o texto JSON contiver propriedades duplicadas - por exemplo, duas chaves com o mesmo nome no mesmo nível - as JSON_VALUE funções 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 JSON interno, consulte o seguinte vídeo:

Conteúdo relacionado

  • Last updated on