Expressões de demarcador JSON (SQL Server)JSON Path Expressions (SQL Server)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure nãoSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Use expressões de demarcadores JSON para fazer referência às propriedades de objetos JSON.Use JSON path expressions to reference the properties of JSON objects.

Você precisa fornecer uma expressão de demarcador ao chamar as funções a seguir.You have to provide a path expression when you call the following functions.

  • Quando você chama OPENJSON para criar uma exibição relacional de dados JSON.When you call OPENJSON to create a relational view of JSON data. Para obter mais informações, veja OPENJSON (Transact-SQL).For more info, see OPENJSON (Transact-SQL).

  • Quando você chama JSON_VALUE para extrair um valor de texto JSON.When you call JSON_VALUE to extract a value from JSON text. Para obter mais informações, veja JSON_VALUE (Transact-SQL).For more info, see JSON_VALUE (Transact-SQL).

  • Quando você chama JSON_QUERY para extrair um objeto ou uma matriz JSON.When you call JSON_QUERY to extract a JSON object or an array. Para obter mais informações, veja JSON_QUERY (Transact-SQL).For more info, see JSON_QUERY (Transact-SQL).

  • Quando você chama JSON_MODIFY para atualizar o valor de uma propriedade em uma cadeia de caracteres JSON.When you call JSON_MODIFY to update the value of a property in a JSON string. Para obter mais informações, veja JSON_MODIFY (Transact-SQL).For more info, see JSON_MODIFY (Transact-SQL).

Partes de uma expressão de caminhoParts of a path expression

Uma expressão de demarcador tem dois componentes.A path expression has two components.

  1. O modo demarcador opcional, com valor de lax ou strict.The optional path mode, with a value of lax or strict.

  2. O demarcador em si.The path itself.

Somos todos ouvidos: Se você encontrar algo desatualizado ou incorreto neste artigo, como uma etapa ou um exemplo de código, informe-nos.We are listening: If you find something outdated or incorrect in this article, such as a step or a code example, please tell us. Você pode clicar no botão Esta página na seção Comentários na parte inferior desta página.You can click the This page button in the Feedback section at the bottom of this page. Lemos todos os itens de comentários sobre o SQL, normalmente no dia seguinte.We read every item of feedback about SQL, typically the next day. Obrigado.Thanks.

Path modePath mode

No início da expressão de demarcador, opcionalmente, declare o modo demarcador especificando a palavra-chave lax ou strict.At the beginning of the path expression, optionally declare the path mode by specifying the keyword lax or strict. O padrão é lax.The default is lax.

  • No modo lax, as funções retornarão valores vazios se a expressão do demarcador contiver um erro.In lax mode, the function returns empty values if the path expression contains an error. 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.For example, if you request the value $.name, and the JSON text doesn't contain a name key, the function returns null, but does not raise an error.

  • No modo strict, a função gerará um erro se a expressão do demarcador contiver um erro.In strict mode, the function raises an error if the path expression contains an error.

A consulta a seguir especifica explicitamente o modo lax na expressão de demarcador.The following query explicitly specifies lax mode in the path expression.

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

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

PathPath

Após a declaração de modo de demarcador opcional, especifique o demarcador em si.After the optional path mode declaration, specify the path itself.

  • O símbolo de cifrão ($) representa o item de contexto.The dollar sign ($) represents the context item.

  • O demarcador de propriedade é um conjunto de etapas de demarcador.The property path is a set of path steps. As etapas do demarcador podem conter os seguintes elementos e operadores.Path steps can contain the following elements and operators.

    • Nomes de chave.Key names. Por exemplo, $.name e $."first name".For example, $.name and $."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.If the key name starts with a dollar sign or contains special characters such as spaces, surround it with quotes.

    • Elementos da matriz.Array elements. Por exemplo, $.product[3].For example, $.product[3]. Matrizes são baseadas em zero.Arrays are zero-based.

    • O operador ponto (.) indica um membro de um objeto.The dot operator (.) indicates a member of an object. Por exemplo, em $.people[1].surname, surname é um filho de people.For example, in $.people[1].surname, surname is a child of people.

ExemplosExamples

Os exemplos nesta seção fazem referência ao texto JSON a seguir.The examples in this section reference the following JSON text.

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

A tabela a seguir mostra alguns exemplos de expressões de demarcador.The following table shows some examples of path expressions.

Expressão de demarcadorPath expression ValorValue
$.people[0].name$.people[0].name JohnJohn
$.people[1]$.people[1] { "name": "Jane", "surname": null, "active": true }{ "name": "Jane", "surname": null, "active": true }
$.people[1].surname$.people[1].surname nulonull
$ { "people": [ { "name": "John", "surname": "Doe" },{ "people": [ { "name": "John", "surname": "Doe" },
{ "name": "Jane", "surname": null, "active": true } ] }{ "name": "Jane", "surname": null, "active": true } ] }

Como as funções internas tratam caminhos duplicadosHow built-in functions handle duplicate paths

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.If the JSON text contains duplicate properties - for example, two keys with the same name on the same level - the JSON_VALUE and JSON_QUERY functions return only the first value that matches the path. Para analisar um objeto JSON que contém chaves duplicadas e retornar todos os valores, use OPENJSON, conforme mostrado no exemplo a seguir.To parse a JSON object that contains duplicate keys and return all values, use OPENJSON, as shown in the following example.

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 AzureLearn more about JSON in SQL Server and Azure SQL Database

Vídeos da MicrosoftMicrosoft videos

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:For a visual introduction to the built-in JSON support in SQL Server and Azure SQL Database, see the following videos:

Consulte TambémSee Also

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