Exemplos de JSON_VALUE() no SQL Server (T-SQL)

Ao usar JSON com SQL Server, você pode usar o JSON_VALUE() função para retornar um valor escalar de uma string JSON.

Para usar esta função, você fornece dois argumentos; a expressão JSON e a propriedade a ser extraída.

Sintaxe

A sintaxe fica assim:

JSON_VALUE ( expression , path )

Onde expression é a expressão de string JSON e path é a propriedade que você deseja extrair dessa expressão.

O argumento de caminho pode incluir um modo de caminho opcional componente. Este modo de caminho opcional pode ser um valor de lax ou strict . Esse valor, se houver, vem antes do cifrão.

Exemplo 1 – Uso básico

Aqui está um exemplo para demonstrar o uso básico do JSON_VALUE() função.

SELECT JSON_VALUE('{"Name": "Bruce"}', '$.Name') AS 'Result';

Resultado:

+----------+
| Result   |
|----------|
| Bruce    |
+----------+

Neste exemplo:

O {"Name": "Bruce"} argumento é a expressão JSON (pequena, mas ainda uma expressão JSON válida). As expressões JSON consistem em um par chave/valor. Nesse caso, Name é a chave, Bruce é o seu valor.
O $.Name argumento é o caminho. Este caminho faz referência ao valor do Name chave da expressão JSON. Assim, podemos extrair o valor referenciando o nome do par.

Exemplo 2 – Matrizes

Para extrair um valor de uma matriz, faça referência ao seu índice entre colchetes, seguido pela chave relevante. Aqui está um exemplo:

/* 
CREATE THE ARRAY (and put into a variable called @data)
*/
DECLARE @data NVARCHAR(4000)
SET @data=N'{
    "Cities": [
        {
            "Name": "Kabul",
            "CountryCode": "AFG",
            "District": "Kabol",
            "Population": 1780000
        },
        {
            "Name": "Qandahar",
            "CountryCode": "AFG",
            "District": "Qandahar",
            "Population": 237500
        }
    ]
}'

/* 
QUERY THE ARRAY
*/
SELECT 
  JSON_VALUE(@data,'$.Cities[0].Name') AS 'Name',
  JSON_VALUE(@data,'$.Cities[0].CountryCode') AS 'Country Code',
  JSON_VALUE(@data,'$.Cities[0].District') AS 'District',
  JSON_VALUE(@data,'$.Cities[0].Population') AS 'Population'

UNION ALL

SELECT 
  JSON_VALUE(@data,'$.Cities[1].Name') AS 'Name',
  JSON_VALUE(@data,'$.Cities[1].CountryCode') AS 'Country Code',
  JSON_VALUE(@data,'$.Cities[1].District') AS 'District',
  JSON_VALUE(@data,'$.Cities[1].Population') AS 'Population';

Resultado:

+----------+----------------+------------+--------------+
| Name     | Country Code   | District   | Population   |
|----------+----------------+------------+--------------|
| Kabul    | AFG            | Kabol      | 1780000      |
| Qandahar | AFG            | Qandahar   | 237500       |
+----------+----------------+------------+--------------+

Portanto, neste exemplo, criamos um array JSON e o colocamos em uma variável chamada @data . Em seguida, executamos uma consulta, usando @data como o primeiro argumento do JSON_VALUE() função (isso ocorre porque @data contém a expressão JSON).

Arrays usam numeração baseada em zero, então para extrair o primeiro item precisamos usar Cities[0] , a segunda Cities[1] , e assim por diante.

Exemplo 3 – Um exemplo de banco de dados

Se pudéssemos colocar os dados do exemplo anterior em um banco de dados, poderíamos reescrever a consulta da seguinte forma:

SELECT 
  JSON_VALUE(Document,'$.Cities[0].Name') AS 'Name',
  JSON_VALUE(Document,'$.Cities[0].CountryCode') AS 'Country Code',
  JSON_VALUE(Document,'$.Cities[0].District') AS 'District',
  JSON_VALUE(Document,'$.Cities[0].Population') AS 'Population'
FROM Json_Documents

UNION ALL

SELECT 
  JSON_VALUE(Document,'$.Cities[1].Name') AS 'Name',
  JSON_VALUE(Document,'$.Cities[1].CountryCode') AS 'Country Code',
  JSON_VALUE(Document,'$.Cities[1].District') AS 'District',
  JSON_VALUE(Document,'$.Cities[1].Population') AS 'Population'
FROM Json_Documents

Resultado:

+----------+----------------+------------+--------------+
| Name     | Country Code   | District   | Population   |
|----------+----------------+------------+--------------|
| Kabul    | AFG            | Kabol      | 1780000      |
| Qandahar | AFG            | Qandahar   | 237500       |
+----------+----------------+------------+--------------+

Isso pressupõe que o documento JSON seja armazenado em uma coluna chamada Document , que está em uma tabela chamada Json_Documents .

Exemplo 4 – Modo de caminho

Como mencionado, você também tem a opção de especificar o modo de caminho. Isso pode ser lax ou strict .

O valor do modo de caminho determina o que acontece quando a expressão de caminho contém um erro. Especificamente:

Em relaxado modo, a função retornará 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 contém um nome key, a função retorna null, mas não gera um erro.
Em estrito modo, a função gera um erro se a expressão de caminho contiver um erro.

O valor padrão é lax .

Aqui está um exemplo para demonstrar a diferença entre esses dois modos.

Erro no modo lax

Aqui está o que acontece quando a expressão de caminho contém um erro no modo lax.

SELECT JSON_VALUE('{"Name": "Bruce"}', 'lax $.Hobbies') AS 'Result';

Resultado:

+----------+
| Result   |
|----------|
| NULL     |
+----------+

Neste exemplo, estamos tentando fazer referência a Hobbies , mas essa chave não existe no documento JSON. Nesse caso, obtemos um valor nulo (porque estamos usando o modo lax).

Erro no modo estrito

Aqui está o que acontece quando executamos o mesmo código no modo estrito.

SELECT JSON_VALUE('{"Name": "Bruce"}', 'strict $.Hobbies') AS 'Result';

Resultado:

Msg 13608, Level 16, State 1, Line 1
Property cannot be found on the specified JSON path.

Conforme esperado, o modo estrito resulta na exibição de uma mensagem de erro.

Exemplo 5 – Retornando objetos e matrizes

O JSON_VALUE() função não retorna objetos e arrays. Se você quiser retornar um objeto ou um array, use o JSON_QUERY() função em vez disso. Aqui está um exemplo onde eu uso ambas as funções dentro de uma consulta.

DECLARE @data NVARCHAR(4000)
SET @data=N'{  
    "Suspect": {    
       "Name": "Homer Simpson",  
       "Address": {    
         "City": "Mae Sai",  
         "Province": "Chiang Rai",  
         "Country": "Thailand"  
       },  
       "Hobbies": ["Eating", "Sleeping", "Base Jumping"]  
    }
 }'
 SELECT 
   JSON_VALUE(@data,'$.Suspect.Name') AS 'Name',
   JSON_VALUE(@data,'$.Suspect.Address.Country') AS 'Country',
   JSON_QUERY(@data,'$.Suspect.Hobbies') AS 'Hobbies',
   JSON_VALUE(@data,'$.Suspect.Hobbies[2]') AS 'Last Hobby';

Resultado:

+---------------+-----------+----------------------------------------+--------------+
| Name          | Country   | Hobbies                                | Last Hobby   |
|---------------+-----------+----------------------------------------+--------------|
| Homer Simpson | Thailand  | ["Eating", "Sleeping", "Base Jumping"] | Base Jumping |
+---------------+-----------+----------------------------------------+--------------+

Neste caso, eu uso JSON_VALUE() para retornar vários valores escalares e JSON_QUERY() para retornar uma matriz.

Portanto, se você precisar retornar um objeto ou uma matriz (incluindo todo o documento JSON), consulte JSON_QUERY() Exemplos no SQL Server.