JSON_TABLE función de tabla

La función de tabla JSON_TABLE devuelve una tabla de resultados de la evaluación de las expresiones de vía de acceso SQL/JSON. Cada elemento de la secuencia de resultados de la expresión de vía de acceso de SQL/JSON de fila representa una o varias filas de la tabla de resultados.

definición-columna-regular-tabla-json

definición-columna-con-formato-tabla-json

tipo-datos1

tipo-datos-2

El esquema es SYSIBM. El nombre de la función no puede especificarse 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).

'strict $'

Especifica que si se informa de un error cuando no se puede utilizar la expresión de vía de acceso especificada para navegar por el documento JSON desde el inicio del elemento de contexto. El error se maneja de acuerdo con la cláusula ON ERROR actual.

COLUMNS

Especifica las columnas de salida de la tabla de resultados, incluyendo el nombre de columna, el tipo de datos y cómo se calcula el valor de columna para cada fila. La suma de las longitudes de la columna de resultados no puede exceder los 64 KB.

definición-columna-regular-tabla-json

Especifica una columna de salida de la tabla de resultados, incluyendo el nombre de columna, el tipo de datos y una expresión de vía de acceso SQL/JSON para extraer el valor del elemento de secuencia para la fila. Esto equivale al resultado de la función escalar JSON_VALUE.

nombre-columna

Especifica el nombre de la columna en la tabla de resultados. El nombre no se puede calificar y no se puede utilizar el mismo nombre para más de una columna de la tabla de resultados (SQLSTATE 42711).

tipo-datos1

Especifica el tipo de datos de la columna.

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

PATH constante-expresión-vía-columna

Especifica una constante de serie de caracteres que se interpreta como una vía de acceso SQL/JSON. La constante-expresión-vía-columna especifica una expresión de vía de acceso SQL/JSON que determinar el valor de columna con respecto a un elemento que es el resultado de evaluar la expresión de vía de acceso SQL/JSON en expresión-vía-json-sql.

Si desea más información sobre el contenido de una expresión de vía de acceso SQL/JSON, consulte expresión-vía-json-sql.

Dado un elemento resultado del proceso de la expresión-vía-json-sql como elemento de contexto proporcionado externamente, la constante-expresión-vía-columna se evalúa y devuelve una secuencia de salida. El valor de columna se determina basándose en esta secuencia de salida del modo siguiente:

Si se devuelve una secuencia vacía, la cláusula ON EMPTY proporciona el valor de la columna.
Si se especifica ERROR ON EMPTY, se devuelve un error.
Si se devuelve una secuencia vacía y no se especifica la cláusula ON EMPTY, se asigna el valor nulo a la columna.
Si se devuelve una sola secuencia de elemento y el tipo del elemento no es una matriz JSON o un objeto JSON, el valor se convierte al tipo de datos que se ha especificado para la columna.
Si se devuelve una única secuencia de elemento y el tipo del elemento es una matriz JSON o un objeto JSON, se devuelve un error.
Si se devuelve una secuencia con más de un elemento, se devuelve un error.
Si se produce un error, la cláusula ON ERROR especifica el valor de la columna.

El valor de constante-expresión-vía-columna no debe ser una serie vacía ni un serie toda de espacios en blanco. Si no se especifica la cláusula PATH, la constante-expresión-vía-columna se define como '$.' con el prefijo nombre-columna.

ON EMPTY

Especifica el comportamiento cuando se devuelve una secuencia vacía para la columna.

NULL ON EMPTY: Se devuelve un valor nulo SQL. Esta cláusula es el valor por omisión.
ERROR ON EMPTY: Se devuelve un error.
DEFAULT expresión-predeterminada ON EMPTY: Se devuelve el valor especificado por expresión-predeterminada. El tipo de datos de expresión-predeterminada debe ser el mismo que el tipo de datos de devolución (SQLSTATE 42815).

ON ERROR

Especifica el comportamiento cuando se devuelve un error para la columna. Si esta cláusula no se especifica. se sigue el comportamiento especificado para la cláusula ON ERROR de nivel de tabla.

NULL ON ERROR: Se devuelve un valor nulo.
ERROR ON ERROR: Se devuelve un error.
DEFAULT expresión-predeterminada ON ERROR: Se devuelve el valor especificado por expresión-predeterminada. El tipo de datos de expresión-predeterminada debe ser el mismo que el tipo de datos de devolución (SQLSTATE 42815).

definición-columna-con-formato-tabla-json

Especifica una columna de salida de la tabla de resultados. La definición incluye el nombre de columna, el tipo de datos y una expresión de vía de acceso SQL/JSON. Esta definición se utiliza para extraer el valor del elemento de secuencia para la fila. El valor extraído se formatea como un valor JSON. Esto equivale al resultado de la función escalar JSON_QUERY.

nombre-columna

tipo-datos-2

Especifica el tipo de datos de la columna. El tipo de datos puede ser CHAR, VARCHAR, CLOB, VARBINARY o BLOB (SQLSTATE 42815).

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

FORMAT JSON

Indica que los datos que se han recuperado se formatean como una serie JSON.

PATH constante-expresión-vía-columna

Especifica una constante de serie de caracteres que se interpreta como una vía de acceso SQL/JSON.

La constante-expresión-vía-columna especifica una expresión de vía de acceso SQL/JSON que determina el valor de columna con respecto al resultado de evaluar la expresión de vía de acceso SQL/JSON en expresión-vía-json-sql.

Si desea más información sobre el contenido de una expresión de vía de acceso SQL/JSON, consulte expresión-vía-json-sql.

Si se devuelve una secuencia vacía, la cláusula ON EMPTY proporciona el valor de la columna.
Si se especifica ERROR ON EMPTY, se devuelve un error.
Si se devuelve una secuencia vacía y no se especifica la cláusula ON EMPTY, se asigna el valor nulo a la columna.
Si se produce un error, la cláusula ON ERROR especifica el valor de la columna.

El valor para constante-expresión-vía-columna no debe ser una serie vacía ni una serie toda llena de espacios en blanco. Si no se especifica la cláusula PATH, la constante-expresión-vía-columna se define como '$.' con el prefijo nombre-columna.

WITHOUT ARRAY WRAPPER o WITH ARRAY WRAPPER

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

WITHOUT ARRAY WRAPPER

Indica que 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 genera un error (SQLSTATE 22035).

WITH UNCONDITIONAL ARRAY WRAPPER

Indica que 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 se van a eliminar las comillas de apertura y cierre 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 se devuelve una secuencia vacía para una columna.

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

ON ERROR

Especifica el comportamiento cuando se devuelve un error para la columna. Si esta cláusula no se especifica. se sigue el comportamiento especificado para la cláusula ON ERROR de nivel de tabla.

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

ERROR ON ERROR

Se devuelve un error cuando se encuentra un error de nivel de tabla.

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

Este ejemplo se basa en el documento JSON siguiente:

{
  "id" : 901,
  "firstname" : "John",
  "lastname"  : "Doe",
  "phoneno"   : "555-3762"
}

Listar el ID de empleado, el nombre de pila, los apellidos y el número de teléfono:

SELECT U."id", U."firstname", U."lastname", U."phoneno"
  FROM EMPLOYEE_TABLE E
    JSON_TABLE(E.jsondoc, 'strict $'
               COLUMNS( "id" INTEGER,
                        "firstname"  VARCHAR(20),
                        "lastname"   VARCHAR(20),
                        "phoneno"    VARCHAR(20))
                        ERROR ON ERROR) AS U

Esta consulta devuelve la tabla siguiente:

id	firstname	lastname	phoneno
901	John	Doe	555-3762