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 de SQL do Azure Azure Synapse Analytics Ponto de extremidade de análises SQL 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 uma 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.

Convenções de sintaxe de Transact-SQL

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 o texto JSON.

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

caminho

Um demarcador 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 path.

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

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

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

COM WRAPPER DE MATRIZ

Observação

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

A função SQL JSON_QUERY ANSI é usada atualmente para retornar um objeto JSON ou uma matriz em um caminho especificado. Com o suporte para curingas de matriz na expressão de caminho SQL/JSON introduzida na versão prévia JSON_QUERY do SQL Server 2025 (17.x), pode ser usado para retornar propriedades especificadas de elementos em uma matriz JSON em que cada elemento é um objeto JSON. Como pesquisas curinga podem retornar vários valores, especifique a WITH ARRAY WRAPPER cláusula em uma expressão de consulta JSON juntamente 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 só terá suporte 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 em que cada elemento é um objeto JSON válido. Agora, a JSON_QUERY função pode ser usada com suporte curinga 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 retornado usando JSON_QUERY WITH ARRAY WRAPPER.

Caminho	Valor retornado
`$.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 retornado

Retorna um fragmento JSON do tipo nvarchar(max). A ordenação do valor retornado é a mesma que a ordenação da expressão de entrada.

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

No modo incerto, JSON_QUERY retorna nulo.
No modo estrito, JSON_QUERY retorna um erro.

Comentários

Modo incerto 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 incerto e no modo estrito. Para obter mais informações sobre a especificação de modo de demarcador opcional (incerto ou estrito), confira Expressões de demarcador JSON (SQL Server).

Caminho	Valor retornado no modo incerto	Valor retornado no modo estrito	Obter mais informações
`$`	Retorna o texto JSON inteiro.	Retorna o texto JSON inteiro.
`$.info.type`	`NULL`	Erro	Não é um objeto nem uma matriz. Use o `JSON_VALUE` em vez disso.
`$.info.address.town`	`NULL`	Erro	Não é um objeto nem uma matriz. Use o `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 retornado JSON_QUERY.

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

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 FOR JSON.

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

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

O exemplo a seguir mostra o uso da WITH ARRAY WRAPPERJSON_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;

Veja aqui o conjunto de resultados.

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

Compartilhar via

JSON_QUERY (Transact-SQL)

Sintaxe

Argumentos

expressão

caminho

COM WRAPPER DE MATRIZ

Valor retornado

Comentários

Modo incerto 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. Usar WITH ARRAY WRAPPER com JSON_QUERY função

Conteúdo relacionado

Comentários

Recursos adicionais