Esta página foi traduzida pela API Cloud Translation.
Switch to English

Funções JSON

O Cloud Spanner SQL é compatível com funções que ajudam você a recuperar dados armazenados nas strings formatadas como JSON e funções que ajudam a transformar dados em strings formatadas como JSON.

Visão geral da função

Função JSON Descrição
JSON_QUERY Extrai um valor JSON, como uma matriz ou objeto, ou um valor escalar em formato JSON, como uma string, número inteiro ou booleano. Se uma chave JSON usar caracteres JSONPath inválidos, use aspas duplas para inserir caracteres de escape.
JSON_VALUE Extrai um valor escalar, como uma string, número inteiro ou booleano. Remove as aspas mais externas e ignora os valores. Se uma chave JSON usar caracteres JSONPath inválidos, use aspas duplas para inserir caracteres de escape.

JSON_QUERY

JSON_QUERY(json_string_expr, json_path)

Descrição

Extrai um valor JSON, como uma matriz ou objeto, ou um valor escalar em formato JSON, como uma string, número inteiro ou booleano. Se uma chave JSON usar caracteres JSONPath inválidos, use aspas duplas para inserir caracteres de escape.

  • json_string_expr: uma string formatada em JSON. Exemplo:

    {"class" : {"students" : [{"name" : "Jane"}]}}
    
  • json_path: o JSONPath. Identifica os valores que você quer obter da string formatada em JSON. Se json_path retornar um null JSON, isso será convertido em um NULL SQL.

Se você quiser incluir valores não escalares, como matrizes na extração, use JSON_QUERY. Se você quiser apenas extrair valores escalares, como strings, números inteiros e booleanos, use JSON_VALUE.

Tipo de retorno

Um STRING formatado em JSON

Exemplos

SELECT JSON_QUERY(json_text, '$') AS json_text_string
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------------------------------------------------+
| json_text_string                                          |
+-----------------------------------------------------------+
| {"class":{"students":[{"name":"Jane"}]}}                  |
| {"class":{"students":[]}}                                 |
| {"class":{"students":[{"name":"John"},{"name":"Jamie"}]}} |
+-----------------------------------------------------------+
SELECT JSON_QUERY(json_text, '$.class.students[0]') AS first_student
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+
SELECT JSON_QUERY(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name" : null}]}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| NULL              |
| "Jamie"           |
+-------------------+
SELECT JSON_QUERY(json_text, '$.class."students"') AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+

JSON_VALUE

JSON_VALUE(json_string_expr, json_path)

Descrição

Extrai um valor escalar, como uma string, número inteiro ou booleano. Remove as aspas mais externas e ignora os valores de retorno. Se uma chave JSON usar caracteres JSONPath inválidos, use aspas duplas para inserir caracteres de escape.

  • json_string_expr: uma string formatada em JSON. Exemplo:

    {"class" : {"students" : [{"name" : "Jane"}]}}
    
  • json_path: o JSONPath. Identifica os valores que você quer obter da string formatada em JSON. Se json_path retornar um null JSON, isso será convertido em um NULL SQL.

Se você quiser extrair apenas valores escalares, como números de inteiros e strings, use JSON_VALUE. Dica: se você quiser incluir valores não escalares, como matrizes na extração, use JSON_QUERY.

Tipo de retorno

STRING

Exemplos

SELECT JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

Quando a chave JSON usar caracteres inválidos do JSONPath, use aspas duplas para inserir caracteres de escape. Exemplo:

SELECT JSON_VALUE('{"a.b": {"c": "world"}}', '$."a.b".c') as hello;

+-------+
| hello |
+-------+
| world |
+-------+

JSONPath

A maioria das funções JSON transmitem em um parâmetro json_string_expr e json_path. O parâmetro json_string_expr transmite uma string formatada em JSON, e o parâmetro json_path identifica os valores que você quer obter da string formatada em JSON.

É necessário que o parâmetro json_string_expr seja uma string JSON formatada dessa forma:

{"class" : {"students" : [{"name" : "Jane"}]}}

O parâmetro json_path é construído usando o formato JSONPath. Como parte desse formato, é necessário que o parâmetro inicie com o símbolo $, que indica o nível mais externo da string formatada em JSON. É possível identificar valores filho usando pontos. Se o objeto JSON for uma matriz, use colchetes para especificar o índice da matriz. Se as chaves tiverem $, pontos ou colchetes, consulte sobre como inserir caracteres de escape para cada função JSON.

JSONPath Descrição Exemplo Resultado usando o json_string_expr acima
$ Objeto ou elemento raiz "$" {"class":{"students":[{"name":"Jane"}]}}
. Operador filho "$.class.students" [{"name":"Jane"}]
[] Operador subscrito "$.class.students[0]" {"name":"Jane"}

Uma função JSON retornará NULL se o parâmetro json_path não corresponder a um valor em json_string_expr. Se o valor selecionado para uma função escalar não for escalar, como um objeto ou uma matriz, a função retornará NULL.

Se o JSONPath for inválido, a função gerará um erro.