Função JSON_QUERY() no Oracle

No Oracle Database, o JSON_QUERY() A função seleciona e retorna um ou mais valores de dados JSON e retorna esses valores.

Você pode usar a função para recuperar fragmentos de um documento JSON.

Sintaxe

A sintaxe fica assim:

JSON_QUERY
  ( expr [ FORMAT JSON ], JSON_basic_path_expression
    [ JSON_query_returning_clause ] [ JSON_query_wrapper_clause ]
    [ JSON_query_on_error_clause ] [ JSON_query_on_empty_clause ]
  )

Onde:

expr é o documento JSON que você deseja consultar
JSON_basic_path_expression é o caminho SQL/JSON que você deseja retornar desse documento JSON. A função usa a expressão de caminho para avaliar expr e encontre um ou mais valores JSON que correspondam ou satisfaçam a expressão de caminho. A expressão de caminho deve ser um literal de texto.
JSON_query_returning_clause especifica o tipo de dados e o formato da cadeia de caracteres retornada pela função.
JSON_query_wrapper_clause controla se a função envolve os valores retornados em um array wrapper (colchetes ([] )).
JSON_query_on_error_clause especifica o valor retornado quando ocorrem determinados erros.
JSON_query_on_empty_clause especifica o valor retornado se nenhuma correspondência for encontrada quando os dados JSON forem avaliados usando a expressão de caminho SQL/JSON.

Consulte a documentação do Oracle para obter uma explicação detalhada das cláusulas opcionais.

Exemplo

Aqui está um exemplo para demonstrar como o JSON_QUERY() função funciona:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$')
FROM DUAL;

Resultado:

{"a":1,"b":2,"c":3}

Usar o cifrão por si só retorna toda a string de dados JSON.

Com invólucro

Você pode usar o WITH WRAPPER cláusula para envolver o resultado em um wrapper de array:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH WRAPPER)
FROM DUAL;

Resultado:

[{"a":1,"b":2,"c":3}]

Você deve especificar esta cláusula se a expressão de caminho corresponder a um único valor escalar (um valor que não seja um objeto JSON ou uma matriz JSON) ou vários valores de qualquer tipo.

Por exemplo, retornar o seguinte valor escalar deve ser feito com o WITH WRAPPER cláusula:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH WRAPPER)
FROM DUAL;

Resultado:

[2]

Omitindo o WITH WRAPPER cláusula ao retornar um valor escalar resulta em um valor nulo sendo retornado:

SET NULL 'null';
SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b')
FROM DUAL;

Resultado:

null

Por padrão, SQLcl e SQL*Plus retornam um espaço em branco sempre que null ocorre como resultado de um SQL SELECT demonstração.

No entanto, você pode usar SET NULL para especificar uma string diferente a ser retornada. Aqui eu especifiquei que a string null deve ser devolvido.

Com wrapper condicional

Alternativamente, você pode usar o WITH CONDITIONAL WRAPPER cláusula para incluir o wrapper de matriz apenas se a expressão de caminho corresponder a um único valor escalar ou a vários valores de qualquer tipo. Se a expressão de caminho corresponder a um único objeto JSON ou matriz JSON, o wrapper da matriz será omitido:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH CONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH CONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Resultado:

                    r1     r2 
______________________ ______ 
{"a":1,"b":2,"c":3}    [2]

Nesse caso, apenas o valor escalar tem o wrapper de matriz aplicado.

Só para ficar claro, aqui está com um wrapper incondicional:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH UNCONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH UNCONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Resultado:

                      r1     r2 
________________________ ______ 
[{"a":1,"b":2,"c":3}]    [2]

Desta vez, ambos os resultados têm o wrapper aplicado.

Observe que WITH UNCONDITIONAL WRAPPER é o equivalente a WITH WRAPPER .

Tratamento de erros

Há cinco cláusulas que você pode usar para especificar o que retornar sempre que ocorrerem determinados tipos de erros. As cláusulas são:

NULL ON ERROR – Retorna null quando ocorre um erro. Este é o padrão.
ERROR ON ERROR – Retorna o erro apropriado do Oracle quando ocorre um erro.
EMPTY ON ERROR – Especificar esta cláusula é equivalente a especificar EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Retorna um array JSON vazio ([] ) quando ocorre um erro.
EMPTY OBJECT ON ERROR – Retorna um objeto JSON vazio ({} ) quando ocorre um erro.

Aqui está um exemplo:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' NULL ON ERROR) AS "r1",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON ERROR) AS "r2",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY OBJECT ON ERROR) AS "r3"
FROM DUAL;

Resultado:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Aqui está com o ERROR ON ERROR cláusula:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' ERROR ON ERROR)
FROM DUAL;

Resultado:

Error report -
ORA-40462: JSON_VALUE evaluated to no value

Essas cláusulas de erro são para lidar com os seguintes erros:

O primeiro argumento não é um dado JSON bem formado usando sintaxe JSON estrita ou relaxada
Nenhuma correspondência é encontrada quando os dados JSON são avaliados usando a expressão de caminho SQL/JSON. Você pode modificar o comportamento desse tipo de erro especificando a JSON_query_on_empty_clause .
O tipo de dados do valor de retorno não é grande o suficiente para conter a cadeia de caracteres de retorno
A função corresponde a um único valor escalar ou a vários valores de qualquer tipo, e uma cláusula wrapper não é especificada

Gerenciando resultados vazios

Você também pode usar uma cláusula para especificar o valor retornado se nenhuma correspondência for encontrada. Essa cláusula permite especificar um resultado diferente para esse tipo de erro do resultado especificado com as cláusulas de erro.

Essas cláusulas são:

NULL ON EMPTY – Retorna null quando nenhuma correspondência é encontrada.
ERROR ON EMPTY – Retorna o erro apropriado do Oracle quando nenhuma correspondência é encontrada.
EMPTY ON EMPTY – Especificar esta cláusula é equivalente a especificar EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Retorna um array JSON vazio ([] ) quando nenhuma correspondência for encontrada.
EMPTY OBJECT ON EMPTY – Retorna um objeto JSON vazio ({} ) quando nenhuma correspondência for encontrada.

Exemplo:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON EMPTY)
FROM DUAL;

Resultado:

[]

Se você omitir essa cláusula, a cláusula de erro determinará o valor retornado quando nenhuma correspondência for encontrada.