Función JSON_VALUE() en Oracle

En Oracle Database, el JSON_VALUE() encuentra un valor JSON escalar especificado en datos JSON y lo devuelve como un valor SQL.

Sintaxis

La sintaxis es así:

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 ]
  )

Dónde:

• expr es el documento JSON que desea consultar
• JSON_basic_path_expression es la expresión de ruta de SQL/JSON. Esta expresión de ruta se utiliza para evaluar expr y busque un valor JSON escalar que coincida o satisfaga la expresión de la ruta.
• JSON_query_returning_clause especifica el tipo de datos y el formato del valor devuelto por la función.
• JSON_query_on_error_clause especifica el valor devuelto cuando ocurren ciertos errores.
• JSON_query_on_empty_clause especifica el valor devuelto si no se encuentra ninguna coincidencia cuando los datos JSON se evalúan mediante la expresión de ruta SQL/JSON.
• JSON_value_on_mismatch_clause se puede usar para especificar ignorar, error o nulo para casos de error como datos adicionales, datos faltantes y errores de tipo. Se puede aplicar de forma general o caso por caso.

Consulte la documentación de Oracle para obtener una explicación detallada de las cláusulas opcionales.

Ejemplo

Aquí hay un ejemplo para demostrar cómo JSON_VALUE() la función funciona:

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

Resultado:

2

En este caso especifiqué $.b para devolver el valor escalar en b .

Aquí hay un ejemplo de devolver un valor de una matriz:

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

Resultado:

c

Las matrices están basadas en cero, por lo que $[2] devuelve el tercer elemento de la matriz.

Gestión de errores

Hay tres cláusulas que puede usar para especificar qué devolver cada vez que ocurran ciertos tipos de errores. Las cláusulas son:

• NULL ON ERROR – Devuelve nulo cuando se produce un error. Este es el valor predeterminado.
• ERROR ON ERROR – Devuelve el error de Oracle apropiado cuando ocurre un error.
• DEFAULT literal ON ERROR – Devuelve literal cuando se produce un error. El tipo de datos de literal debe coincidir con el tipo de datos del valor devuelto por la función.

He aquí un ejemplo:

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!   

Aquí está con el 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

Las cláusulas de error anteriores son para manejar los siguientes errores:

• El primer argumento no son datos JSON bien formados con sintaxis JSON estricta o laxa
• Se encuentra un valor no escalar cuando los datos JSON se evalúan mediante la expresión de ruta SQL/JSON
• No se encuentra ninguna coincidencia cuando los datos JSON se evalúan mediante la expresión de ruta SQL/JSON. Puede anular el comportamiento de este tipo de error especificando JSON_value_on_empty_clause .
• El tipo de datos del valor devuelto no es lo suficientemente grande para contener el valor devuelto

Manejo de resultados vacíos

También puede usar una cláusula para especificar el valor devuelto si no se encuentra ninguna coincidencia. Esta cláusula le permite especificar un resultado diferente para este tipo de error que el resultado especificado con las cláusulas de error.

Estas cláusulas son:

• NULL ON EMPTY – Devuelve nulo cuando no se encuentra ninguna coincidencia.
• ERROR ON EMPTY – Devuelve el error de Oracle apropiado cuando no se encuentra ninguna coincidencia.
• DEFAULT literal ON EMPTY – Devuelve literal cuando no se encuentra ninguna coincidencia. El tipo de datos de literal debe coincidir con el tipo de datos del valor devuelto por esta función.

Ejemplo:

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

Resultado:

Dang!

Si omite esta cláusula, la cláusula de error determina el valor devuelto cuando no se encuentra ninguna coincidencia.