JSON_QUERY (Transact-SQL)

2025-05-19

Aplica-se a: SQL Server 2016 (13.x) e posterior Banco de Dados SQL do Azure Instância Gerenciada SQL do Azure ponto de extremidade do Azure Synapse Analytics SQL Analytics no Microsoft Fabric Warehouse no Microsoft Fabric

Extrai um objeto ou uma matriz de uma cadeia de caracteres JSON.

Para extrair um valor escalar de uma cadeia de caracteres JSON em vez de um objeto ou matriz, consulte JSON_VALUE. Para obter informações sobre as diferenças entre JSON_VALUE e JSON_QUERY, consulte Comparar JSON_VALUE e JSON_QUERY.

Transact-SQL convenções de sintaxe

Sintaxe

JSON_QUERY ( expression [ , path ] [WITH ARRAY WRAPPER])

Argumentos

expressão

Uma expressão. Normalmente, o nome de uma variável ou de uma coluna que contém texto JSON.

Se JSON_QUERY encontrar JSON que não é válido na expressão antes de encontrar o valor identificado por caminho, a função retornará um erro. Se JSON_QUERY não encontrar o valor identificado por caminho, ele verificará todo o texto e retornará um erro se encontrar JSON que não é válido em nenhum lugar na expressão.

caminho

Um caminho JSON que especifica o objeto ou a matriz a ser extraída.

No SQL Server 2017 (14.x) e no Banco de Dados SQL do Azure, você pode fornecer uma variável como o valor de caminho.

O caminho JSON pode especificar o modo lax ou strict para análise. Se você não especificar o modo de análise, o modo lax será o padrão. Para obter mais informações, consulte Expressões de caminho JSON (SQL Server).

O valor padrão para caminho é $. Como resultado, se você não fornecer um valor para caminho, JSON_QUERY retornará a entrada expressão.

Se o formato de caminho não for válido, JSON_QUERY retornará um erro.

COM INVÓLUCRO DE MATRIZ

Observação

WITH ARRAY WRAPPER está atualmente em pré-visualização e apenas disponível na Pré-visualização do SQL Server 2025 (17.x).

A função ANSI SQL JSON_QUERY é atualmente usada para retornar um objeto JSON ou matriz em um caminho especificado. Com o suporte para curingas de matriz na expressão de caminho SQL/JSON introduzido no SQL Server 2025 (17.x) Preview, JSON_QUERY pode ser usado para retornar propriedades especificadas de elementos em uma matriz JSON onde cada elemento é um objeto JSON. Como as pesquisas curinga podem retornar vários valores, especifique a WITH ARRAY WRAPPER cláusula em uma expressão de consulta JSON junto com uma expressão de caminho SQL/JSON com curinga ou intervalo ou lista para retornar os valores como uma matriz JSON. WITH ARRAY WRAPPER A cláusula é suportada somente se a entrada for um tipo JSON .

Considere o seguinte documento JSON:

declare @j JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "gender": "Female",
    "ip_address": "148.199.129.123",
    "credit_cards": [
        {
            "type": "jcb",
            "card#": "3545138777072343",
            "currency": "Koruna"
        },
        {
            "type": "diners-club-carte-blanche",
            "card#": "30282304348533",
            "currency": "Dong"
        },
        {
            "type": "jcb",
            "card#": "3585303288595361",
            "currency": "Yuan Renminbi"
        },
        {
            "type": "maestro",
            "card#": "675984450768756054",
            "currency": "Rupiah"
        },
        {
            "type": "instapayment",
            "card#": "6397068371771473",
            "currency": "Euro"
        }
    ]
}';

O caminho $.credit_cards aponta para uma matriz JSON onde cada elemento é um objeto JSON válido. Agora, a função pode ser usada com suporte a curinga JSON_QUERY de matriz para retornar todos ou valores específicos da type propriedade, como:

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

A tabela a seguir mostra vários exemplos de expressão de caminho SQL/JSON com curinga e o valor de retorno usando JSON_QUERY WITH ARRAY WRAPPER.

Caminho	Valor de retorno
`$.creditcards[0].type`	`["jcb"]`
`$.credit_cards[*].type`	`["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]`
`$.credit_cards[0, 2].type`	`["jcb","jcb"]`
`$.credit_cards[1 to 3].type`	`["diners-club-carte-blanche","jcb","maestro"]`
`$.credit_cards[last].type`	`["instapayment"]`
`$.credit_cards[last, 0].type`	`["instapayment","jcb"]`
`$.credit_cards[last, last].type`	`["instapayment","instapayment"]`
`$.credit_cards[ 0, 2, 4].type`	`["jcb","jcb","instapayment"]`

Valor de retorno

Retorna um fragmento JSON do tipo nvarchar(max). O agrupamento do valor retornado é o mesmo que o agrupamento da expressão de entrada.

Se o valor não for um objeto ou uma matriz:

No modo lax, JSON_QUERY retorna null.
No modo estrito, JSON_QUERY retorna um erro.

Comentários

Modo lax e modo estrito

Considere o seguinte texto JSON:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

A tabela a seguir compara o comportamento de JSON_QUERY no modo lax e no modo estrito. Para obter mais informações sobre a especificação do modo de caminho opcional (lax ou strict), consulte JSON Path Expressions (SQL Server).

Caminho	Valor de retorno no modo lax	Valor de retorno no modo estrito	Mais informações
`$`	Retorna todo o texto JSON.	Retorna todo o texto JSON.
`$.info.type`	`NULL`	Erro	Não é um objeto ou matriz. Use `JSON_VALUE` em vez disso.
`$.info.address.town`	`NULL`	Erro	Não é um objeto ou matriz. Use `JSON_VALUE` em vez disso.
`$.info."address"`	`N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'`	`N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'`
`$.info.tags`	`N'[ "Sport", "Water polo"]'`	`N'[ "Sport", "Water polo"]'`
`$.info.type[0]`	`NULL`	Erro	Não é uma matriz.
`$.info.none`	`NULL`	Erro	A propriedade não existe.

Usar JSON_QUERY com FOR JSON

JSON_QUERY retorna um fragmento JSON válido. Como resultado, FOR JSON não escapa de caracteres especiais no valor de retorno JSON_QUERY.

Se você estiver retornando resultados com FOR JSON e estiver incluindo dados que já estão no formato JSON (em uma coluna ou como resultado de uma expressão), envolva os dados JSON com JSON_QUERY sem o path parâmetro.

Exemplos

Um. Retornar um fragmento JSON

O exemplo a seguir mostra como retornar um fragmento JSON de uma coluna CustomFields nos resultados da consulta.

SELECT PersonID,
       FullName,
       JSON_QUERY(CustomFields, '$.OtherLanguages') AS Languages
FROM Application.People;

B. Incluir fragmentos JSON na saída FOR JSON

O exemplo a seguir mostra como incluir fragmentos JSON na saída da cláusula JSON FOR.

SELECT StockItemID,
       StockItemName,
       JSON_QUERY(Tags) AS Tags,
       JSON_QUERY(CONCAT('["', ValidFrom, '","', ValidTo, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;

C. Use WITH ARRAY WRAPPER com função JSON_QUERY

O exemplo a seguir mostra o uso de WITH ARRAY WRAPPER com a JSON_QUERY função para retornar vários elementos de uma matriz JSON:

DECLARE @j JSON = ' {"id":2,"first_name":"Mamie","last_name":"Baudassi","email":"mbaudassi1@abc.net.au","gender":"Female","ip_address":"148.199.129.123","credit_cards":[{"type":"jcb","card#":"3545138777072343","currency":"Koruna"},{"type":"diners-club-carte-blanche","card#":"30282304348533","currency":"Dong"},{"type":"jcb","card#":"3585303288595361","currency":"Yuan Renminbi"},{"type":"maestro","card#":"675984450768756054","currency":"Rupiah"},{"type":"instapayment","card#":"6397068371771473","currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;

Aqui está o conjunto de resultados.

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

Partilhar via

JSON_QUERY (Transact-SQL)

Sintaxe

Argumentos

expressão

caminho

COM INVÓLUCRO DE MATRIZ

Valor de retorno

Comentários

Modo lax e modo estrito

Usar JSON_QUERY com FOR JSON

Exemplos

Um. Retornar um fragmento JSON

B. Incluir fragmentos JSON na saída FOR JSON

C. Use WITH ARRAY WRAPPER com função JSON_QUERY

Conteúdo relacionado

Comentários

Recursos adicionais