Función JSON_QUERY() en Oracle

En Oracle Database, JSON_QUERY() La función selecciona y devuelve uno o más valores de los datos JSON y devuelve esos valores.

Puede utilizar la función para recuperar fragmentos de un documento JSON.

Sintaxis

La sintaxis es así:

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

Dónde:

expr es el documento JSON que desea consultar
JSON_basic_path_expression es la ruta SQL/JSON que desea devolver desde ese documento JSON. La función usa la expresión de ruta para evaluar expr y encuentre uno o más valores JSON que coincidan o satisfagan la expresión de la ruta. La expresión de ruta debe ser un texto literal.
JSON_query_returning_clause especifica el tipo de datos y el formato de la cadena de caracteres devuelta por la función.
JSON_query_wrapper_clause controla si la función envuelve los valores devueltos en un contenedor de matriz (corchetes ([] )).
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.

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_QUERY() la función funciona:

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

Resultado:

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

El uso del signo de dólar por sí solo devuelve la cadena completa de datos JSON.

Con envoltorio

Puedes usar el WITH WRAPPER cláusula para envolver el resultado en un contenedor de matriz:

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

Resultado:

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

Debe especificar esta cláusula si la expresión de ruta coincide con un solo valor escalar (un valor que no es un objeto JSON o una matriz JSON) o varios valores de cualquier tipo.

Por ejemplo, devolver el siguiente valor escalar debe hacerse con WITH WRAPPER cláusula:

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

Resultado:

[2]

Omitiendo el WITH WRAPPER cuando se devuelve un valor escalar, se devuelve un valor nulo:

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

Resultado:

null

De forma predeterminada, SQLcl y SQL*Plus devuelven un espacio en blanco cada vez que null ocurre como resultado de un SQL SELECT declaración.

Sin embargo, puede usar SET NULL para especificar una cadena diferente a devolver. Aquí especifiqué que la cadena null debe ser devuelto.

Con contenedor condicional

Alternativamente, puede usar el WITH CONDITIONAL WRAPPER cláusula para incluir el contenedor de matriz solo si la expresión de ruta coincide con un solo valor escalar o varios valores de cualquier tipo. Si la expresión de la ruta coincide con un solo objeto JSON o una matriz JSON, se omite el envoltorio de la matriz:

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]

En este caso, solo el valor escalar tiene aplicado el contenedor de matriz.

Para que quede claro, aquí está con un envoltorio 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]

Esta vez ambos resultados tienen aplicado el envoltorio.

Tenga en cuenta que WITH UNCONDITIONAL WRAPPER es el equivalente de WITH WRAPPER .

Gestión de errores

Hay cinco 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.
EMPTY ON ERROR – Especificar esta cláusula es equivalente a especificar EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Devuelve una matriz JSON vacía ([] ) cuando se produce un error.
EMPTY OBJECT ON ERROR – Devuelve un objeto JSON vacío ({} ) cuando se produce un error.

He aquí un ejemplo:

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    []    {}

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

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

El primer argumento no son datos JSON bien formados con sintaxis JSON estricta o laxa
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_query_on_empty_clause .
El tipo de datos del valor de retorno no es lo suficientemente grande para contener la cadena de caracteres de retorno
La función coincide con un único valor escalar o con varios valores de cualquier tipo y no se especifica una cláusula contenedora

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.
EMPTY ON EMPTY – Especificar esta cláusula es equivalente a especificar EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Devuelve una matriz JSON vacía ([] ) cuando no se encuentra ninguna coincidencia.
EMPTY OBJECT ON EMPTY – Devuelve un objeto JSON vacío ({} ) cuando no se encuentra ninguna coincidencia.

Ejemplo:

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

Resultado:

[]

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