Função JSON_VALUE() no Oracle

No Oracle Database, o JSON_VALUE() A função encontra um valor JSON escalar especificado nos dados JSON e o retorna como um valor SQL.

Sintaxe

A sintaxe fica assim:

JSON_VALUE
  ( expr [ FORMAT JSON ], JSON_basic_path_expression
    [ JSON_value_returning_clause ] [ JSON_value_on_error_clause ]
    [ JSON_value_on_empty_clause ][ JSON_value_on_mismatch_clause ]
  )

Onde:

expr é o documento JSON que você deseja consultar
JSON_basic_path_expression é a expressão de caminho SQL/JSON. Essa expressão de caminho é usada para avaliar expr e encontre um valor JSON escalar que corresponda ou satisfaça a expressão de caminho.
JSON_query_returning_clause especifica o tipo de dados e o formato do valor retornado pela função.
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.
JSON_value_on_mismatch_clause pode ser usado para especificar ignorar, erro ou nulo para casos de erro, como dados extras, dados ausentes e erros de tipo. Pode ser aplicado de forma geral ou caso a caso.

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_VALUE() função funciona:

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

Resultado:

Neste caso eu especifiquei $.b para retornar o valor escalar em b .

Aqui está um exemplo de retorno de um valor de uma matriz:

SELECT 
    JSON_VALUE('["a", "b", "c"]', '$[2]')
FROM DUAL;

Resultado:

As matrizes são baseadas em zero e, portanto, $[2] retorna o terceiro elemento da matriz.

Tratamento de erros

Existem três 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.
DEFAULT literal ON ERROR – Retorna literal quando ocorre um erro. O tipo de dados de literal deve corresponder ao tipo de dados do valor retornado pela função.

Aqui está um exemplo:

SELECT 
    JSON_VALUE('["a", "b", "c"]', '$[3]' NULL ON ERROR) AS "r1",
    JSON_VALUE('["a", "b", "c"]', '$[3]' DEFAULT 'Oops!' ON ERROR) AS "r2"
FROM DUAL;

Resultado:

     r1       r2 
_______ ________ 
null    Oops!

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

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

Resultado:

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

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

O primeiro argumento não é um dado JSON bem formado usando sintaxe JSON estrita ou relaxada
Um valor não escalar é encontrado quando os dados JSON são avaliados usando a expressão de caminho SQL/JSON
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_value_on_empty_clause .
O tipo de dados do valor de retorno não é grande o suficiente para conter o valor de retorno

Gerenciando resultados vazios

Você também pode usar uma cláusula para especificar o valor retornado se nenhuma correspondência for encontrada. Esta cláusula permite especificar um resultado diferente para esse tipo de erro do que o 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.
DEFAULT literal ON EMPTY – Retorna literal quando nenhuma correspondência for encontrada. O tipo de dados de literal deve corresponder ao tipo de dados do valor retornado por esta função.

Exemplo:

SELECT 
    JSON_VALUE('["a", "b", "c"]', '$[3]' DEFAULT 'Dang!' ON EMPTY)
FROM DUAL;

Resultado:

Dang!

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