Função JSON_EXTRACT_ARRAY_ELEMENT_TEXT - Amazon Redshift
SintaxeArgumentosTipo de retornoExemplos

O Amazon Redshift não permitirá mais a criação de funções definidas pelo usuário (UDFs) do Python a partir de 1.º de novembro de 2025. Se quiser usar UDFs do Python, você deve criá-las antes dessa data. As UDFs do Python existentes continuarão a funcionar normalmente. Para ter mais informações, consulte a publicação de blog .

Função JSON_EXTRACT_ARRAY_ELEMENT_TEXT

nota

O JSON_PARSE e suas funções associadas analisam os valores JSON como SUPER, que o Amazon Redshift analisa com maior eficiência do que o VARCHAR.

Em vez de usar JSON_EXTRACT_ARRAY_ELEMENT_TEXT, recomendamos que você analise suas strings JSON usando o Função JSON_PARSE para ter um valor SUPER. Depois, consulte o elemento desejado usando o índice de matriz, com a sintaxe value[element position]. Para ter mais informações sobre como consultar elementos de matriz em valores SUPER, acesse Consultar dados semiestruturados.

A função JSON_EXTRACT_ARRAY_ELEMENT_TEXT retorna um elemento de array JSON no array mais externa de uma string JSON, usando um índice baseado em zero. O primeiro elemento em uma matriz fica na posição 0. Se o índice for negativo ou estiver fora do limite, JSON_EXTRACT_ARRAY_ELEMENT_TEXT retornará NULL. Se o argumento null_if_invalid for definido como TRUE e a string JSON for inválida, a função retornará NULL, em vez de retornar um erro.

Para obter mais informações, consulte Funções JSON.

Sintaxe

JSON_EXTRACT_ARRAY_ELEMENT_TEXT('json string', pos [, null_if_invalid ] )

Argumentos

json_string

Uma string JSON adequadamente formatada.

pos

Um INTEGER que representa o índice do elemento da matriz a ser retornado, usando um índice de matriz baseado em zero.

null_if_invalid

(Opcional) Um valor BOOLEAN que especifica se NULL será ou não retornado caso a string de entrada JSON seja inválida, em vez de retornar um erro. Para retornar NULL se JSON for inválido, especifique true (t). Para retornar um erro se JSON for inválido, especifique false (f). O padrão é “”. false.

Tipo de retorno

VARCHAR

Uma string VARCHAR representando o elemento da matriz JSON referido por pos.

Exemplos

Para retornar o elemento da posição 2 da matriz, que é o terceiro elemento de um índice de matriz baseado em zero, use o exemplo a seguir. 

SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('[111,112,113]', 2);
 
+---------------------------------+
| json_extract_array_element_text |
+---------------------------------+
|                             113 |
+---------------------------------+

Para retornar um erro porque JSON é inválido, use o exemplo a seguir.

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 definir null_if_invalid como true a fim de que a instrução retorne NULL, em vez de retornar um erro para o JSON inválido, use o exemplo a seguir.

SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('["a",["b",1,["c",2,3,null,]]]',1,true);
 
+---------------------------------+
| json_extract_array_element_text |
+---------------------------------+
| NULL                            |
+---------------------------------+

Considere o exemplo de declarações a seguir. Se a string JSON fornecida ou o índice for NULL, JSON_EXTRACT_ARRAY_ELEMENT_TEXT retornará NULL independentemente do valor de qualquer outro 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 o exemplo de declarações a seguir. Quando null_if_invalid é TRUE, JSON_EXTRACT_ARRAY_ELEMENT_TEXT retorna NULL quando json_string é um JSON inválido. Se null_if_invalid for FALSE ou não estiver definido, a função retornará um erro quando json_string for invá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 o exemplo a seguir, em que json_string é um JSON válido e pos se refere a um valor JSON null. Nesse caso, JSON_EXTRACT_ARRAY_ELEMENT_TEXT retorna NULL, independentemente do valor de null_if_invalid.

--Statement selecting a null value.
SELECT json_extract_array_element_text('[null]', 0);

  json_extract_array_element_text 
----------------------------------
                             NULL