Amazon Redshift dejará de admitir la creación de nuevas UDF de Python a partir del parche 198. Las UDF de Python existentes seguirán funcionando hasta el 30 de junio de 2026. Para obtener más información, consulte la [publicación del blog](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
# Funciones JSON
**Topics**
+ [Función JSON\$1PARSE](JSON_PARSE.md)
+ [Función CAN\$1JSON\$1PARSE](CAN_JSON_PARSE.md)
+ [Función JSON\$1SERIALIZE](JSON_SERIALIZE.md)
+ [Función JSON\$1SERIALIZE\$1TO\$1VARBYTE](JSON_SERIALIZE_TO_VARBYTE.md)
+ [Funciones JSON basadas en texto](text-json-functions.md)
**nota**
Le recomendamos que utilice las siguientes funciones para trabajar con JSON:
[Función JSON\$1PARSE](JSON_PARSE.md)
[Función CAN\$1JSON\$1PARSE](CAN_JSON_PARSE.md)
[Función JSON\$1SERIALIZE](JSON_SERIALIZE.md)
[Función JSON\$1SERIALIZE\$1TO\$1VARBYTE](JSON_SERIALIZE_TO_VARBYTE.md)
Con JSON\$1PARSE, solo necesita convertir el texto JSON en un valor de tipo SUPER una vez en la ingesta, después de lo cual puede operar con los valores SUPER. Amazon Redshift analiza los valores SUPER de forma más eficiente que VARCHAR, que es el resultado de las funciones JSON basadas en texto. Para obtener más información acerca de cómo trabajar con el tipo de datos SUPER, vaya a [Datos semiestructurados en Amazon Redshift](super-overview.md).
Cuando necesita almacenar un conjunto relativamente pequeño de pares clave-valor, puede ahorrar espacio al almacenar los datos en formato JSON. Debido a que las cadenas JSON se pueden almacenar en una única columna, utilizar JSON puede ser más eficiente que almacenar los datos en formato de tabla. Por ejemplo, suponga que tiene una tabla dispersa, donde necesita tener muchas columnas para representar completamente todos los atributos posibles, pero la mayoría de los valores son NULL para cualquier fila o columna dada. Al usar JSON para almacenamiento, puede almacenar los datos para una fila en pares clave-valor en una única cadena JSON y eliminar las columnas de tabla poco pobladas.
Además, puede modificar fácilmente las cadenas JSON para almacenar pares clave-valor adicionales cuando el esquema JSON cambia sin necesidad de agregar columnas a una tabla.
Recomendamos utilizar JSON con moderación. JSON no es una buena opción para almacenar grandes conjuntos de datos porque, al almacenar datos dispersos en una única columna, JSON no utiliza la arquitectura de almacén de columnas de Amazon Redshift. Aunque Amazon Redshift admite las funciones JSON en las columnas CHAR y VARCHAR, recomendamos utilizar SUPER para procesar los datos con el formato de serialización de JSON. SUPER utiliza una representación sin esquema posterior al análisis con la que se pueden consultar datos jerárquicos de manera eficiente. Para obtener más información acerca del tipo de datos SUPER, consulte [Datos semiestructurados en Amazon Redshift](super-overview.md).
JSON utiliza cadenas de texto con cifrado UTF-8, por lo que las cadenas JSON se pueden almacenar como tipos de datos CHAR o VARCHAR.
Las cadenas JSON deben tener el formato JSON adecuado, conforme a las siguientes reglas:
+ El JSON a nivel raíz puede ser un objeto JSON o una matriz JSON. Un objeto JSON es un conjunto no ordenado de pares clave-valor separados por comas y delimitado con llaves.
Por ejemplo: ., `{"one":1, "two":2} `
+ Una matriz JSON es un conjunto ordenado de valores separados por comas delimitado entre corchetes.
A continuación se muestra un ejemplo: `["first", {"one":1}, "second", 3, null] `
+ Las matrices JSON utilizan un índice basado en cero; el primer elemento en una matriz está en la posición 0. En un par clave:valor de JSON, la clave es una cadena con comillas dobles.
+ El valor JSON puede ser cualquiera de los siguientes valores:
+ Objeto JSON
+ matriz
+ cadena
+ Se representa con comillas dobles
+ número
+ Incluye números enteros, decimales y flotantes
+ booleano
+ null
+ Los objetos y las matrices vacíos son valores JSON válidos.
+ Los campos JSON distinguen entre mayúsculas y minúsculas.
+ Se ignoran los espacios en blanco entre los elementos estructurales de JSON (como `{ }, [ ]`).
Las funciones JSON de Amazon Redshift y el comando COPY de Amazon Redshift utilizan los mismos métodos para trabajar con datos con formato JSON. Para obtener más información acerca de cómo trabajar con JSON, consulte [COPY de formato JSON](copy-usage_notes-copy-from-json.md)
# Función JSON\$1PARSE
La función JSON\$1PARSE analiza los datos con formato JSON y los convierte en la representación `SUPER`.
Para capturar el tipo de datos `SUPER` mediante el comando INSERT o UPDATE, utilice la función JSON\$1PARSE. Cuando utiliza JSON\$1PARSE() para analizar cadenas JSON en valores `SUPER`, se aplican determinadas restricciones. Para obtener información adicional, consulta [Opciones de análisis de SUPER](super-configurations.md#parsing-options-super).
## Sintaxis
```
JSON_PARSE( {json_string | binary_value} )
```
## Argumentos
*json\$1string*
Una expresión que devuelve JSON serializado como tipo `VARBYTE` o `VARCHAR`.
*binary\$1value*
Valor binario de tipo VARBYTE.
## Tipo de retorno
`SUPER`
## Ejemplos
Para convertir la matriz JSON `[10001,10002,"abc"]` en el tipo de datos `SUPER`, utilice el siguiente ejemplo.
```
SELECT JSON_PARSE('[10001,10002,"abc"]');
+---------------------+
| json_parse |
+---------------------+
| [10001,10002,"abc"] |
+---------------------+
```
Para asegurarse de que la función convirtió la matriz JSON en el tipo de datos `SUPER`, utilice el siguiente ejemplo. Para obtener más información, consulte [Función JSON\$1TYPEOF](r_json_typeof.md)
```
SELECT JSON_TYPEOF(JSON_PARSE('[10001,10002,"abc"]'));
+-------------+
| json_typeof |
+-------------+
| array |
+-------------+
```
# Función CAN\$1JSON\$1PARSE
La función CAN\$1JSON\$1PARSE analiza los datos en formato JSON y devuelve `true` si el resultado se puede convertir en un valor `SUPER` mediante la función JSON\$1PARSE.
## Sintaxis
```
CAN_JSON_PARSE( {json_string | binary_value} )
```
## Argumentos
*json\$1string*
Una expresión que devuelve objetos JSON serializados en el formato `VARCHAR`.
*binary\$1value*
Valor binario de tipo VARBYTE.
## Tipo de retorno
`BOOLEAN`
## Notas de uso
+ CAN\$1JSON\$1PARSE devuelve el valor false para cadenas vacías. Devuelve NULL si el argumento de entrada es nulo.
## Ejemplos
En el siguiente ejemplo se muestra CAN\$1JSON\$1PARSE en ejecución en una matriz JSON correctamente formada mediante una condición CASE. Devuelve el valor true, por lo que Amazon Redshift ejecuta la función JSON\$1PARSE en el valor de ejemplo.
```
SELECT CASE
WHEN CAN_JSON_PARSE('[10001,10002,"abc"]')
THEN JSON_PARSE('[10001,10002,"abc"]')
END;
case
---------------------
'[10001,10002,"abc"]'
```
En el siguiente ejemplo se muestra CAN\$1JSON\$1PARSE en ejecución en un valor que no tiene formato JSON mediante una condición CASE. Devuelve el valor false, por lo que Amazon Redshift devuelve en su lugar el segmento de la cláusula ELSE de la condición CASE.
```
SELECT CASE
WHEN CAN_JSON_PARSE('This is a string.')
THEN JSON_PARSE('This is a string.')
ELSE 'This is not JSON.'
END;
case
---------------------
"This is not JSON."
```
# Función JSON\$1SERIALIZE
La función JSON\$1SERIALIZE serializa una expresión `SUPER` en una representación JSON textual en función de RFC 8259. Para obtener más información acerca de dicho RFC, consulte [Formato de intercambio de datos de notación de objetos de JavaScript (JSON)](https://tools.ietf.org/html/rfc8259).
El límite de tamaño de `SUPER` es aproximadamente el mismo que el límite de bloque y el límite de `VARCHAR` es menor que el límite de tamaño de `SUPER`. Por lo tanto, la función JSON\$1SERIALIZE devuelve un error cuando el formato JSON excede el límite de VARCHAR del sistema. Para comprobar el tamaño de una expresión `SUPER`, consulte la función [JSON\$1SIZE](r_json_size.md).
## Sintaxis
```
JSON_SERIALIZE(super_expression)
```
## Argumentos
*super\$1expression*
Una expresión o columna `SUPER`.
## Tipo de retorno
`VARCHAR`
**nota**
El valor VARCHAR devuelto es siempre una cadena JSON no nula. Si *super\$1expression* es NULL, JSON\$1SERIALIZE devuelve la cadena JSON `'null'`.
## Ejemplos
Para serializar un valor de `SUPER` en una cadena, use el siguiente ejemplo.
```
SELECT JSON_SERIALIZE(JSON_PARSE('[10001,10002,"abc"]'));
+---------------------+
| json_serialize |
+---------------------+
| [10001,10002,"abc"] |
+---------------------+
```
# Función JSON\$1SERIALIZE\$1TO\$1VARBYTE
La función JSON\$1SERIALIZE\$1TO\$1VARBYTE convierte un valor `SUPER` en una cadena JSON similar a JSON\$1SERIALIZE(), pero se almacena en un valor `VARBYTE` en su lugar.
## Sintaxis
```
JSON_SERIALIZE_TO_VARBYTE(super_expression)
```
## Argumentos
*super\$1expression*
Una expresión o columna `SUPER`.
## Tipo de retorno
`VARBYTE`
## Ejemplos
Para serializar un valor `SUPER` y devolver el resultado en formato `VARBYTE`, use el siguiente ejemplo.
```
SELECT JSON_SERIALIZE_TO_VARBYTE(JSON_PARSE('[10001,10002,"abc"]'));
+----------------------------------------+
| json_serialize_to_varbyte |
+----------------------------------------+
| 5b31303030312c31303030322c22616263225d |
+----------------------------------------+
```
Para serializar un valor `SUPER` y convertir el resultado en formato `VARCHAR`, use el siguiente ejemplo. Para obtener más información, consulte [Función CAST](r_CAST_function.md).
```
SELECT CAST((JSON_SERIALIZE_TO_VARBYTE(JSON_PARSE('[10001,10002,"abc"]'))) AS VARCHAR);
+---------------------------+
| json_serialize_to_varbyte |
+---------------------------+
| [10001,10002,"abc"] |
+---------------------------+
```
# Funciones JSON basadas en texto
Las funciones de esta sección analizan los valores JSON como VARCHAR. Para analizar JSON, le recomendamos que utilice las siguientes funciones, que analizan los valores JSON como SUPER. Amazon Redshift analiza los valores SUPER de forma más eficiente que VARCHAR.
+ [Función JSON\$1PARSE](JSON_PARSE.md)
+ [Función CAN\$1JSON\$1PARSE](CAN_JSON_PARSE.md)
+ [Función JSON\$1SERIALIZE](JSON_SERIALIZE.md)
+ [Función JSON\$1SERIALIZE\$1TO\$1VARBYTE](JSON_SERIALIZE_TO_VARBYTE.md)
**Topics**
+ [Función IS\$1VALID\$1JSON](IS_VALID_JSON.md)
+ [Función IS\$1VALID\$1JSON\$1ARRAY](IS_VALID_JSON_ARRAY.md)
+ [Función JSON\$1ARRAY\$1LENGTH](JSON_ARRAY_LENGTH.md)
+ [Función JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT](JSON_EXTRACT_ARRAY_ELEMENT_TEXT.md)
+ [Función JSON\$1EXTRACT\$1PATH\$1TEXT](JSON_EXTRACT_PATH_TEXT.md)
# Función IS\$1VALID\$1JSON
**nota**
CAN\$1JSON\$1PARSE y sus funciones asociadas analizan los valores JSON como SUPER, que Amazon Redshift analiza de forma más eficiente que VARCHAR.
En lugar de usar IS\$1VALID\$1JSON, le recomendamos que valide las cadenas JSON con [Función CAN\$1JSON\$1PARSE](CAN_JSON_PARSE.md).
La función IS\$1VALID\$1JSON valida una cadena JSON. La función devuelve un valor booleano de `true` si la cadena tiene un formato JSON correcto o `false` si la cadena no tiene el formato correcto. Para validar una matriz JSON, use [Función IS\$1VALID\$1JSON\$1ARRAY](IS_VALID_JSON_ARRAY.md)
Para obtener más información, consulte [Funciones JSON](json-functions.md).
## Sintaxis
```
IS_VALID_JSON('json_string')
```
## Argumentos
*json\$1string*
Cadena o expresión que se evalúa como una cadena JSON.
## Tipo de retorno
`BOOLEAN`
## Ejemplos
Para crear una tabla e insertar cadenas JSON para su comprobación, use el siguiente ejemplo.
```
CREATE TABLE test_json(id int IDENTITY(0,1), json_strings VARCHAR);
-- Insert valid JSON strings --
INSERT INTO test_json(json_strings) VALUES
('{"a":2}'),
('{"a":{"b":{"c":1}}}'),
('{"a": [1,2,"b"]}');
-- Insert invalid JSON strings --
INSERT INTO test_json(json_strings) VALUES
('{{}}'),
('{1:"a"}'),
('[1,2,3]');
```
Para validar las cadenas del ejemplo anterior, use el siguiente ejemplo.
```
SELECT id, json_strings, IS_VALID_JSON(json_strings)
FROM test_json
ORDER BY id;
+----+---------------------+---------------+
| id | json_strings | is_valid_json |
+----+---------------------+---------------+
| 0 | {"a":2} | true |
| 4 | {"a":{"b":{"c":1}}} | true |
| 8 | {"a": [1,2,"b"]} | true |
| 12 | {{}} | false |
| 16 | {1:"a"} | false |
| 20 | [1,2,3] | false |
+----+---------------------+---------------+
```
# Función IS\$1VALID\$1JSON\$1ARRAY
**nota**
JSON\$1PARSE y sus funciones asociadas analizan los valores JSON como SUPER, que Amazon Redshift analiza de forma más eficiente que VARCHAR.
En lugar de usar IS\$1VALID\$1JSON\$1ARRAY, le recomendamos que analice las cadenas JSON con [Función JSON\$1PARSE](JSON_PARSE.md) para obtener un valor SUPER. A continuación, utilice la función [Función IS\$1ARRAY](r_is_array.md) para confirmar que la matriz está formada correctamente.
La función IS\$1VALID\$1JSON\$1ARRAY valida una matriz JSON. La función devuelve un valor booleano de `true` si la matriz tiene un formato JSON correcto o `false` si la matriz no tiene el formato correcto. Para validar una cadena JSON, use [Función IS\$1VALID\$1JSON](IS_VALID_JSON.md)
Para obtener más información, consulte [Funciones JSON](json-functions.md).
## Sintaxis
```
IS_VALID_JSON_ARRAY('json_array')
```
## Argumentos
*json\$1array*
Cadena o expresión que se evalúa como una matriz JSON.
## Tipo de retorno
`BOOLEAN`
## Ejemplos
Para crear una tabla e insertar cadenas JSON para su comprobación, use el siguiente ejemplo.
```
CREATE TABLE test_json_arrays(id int IDENTITY(0,1), json_arrays VARCHAR);
-- Insert valid JSON array strings --
INSERT INTO test_json_arrays(json_arrays)
VALUES('[]'),
('["a","b"]'),
('["a",["b",1,["c",2,3,null]]]');
-- Insert invalid JSON array strings --
INSERT INTO test_json_arrays(json_arrays)
VALUES('{"a":1}'),
('a'),
('[1,2,]');
```
Para validar las cadenas del ejemplo anterior, use el siguiente ejemplo.
```
SELECT json_arrays, IS_VALID_JSON_ARRAY(json_arrays)
FROM test_json_arrays ORDER BY id;
+------------------------------+---------------------+
| json_arrays | is_valid_json_array |
+------------------------------+---------------------+
| [] | true |
| ["a","b"] | true |
| ["a",["b",1,["c",2,3,null]]] | true |
| {"a":1} | false |
| a | false |
| [1,2,] | false |
+------------------------------+---------------------+
```
# Función JSON\$1ARRAY\$1LENGTH
**nota**
JSON\$1PARSE y sus funciones asociadas analizan los valores JSON como SUPER, que Amazon Redshift analiza de forma más eficiente que VARCHAR.
En lugar de usar JSON\$1ARRAY\$1LENGTH, le recomendamos que analice las cadenas JSON con [Función JSON\$1PARSE](JSON_PARSE.md) para obtener un valor SUPER. A continuación, use [Función GET\$1ARRAY\$1LENGTH](get_array_length.md) para obtener la longitud de la matriz.
La función JSON\$1ARRAY\$1LENGTH devuelve la cantidad de elementos en la matriz exterior de una cadena JSON. Si el argumento *null\$1if\$1invalid* está establecido en `true` y la cadena JSON no es válida, la función devuelve `NULL` en lugar de un error.
Para obtener más información, consulte [Funciones JSON](json-functions.md).
## Sintaxis
```
JSON_ARRAY_LENGTH('json_array' [, null_if_invalid ] )
```
## Argumentos
*json\$1array*
Una matriz JSON con formato adecuado.
*null\$1if\$1invalid*
(Opcional) Un valor `BOOLEAN` que especifica que se devuelva `NULL` si la cadena JSON de entrada no es válida en lugar de devolver un error. Para devolver `NULL` si la cadena JSON no es válida, especifique `true` (`t`). Para devolver un error si la cadena JSON no es válida, especifique `false` (`f`). El valor predeterminado es `false`.
## Tipo de retorno
`INTEGER`
## Ejemplos
Para devolver la cantidad de elementos en la matriz, use el siguiente ejemplo.
```
SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14]');
+-------------------+
| json_array_length |
+-------------------+
| 5 |
+-------------------+
```
Para devolver un error porque la cadena JSON no es válida, use el siguiente ejemplo.
```
SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14');
ERROR: invalid json array object [11,12,13,{"f1":21,"f2":[25,26]},14
```
Para establecer *null\$1if\$1invalid* en *true*, para que la instrucción devuelva `NULL` en lugar de devolver un error para indicar que la cadena JSON no es válida, use el siguiente ejemplo.
```
SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14',true);
+-------------------+
| json_array_length |
+-------------------+
| NULL |
+-------------------+
```
# Función JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT
**nota**
JSON\$1PARSE y sus funciones asociadas analizan los valores JSON como SUPER, que Amazon Redshift analiza de forma más eficiente que VARCHAR.
En lugar de usar JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT, le recomendamos que analice las cadenas JSON con [Función JSON\$1PARSE](JSON_PARSE.md) para obtener un valor SUPER. A continuación, consulte el elemento que desee utilizando su índice de matriz, con la sintaxis de `value[element position]`. Para obtener más información sobre cómo consultar los elementos de una matriz en valores SUPER, vaya a [Consulta de datos semiestructurados](query-super.md).
La función JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT devuelve un elemento de la matriz JSON en la matriz extrema de una cadena JSON utilizando un índice basado en cero. El primer elemento en una matriz está en posición 0. Si el índice es negativo o está fuera de los límites, JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT devuelve `NULL`. Si el argumento *null\$1if\$1invalid* está establecido en `TRUE` y la cadena JSON no es válida, la función devuelve `NULL` en lugar de un error.
Para obtener más información, consulte [Funciones JSON](json-functions.md).
## Sintaxis
```
JSON_EXTRACT_ARRAY_ELEMENT_TEXT('json string', pos [, null_if_invalid ] )
```
## Argumentos
*json\$1string*
Una cadena JSON con formato adecuado.
*pos*
Un valor `INTEGER` que representa el índice del elemento de matriz que se devolverá, utilizando un índice de matriz basado en cero.
*null\$1if\$1invalid*
(Opcional) Un valor `BOOLEAN` que especifica que se devuelva `NULL` si la cadena JSON de entrada no es válida en lugar de devolver un error. Para devolver `NULL` si la cadena JSON no es válida, especifique `true` (`t`). Para devolver un error si la cadena JSON no es válida, especifique `false` (`f`). El valor predeterminado es `false`.
## Tipo de retorno
`VARCHAR`
Una cadena `VARCHAR` que representa el elemento de matriz JSON al que se hace referencia en *pos*.
## Ejemplos
Para devolver el elemento de matriz en la posición 2, que es el tercer elemento de un índice de matriz basado en cero, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('[111,112,113]', 2);
+---------------------------------+
| json_extract_array_element_text |
+---------------------------------+
| 113 |
+---------------------------------+
```
Para devolver un error porque la cadena JSON no es válida, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('["a",["b",1,["c",2,3,null,]]]',1);
ERROR: invalid json array object ["a",["b",1,["c",2,3,null,]]]
```
Para establecer *null\$1if\$1invalid* en *true*, para que la instrucción devuelva `NULL` en lugar de devolver un error para indicar que la cadena JSON no es válida, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('["a",["b",1,["c",2,3,null,]]]',1,true);
+---------------------------------+
| json_extract_array_element_text |
+---------------------------------+
| NULL |
+---------------------------------+
```
Considere las siguientes instrucciones de ejemplo. Si la cadena JSON proporcionada o el índice son NULL, JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT devuelve NULL independientemente del valor de cualquier otro parámetro.
```
--Statement where json_string is NULL.
SELECT json_extract_array_element_text(NULL, 0)
json_extract_array_element_text
---------------------------------
NULL
--Statement where pos is NULL and json_string is invalid JSON.
SELECT json_extract_array_element_text('invalid_json', NULL);
json_extract_array_element_text
---------------------------------
NULL
--Statement where json_string is NULL and null_if_invalid is FALSE.
SELECT json_extract_array_element_text(NULL, 0, FALSE);
json_extract_array_element_text
---------------------------------
NULL
```
Considere las siguientes instrucciones de ejemplo. Cuando *null\$1if\$1invalid* es TRUE, JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT devuelve NULL cuando *json\$1string* es JSON no válido. Si *null\$1if\$1invalid* es FALSE o no se ha establecido, la función devuelve un error cuando *json\$1string* no es válido.
```
--Statement with invalid JSON where null_if_invalid is TRUE.
SELECT json_extract_array_element_text('invalid_json', 0, TRUE);
json_extract_array_element_text
---------------------------------
NULL
--Statement with invalid JSON where null_if_invalid is FALSE.
SELECT json_extract_array_element_text('invalid_json', 0);
ERROR: JSON parsing error
```
Considere el siguiente ejemplo, donde *json\$1string* es JSON válido y *pos* hace referencia a un valor `null` JSON. En este caso, JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT devuelve NULL, independientemente del valor de *null\$1if\$1invalid*.
```
--Statement selecting a null value.
SELECT json_extract_array_element_text('[null]', 0);
json_extract_array_element_text
----------------------------------
NULL
```
# Función JSON\$1EXTRACT\$1PATH\$1TEXT
**nota**
JSON\$1PARSE y sus funciones asociadas analizan los valores JSON como SUPER, que Amazon Redshift analiza de forma más eficiente que VARCHAR.
En lugar de usar JSON\$1EXTRACT\$1PATH\$1TEXT, le recomendamos que analice las cadenas JSON con [Función JSON\$1PARSE](JSON_PARSE.md) para obtener un valor SUPER. A continuación, consulte el elemento que desee utilizando la sintaxis de `value.attribute`. Para obtener más información sobre cómo consultar los elementos de una matriz en valores SUPER, vaya a [Consulta de datos semiestructurados](query-super.md).
La función JSON\$1EXTRACT\$1PATH\$1TEXT devuelve el valor del par clave-valor al que se hace referencia en una serie de elementos de ruta de una cadena JSON. La ruta JSON se puede anidar hasta un máximo de cinco niveles de profundidad. Los elementos de ruta distinguen entre mayúsculas y minúsculas. Si un elemento de ruta no existe en la cadena JSON, JSON\$1EXTRACT\$1PATH\$1TEXT devuelve `NULL`.
Si el argumento *null\$1if\$1invalid* está establecido en `TRUE` y la cadena JSON no es válida, la función devuelve `NULL` en lugar de un error.
JSON\$1EXTRACT\$1PATH\$1TEXT tiene un máximo de tamaño de datos de 64 KB. Por lo tanto, si algún registro JSON tiene más de 64 KB, al procesarlo con JSON\$1EXTRACT\$1PATH\$1TEXT se produce un error.
Para obtener información sobre funciones JSON adicionales, consulte [Funciones JSON](json-functions.md). Para obtener más información acerca de cómo trabajar con JSON, consulte [COPY de formato JSON](copy-usage_notes-copy-from-json.md).
## Sintaxis
```
JSON_EXTRACT_PATH_TEXT('json_string', 'path_elem' [,'path_elem'[, …] ] [, null_if_invalid ] )
```
## Argumentos
*json\$1string*
Una cadena JSON con formato adecuado.
*path\$1elem*
Un elemento de ruta en una cadena JSON. Se necesita al menos un elemento de ruta. Se pueden especificar elementos de ruta adicionales, hasta un máximo de cinco niveles de profundidad.
*null\$1if\$1invalid*
(Opcional) Un valor `BOOLEAN` que especifica que se devuelva `NULL` si la cadena JSON de entrada no es válida en lugar de devolver un error. Para devolver `NULL` si la cadena JSON no es válida, especifique `TRUE` (`t`). Para devolver un error si la cadena JSON no es válida, especifique `FALSE` (`f`). El valor predeterminado es `FALSE`.
En una cadena JSON, Amazon Redshift reconoce a `\n` como un carácter de línea nueva y a `\t` como un carácter de tabulación. Para cargar una barra inversa, aplique escape con una barra inversa (`\\`). Para obtener más información, consulte [Caracteres de escape en JSON](copy-usage_notes-copy-from-json.md#copy-usage-json-escape-characters).
## Tipo de retorno
`VARCHAR`
Una cadena `VARCHAR` que representa el valor JSON al que se hace referencia en los elementos de ruta.
## Ejemplos
Para devolver el valor para la ruta `'f4', 'f6'`, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}','f4', 'f6');
+------------------------+
| json_extract_path_text |
+------------------------+
| star |
+------------------------+
```
Para devolver un error porque la cadena JSON no es válida, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}','f4', 'f6');
ERROR: invalid json object {"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}
```
Para establecer *null\$1if\$1invalid* en *TRUE*, para que la instrucción devuelva `NULL` por cadena JSON no válida en lugar de devolver un error, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}','f4', 'f6',true);
+------------------------+
| json_extract_path_text |
+------------------------+
| NULL |
+------------------------+
```
Considere el siguiente ejemplo, que selecciona el valor de la ruta `'farm', 'barn', 'color'`, donde el valor recuperado se encuentra en el tercer nivel. Utilice el siguiente ejemplo. Este ejemplo está formateado con una herramienta de lint JSON para facilitar su lectura.
```
SELECT JSON_EXTRACT_PATH_TEXT('{
"farm": {
"barn": {
"color": "red",
"feed stocked": true
}
}
}', 'farm', 'barn', 'color');
+------------------------+
| json_extract_path_text |
+------------------------+
| red |
+------------------------+
```
Para devolver `NULL` porque falta el elemento `'color'`, use el siguiente ejemplo. Este ejemplo está formateado con una herramienta de lint JSON.
```
SELECT JSON_EXTRACT_PATH_TEXT('{
"farm": {
"barn": {}
}
}', 'farm', 'barn', 'color');
+------------------------+
| json_extract_path_text |
+------------------------+
| NULL |
+------------------------+
```
Si el JSON es válido, el intento de extracción de un elemento que falta devuelve `NULL`.
Para devolver el valor para la ruta `'house', 'appliances', 'washing machine', 'brand'`, use el siguiente ejemplo.
```
SELECT JSON_EXTRACT_PATH_TEXT('{
"house": {
"address": {
"street": "123 Any St.",
"city": "Any Town",
"state": "FL",
"zip": "32830"
},
"bathroom": {
"color": "green",
"shower": true
},
"appliances": {
"washing machine": {
"brand": "Any Brand",
"color": "beige"
},
"dryer": {
"brand": "Any Brand",
"color": "white"
}
}
}
}', 'house', 'appliances', 'washing machine', 'brand');
+------------------------+
| json_extract_path_text |
+------------------------+
| Any Brand |
+------------------------+
```
En el siguiente ejemplo, se crea una tabla de ejemplo y se rellena con valores SUPER. A continuación, se devuelve el valor de la ruta `'f2'` de ambas filas.
```
CREATE TABLE json_example(id INT, json_text SUPER);
INSERT INTO json_example VALUES
(1, JSON_PARSE('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}')),
(2, JSON_PARSE('{
"farm": {
"barn": {
"color": "red",
"feed stocked": true
}
}
}'));
SELECT * FROM json_example;
id | json_text
------------+--------------------------------------------
1 | {"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}
2 | {"farm":{"barn":{"color":"red","feed stocked":true}}}
SELECT id, JSON_EXTRACT_PATH_TEXT(JSON_SERIALIZE(json_text), 'f2') FROM json_example;
id | json_text
------------+--------------------------------------------
1 | {"f3":1}
2 |
```
Considere las siguientes instrucciones de ejemplo. El valor de *path\$1elem* proporcionado es NULL, por lo que JSON\$1EXTRACT\$1PATH\$1TEXT devuelve NULL independientemente del valor de cualquier otro parámetro.
```
--Statement where path_elem is NULL and json_string is valid JSON.
SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}',NULL);
json_extract_path_text
------------------------
NULL
--Statement where only one path_elem is NULL.
SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}','f4',NULL);
json_extract_path_text
------------------------
NULL
--Statement where path_elem is NULL and json_string is invalid JSON.
SELECT json_extract_path_text('invalid_json', NULL);
json_extract_path_text
------------------------
NULL
--Statement where path_elem is NULL and null_if_invalid is FALSE.
SELECT json_extract_path_text(NULL, 0, FALSE);
json_extract_path_text
------------------------
NULL
```
Considere las siguientes instrucciones de ejemplo. Cuando *null\$1if\$1invalid* es TRUE, JSON\$1EXTRACT\$1PATH\$1TEXT devuelve NULL cuando *json\$1string* es JSON no válido. Si *null\$1if\$1invalid* es FALSE o no se ha establecido, la función devuelve un error cuando *json\$1string* no es válido.
```
--Statement with invalid JSON where null_if_invalid is TRUE.
SELECT json_extract_path_text('invalid_json', 0, TRUE);
json_extract_path_text
------------------------
NULL
--Statement with invalid JSON where null_if_invalid is FALSE.
SELECT json_extract_path_text('invalid_json', 0, FALSE);
ERROR: JSON parsing error
```
Considere los siguientes ejemplos, donde *json\$1string* es JSON válido y *path\$1elem* hace referencia a un valor `null` JSON. En este caso, JSON\$1EXTRACT\$1PATH\$1TEXT devuelve NULL. Del mismo modo, cuando *path\$1elem* hace referencia a un valor inexistente, JSON\$1EXTRACT\$1PATH\$1TEXT devuelve NULL, independientemente del valor de *null\$1if\$1invalid*.
```
--Statement selecting a null value.
SELECT json_extract_path_text('[null]', 0);
json_extract_path_text
-------------------------
NULL
--Statement selecting a non-existing value.
SELECT json_extract_path_text('{}', 'a');
json_extract_path_text
-------------------------
NULL
```