JSON_QUERY (Transact-SQL)

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics SQL analytics endpoint in Microsoft Fabric Warehouse em Microsoft Fabric SQL database in Microsoft Fabric

A JSON_QUERY sintaxe 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

Syntax

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

Arguments

expression

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.

path

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 do 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 no Mecanismo de Banco de Dados SQL.

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

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

COM INVÓLUCRO DE MATRIZ

Note

WITH ARRAY WRAPPER está atualmente em pré-visualização e disponível apenas no 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 array na expressão de caminho SQL/JSON introduzido no SQL Server 2025 (17.x), JSON_QUERY pode ser usado para devolver propriedades especificadas de elementos num array 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 AS JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@example.com",
    "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, '$.credit_cards[*].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.

Path	Valor de retorno
`$.credit_cards[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.

Remarks

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 Expressões de caminho JSON no Mecanismo de Banco de Dados SQL.

Path	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`	Error	Não é um objeto ou matriz. Use `JSON_VALUE` em vez disso.
`$.info.address.town`	`NULL`	Error	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`	Error	Não é uma matriz.
`$.info.none`	`NULL`	Error	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 parâmetro path .

Examples

A. 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@example.com", "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"]

Comentários

Esta página foi útil?

Last updated on 2025-11-18