Función escalar JSON_VAL

La función JSON_VAL proporciona una interfaz SQL para extraer y recuperar datos JSON de tipos de datos SQL de objetos BSON. La función JSON_VAL devuelve un elemento de un documento JSON que se identifica por el nombre de campo JSON que se especifica en la cadena de búsqueda. El valor del elemento JSON se devuelve en el tipo de datos y la longitud especificados en result-type.

El esquema es SYSIBM.

json-value

Expresión que devuelve un valor BLOB. El json-value debe contener una representación BSON de un documento JSON. fin del cambio

search-string

Una constante de cadena de caracteres o gráficos que no supera los 2048 bytes. la cadena de búsqueda contiene el nombre del campo JSON con ruta completa. Si el valor no es CCSID 1208, el valor se convierte a CCSID 1208 antes de que se evalúe la función.

tipo de resultado

Una cadena de caracteres constante que no supera los 32 bytes y que especifica las características del resultado de la función. La constante no distingue entre mayúsculas y minúsculas. La cadena «:na» se puede añadir al tipo de datos para indicar que json-value no debe contener una matriz JSON. Los espacios en blanco iniciales pueden especificarse antes de ':' y los finales pueden especificarse después de ':'. Por ejemplo, se pueden especificar « s:40 », «s:40», «b: 10», «ts: na», « s:40 : na» y « s:40: : na». El valor del tipo de resultado debe contener una especificación de tipo de datos de la siguiente tabla.

Tabla 1. Valores constantes admitidos para la parte de tipo de datos del `tipo de resultado`.
`tipo de resultado`	Tipo de datos SQL del resultado
n	DECFLOAT(34)
i	ENTERO
l	BIGINT
f	DOUBLE
d	FECHA
ts	TIMESTAMP(6)
t	HORA
`s` :n	VAR `CHAR(n` ), donde `n` es una constante entera de 1 a 32672. El CCSID del resultado es el CCSID para datos mixtos Unicode (1208).
`b:n`	`VARCHAR(n)` PARA DATOS DE BIT, donde `n` es una constante entera de 1 a 32672.
u	ENTERO, con valores 0 o 1.

El nombre del campo JSON puede identificar un valor escalar o un valor de matriz JSON. Si se especifica ':na' como parte del tipo de resultado, el resultado no debe ser una matriz. Si no se especifica ':na' en el tipo de resultado y el resultado es una matriz, se devuelve el valor del primer elemento de la matriz identificada.

El resultado de la función JSON_VAL es el tipo de datos y la longitud especificados por result-type. El resultado puede ser nulo.

El resultado se determina según los siguientes criterios:

Si el nombre del campo JSON no se encuentra en json-value, el resultado es el valor nulo.
Si el BSON_TYPE del campo JSON en json-value es BSON_DBREF o BSON_UNDEFINED, el resultado es el valor nulo.
Si el tipo de resultado es «u», el valor del resultado describe el valor del campo JSON especificado en json-value. El resultado depende de los siguientes valores del campo JSON:

1

Existe un valor y el valor no es el valor nulo o una cadena vacía. Por ejemplo: {name:"Joe"}.

0

Existe un valor y el valor es el valor nulo. Por ejemplo: {name:null}.

nulo

No existe un valor. Por ejemplo: { }.
De lo contrario, si es necesario, el valor del campo JSON especificado en json-value se convierte en result-type. Si el valor del campo JSON no se puede convertir al tipo de resultado, se devuelve el valor nulo. Por ejemplo, supongamos que el valor del campo JSON es una cadena arbitraria que no se puede convertir en un entero, y el tipo de resultado es 'i'. Se devuelve el valor nulo. Si la longitud de los datos es mayor que la longitud especificada por el tipo de resultado, el resultado es el valor nulo. Además, si el resultado es VARCHAR o un valor de fecha y hora (DATE, TIME o TIMESTAMP), el esquema de codificación es Unicode.

Notas

Asignación de argumentos a parámetros

Cuando se invoca la función JSON_VAL y se asignan argumentos a los tipos de parámetros de la función, o se asigna el resultado de la función al destino al regresar de la función, no se utiliza la conversión implícita.

Concentrador de sentencias

Los valores constantes que se especifican como argumentos no pueden sustituirse por marcadores de parámetros para su uso con el concentrador de sentencias.

Consideraciones sobre la instrucción CREATE INDEX

Las siguientes consideraciones se aplican a las sentencias CREATE INDEX que invocan la función JSON_VAL:

Si la expresión clave invoca la función JSON_VAL y el primer argumento es una columna LOB, la columna debe definirse como un LOB en línea.
Si la expresión clave invoca la función JSON_VAL, la invocación de la función debe cumplir las siguientes condiciones:
- La invocación de la función JSON_VAL debe ser la expresión más externa para la expresión clave.
- Si el primer argumento es una columna, dicha columna debe estar contenida en una tabla en un espacio de tabla de partición por crecimiento.
- El tercer argumento debe terminar con la cadena ':na', para indicar que el primer argumento no contiene una matriz JSON.
Si la expresión clave invoca la función incorporada JSON_VAL, la instrucción CREATE INDEX no debe hacer referencia a ninguna columna LOB que no sea la columna LOB que es el argumento de la función JSON_VAL. Una instrucción CREATE INDEX de este tipo solo puede referirse a una única columna LOB.

Restricciones de valor de fecha

Cuando se utiliza $DATE en el documento JSON, solo se admiten valores de fecha desde el 1 de enero de 1970 hasta el 31 de diciembre de 2037. fin del cambio

ejemplos

Supongamos que la columna DATA de la tabla « table1 » contiene una fila con el siguiente documento JSON:

{
	name:"Joe",
	age:5,
	phone:["555-666-7777", "444-789-1234"],
	address:{
		street:"ABC st",
		zipcode:"95141"
               }
}

Puede utilizar la función JSON_VAL para buscar direcciones con un código postal de «95141».

SELECT * FROM "table1" 
   WHERE JSON_VAL(DATA, 'address.zipcode', ‘s:5’)='95141';

Los siguientes ejemplos muestran cómo puede utilizar el argumento de cadena de búsqueda. Supongamos que la tabla 'json_table' contiene cuatro filas con los siguientes objetos JSON. Cada objeto JSON se almacena como BSON en una columna BLOB llamada DATA.
```
{
     name: "Joe",
      isMarried:true,
      phone: 82113456,
      partner:
      {
        name: "Kate",
         isMarried:true, 
         phone: 82113111,
         son: 
         {
            name: "Lock",
             isMarried:false, 
             phone: 81231232, 81231233
}
}
}

{
     name:"Mary"
      isMarried:-1,
      phone: “82111432”
      partner: “NULL”
}

{
     name:"Henry",
      isMarried:0,
      phone: “NULL”
}

{
     name:"Bill",
      isMarried:false
} 
```
Extraiga el nombre del objeto:
Puede utilizar la función JSON_VAL para extraer el nombre del objeto cuyo nombre del hijo de la pareja (cadena de búsqueda de ' partner.son.name ') es 'Lock' y devolver el valor como VARCHAR(40).
```
SELECT JSON_VAL( data, 'name' , 's:40' ) FROM json_table 
     WHERE JSON_VAL( data, 'partner.son.name' , 's:40' ) = 'Lock';
```
El resultado es «Joe».
Extraiga el nombre de la pareja de la pareja:
Puede utilizar la función JSON_VAL para extraer el nombre del socio del socio (cadena de búsqueda de ' partner.partner ') para cada fila y devolver el valor como VARCHAR(40).
```
SELECT JSON_VAL( data, 'partner.partner ' , 's:40' ) FROM json_table ;
```
Este ejemplo devuelve cuatro filas, cada una de las cuales contiene el valor nulo porque la cadena de búsqueda « partner.partner » no existe para los objetos de ninguna fila.