JSON_QUERY función escalar

La función JSON_QUERY devuelve un valor SQL/JSON del texto JSON especificado utilizando una expresión de vía de acceso SQL/JSON.

tipo-datos

Aunque el esquema para esta función es SYSIBM, la función no se puede especificar como un nombre calificado.

expresión-JSON

Una expresión que devuelve un valor que es un tipo de datos de serie incorporado, excepto los tipos de datos siguientes (SQLSTATE 42815):

GRAPHIC
VARGRAPHIC
DBCLOB
BINARY
CHAR FOR BIT DATA
VARCHAR FOR BIT DATA
Un tipo definido por usuario que tiene su origen en cualquiera de los tipos de datos listados previamente.

Si se devuelve un valor de carácter, debe contener datos JSON con un formato correcto (SQLSTATE 22032). Si se devuelve un tipo de datos binario, se interpreta de acuerdo con la cláusula FORMAT explícita o implícita.

FORMAT JSON

expresión-JSON se formatea como datos JSON.

Si expresión-JSON es un tipo de datos de serie de caracteres, se trata como datos JSON.

Si expresión-JSON es un tipo de datos de serie binaria, se interpreta como datos UTF-8.

FORMAT BSON

Especifica que expresión-JSON se formatea como la representación BSON de datos JSON (SQLSTATE 22032). expresión-JSON debe ser un tipo de datos se serie binaria (SQLSTATE 42815).

expresión-vía-json-sql

Expresión que devuelve un valor que es un tipo de datos de serie de caracteres incorporado. La serie se interpreta como una expresión de vía de acceso SQL/JSON y se utiliza para localizar un valor JSON dentro de los datos JSON que se especifican mediante expresión-JSON. Si desea más información sobre la expresión de vía de acceso SQL/JSON, consulte expresión-vía-json-sql.

AS nombre-vía-acceso

Especifica un nombre que se va a utilizar para identificar la expresión-vía-json-sql.

RETURNING tipo-datos

El tipo de datos del resultado puede ser CHAR, VARCHAR, CLOB, VARBINARY o BLOB (SQLSTATE 42815). El valor predeterminado es CLOB (2 GB).

Consulte Sentencia CREATE TABLE para la descripción de los tipos de datos incorporados.

FORMAT JSON

Los datos devueltos se formatean como datos JSON.

ENCODING UTF8: Especifica la codificación para utilizar cuando tipo-datos es un tipo de serie binaria. Esta cláusula solo está permitida para los tipos de serie binaria. El valor predeterminado para las series binarias es UTF-8.

FORMAT BSON

Los datos devueltos se formatean como la representación BSON de los datos JSON (SQLSTATE 22032). tipos-datos debe ser un tipo de datos de serie binaria (SQLSTATE 42815).

WITHOUT ARRAY WRAPPER o WITH ARRAY WRAPPER

Especifica si el valor de salida se ha derivado en una matriz JSON.

WITHOUT ARRAY WRAPPER

El resultado no se ha derivado. Esta cláusula es el valor por omisión.La utilización de una definición de vía de acceso SQL/JSON estricta que se resuelve en una secuencia de dos o más elementos SQL/JSON genera un error (SQLSTATE 2203A). El uso de una definición de vía de acceso SQL/JSON laxa con ON EMPTY que se resuelve en una secuencia de dos o más elementos SQL/JSON generará un error (SQLSTATE 22035).

WITH UNCONDITIONAL ARRAY WRAPPER

El resultado se escribe entre corchetes para crear una matriz JSON.

WITH CONDITIONAL ARRAY WRAPPER

Indica que el resultado se escribe entre corchetes para crear una matriz JSON para cualquiera de los escenarios siguientes:

Se ha devuelto más de un elemento SQL/JSON.
Se ha devuelto un único elemento SQL/JSON que no es una matriz JSON ni un objeto JSON.

KEEP QUOTES o OMIT QUOTES

Especifica si las comillas simples de apertura y cierre se deben eliminar cuando se devuelve una serie escalar.

KEEP QUOTES: Las comillas simples no se eliminan de las series escalares. Esta cláusula es el valor por omisión.
OMIT QUOTES: Las comillas simples se eliminan de las series escalares. Cuando se especifica OMIT QUOTES, no se puede especificar la cláusula WITH ARRAY WRAPPER (SQLSTATE 42601).

ON EMPTY

Especifica el comportamiento cuando expresión-vía-json-sql devuelve una secuencia vacía.

NULL ON EMPTY: Se devuelve un valor nulo. Esta cláusula es el valor por omisión.
ERROR ON EMPTY: Se devuelve un error.
EMPTY ARRAY ON EMPTY: Se devuelve una matriz vacía.
EMPTY OBJECT ON EMPTY: Se devuelve un objeto vacío.

ON ERROR

Especifica el comportamiento cuando JSON_QUERY encuentra un error.

NULL ON ERROR: Se devuelve un valor nulo. Esta cláusula es el valor por omisión.
ERROR ON ERROR: Se devuelve un error.
EMPTY ARRAY ON ERROR: Se devuelve una matriz vacía.
EMPTY OBJECT ON ERROR: Se devuelve un objeto vacío.

El resultado puede ser nulo. Si expresión-JSON es nula, el resultado es el valor nulo.

Notas

Si los marcadores de parámetros no se convierten de forma explícita a un tipo de datos soportado, se devuelve un error (SQLSTATE 42815)

Ejemplo

Devuelva el objeto JSON que está asociado a la clave de nombre del texto JSON.
```
VALUES JSON_QUERY('{"id":"701", "name":{"first":"John", "last":"Doe"}}', '$.name');
```
El resultado es la serie siguiente que representa un objeto JSON:
```
{"first":"John", "last":"Doe"}
```

Consulte el ejemplo en expresión-vía-json-sql para ver las distintas opciones del derivador de matrices con JSON_QUERY.