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.
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 incorporada, salvo los siguientes tipos de datos (SQLSTATE 42815):
- GRAPHIC
- VARGRAPHIC
- DBCLOB
- BINARY
- CHAR FOR BIT DATA
- VARCHAR FOR BIT DATA
- Un tipo definido por el usuario que tiene su origen en cualquiera de los tipos de datos listados anteriormente
Si se devuelve un valor de carácter, debe contener datos JSON formateados correctamente (SQLSTATE 22032). Si se devuelve el tipo de datos binario, se interpretará según la cláusula FORMAT implícita o explícita.
- FORMAT JSON
- La expresión JSON se formatea como datos JSON.
Si la expresión JSON es un tipo de datos de serie de caracteres, se tratará como datos JSON.
Si la expresión JSON es un tipos de datos de serie binaria, se interpretará como datos UTF-8.
- FORMAT BSON
- Especifica que la expresión JSON presenta el formato de representación BSON de datos JSON (SQLSTATE 22032). La expresión JSON debe ser un tipo de datos de serie binaria (SQLSTATE 42815).
expresión-vía-acceso-sql-json - 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 ubicar un valor JSON en los datos JSON que se especifica mediante la expresión JSON. Para obtener más información sobre la expresión de vía de acceso SQL/JSON, consulte sql-json-path-expression.
- AS nombre-vía-acceso
- Especifica un nombre que se va a utilizar para identificar la expresión-vía-acceso-sql-json.
- RETURNING tipo-datos
- El tipo de datos del resultado puede ser CHAR, VARCHAR, CLOB, VARBINARY o BLOB (SQLSTATE 42815). El valor por omisión es CLOB (2 GB).
Consulte Sentencia CREATE TABLE para ver la descripción de los tipos de datos incorporados.
- FORMAT JSON
- Los datos devueltos están formateados como datos JSON.
- ENCODING UTF8
- Especifica la codificación que se va a utilizar cuando el valor de tipo de datos sea un tipo de serie binaria. Esta cláusula solamente se permite para tipos de series binarias. El valor por omisión 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). Los datos tipos-datos deben ser un tipo de datos de serie binaria (SQLSTATE 42815).
- WITHOUT ARRAY WRAPPER o WITH ARRAY WRAPPER
- Especifica si el valor de salida ha derivado en una matriz JSON.
- WITHOUT ARRAY WRAPPER
- El resultado no se deriva. 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 resuelva en una secuencia de dos o más elementos SQL/JSON en un error (SQLSTATE 2203A). La utilización 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 aparece entre corchetes para crear una matriz JSON.
- WITH CONDITIONAL ARRAY WRAPPER
- Indica que el resultado aparece entre corchetes para crear una matriz JSON para cualquiera de los casos siguientes:
- Se devuelve más de un elemento SQL/JSON.
- Se devuelve un único elemento SQL/JSON que no es una matriz JSON o un objeto JSON.
- KEEP QUOTES u OMIT QUOTES
- Especifica si se deben eliminar las comillas de apertura y cierre cuando se devuelve una serie escalar.
- KEEP QUOTES
- Las comillas no se eliminan de las series escalares. Esta cláusula es el valor por omisión.
- OMIT QUOTES
- Las comillas 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 una expresión-vía-acceso-sql-json 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 detecta 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 la expresión-JSON es un valor nulo, el resultado es el valor nulo.
Notas
- Si los marcadores de parámetros no se emiten de forma explícita en un tipo de datos soportado, se devuelve un error (SQLSTATE 42815)
Ejemplo
- Devolver el objeto JSON que está asociado con la clave de nombre del texto JSON.
El resultado es la serie siguiente que representa un objeto JSON:VALUES JSON_QUERY('{"id":"701", "name":{"first":"John", "last":"Doe"}}', '$.name');{"first":"John", "last":"Doe"}
Consulte el ejemplo en sql-json-path-expression para ver distintas opciones de derivador de matriz con JSON_QUERY.