Snowflake Cortex AI Functions: melhorias no tratamento de erros de várias linhas (versão preliminar)

Atenção

Esta mudança de comportamento faz parte do pacote 2026_02.

Para saber o status atual do pacote, consulte Histórico do pacote.

Quando esse pacote de mudança de comportamento é habilitado, a maioria das funções do Snowflake Cortex AI Functions retorna NULL em caso de erro, em vez de gerar o erro. Isso permite que consultas com várias linhas sejam concluídas mesmo que algumas linhas tenham erros. Além disso, a função AI_PARSE_DOCUMENT muda seu valor de retorno para ser mais consistente com o tratamento de erros das outras funções de AI.

Antes da mudança

A maioria das funções de AI gera um erro quando a função não é bem-sucedida, impedindo que consultas com várias linhas sejam concluídas quando apenas uma linha não pode ser processada.

Após a mudança

A maioria das funções de AI retorna NULL quando a função não é bem-sucedida, permitindo que consultas com várias linhas sejam concluídas quando algumas linhas não podem ser processadas. Linhas com erros podem ser facilmente excluídas dos resultados de várias linhas.

Um novo parâmetro final opcional nas funções de AI afetadas, return_error_details, que presente e definido como TRUE, faz com que as funções retornem um OBJECT com os campos value e error, em vez do tipo de resultado anterior. Se a função for bem-sucedida, o campo error será NULL e o campo value incluirá o valor de retorno real. Se a função falhar, o campo value será NULL e o campo error incluirá uma mensagem de erro. Além de permitir que linhas com erros sejam facilmente excluídas dos resultados de várias linhas, esse comportamento permite que os erros sejam registrados para revisão futura.

Além disso, pequenas alterações no valor de retorno da função AI_PARSE_DOCUMENT a tornam mais consistente com as outras funções de AI, conforme mostrado a seguir:

  • Quando o argumento return_error_details é FALSE ou não está presente, e ocorre um erro, a função retorna NULL.

  • Quando return_error_details está presente e é TRUE, o valor de retorno tem as seguintes mudanças em comparação com o comportamento anterior:

    • O campo metadata, que antes era um subcampo do campo de valor de nível superior, agora é o próprio campo de nível superior.

    • O subcampo errorInformation do campo value de nível superior foi renomeado para error para consistência com o campo de erro de nível superior. No entanto, o subcampo error não está presente quando não ocorre erro, enquanto o campo error de nível superior é NULL.

Funções de AI afetadas

As seguintes funções de AI são afetadas por esta mudança de comportamento:

  • AI_COMPLETE: gera respostas de texto a partir de prompts de texto ou imagem usando um modelo de linguagem grande (Large Language Model, LLM) especificado.

  • AI_CLASSIFY: classifica textos ou imagens em categorias definidas pelo usuário.

  • AI_FILTER: aplica filtros semânticos a textos e imagens expressos em linguagem natural.

  • AI_PARSE_DOCUMENT: extrai estrutura, texto, imagens e tabelas de documentos como Markdown.

  • AI_TRANSCRIBE: transcreve arquivos de áudio ou vídeo com a identificação do locutor e os carimbos de data/hora.

  • AI_TRANSLATE: traduz texto entre os idiomas compatíveis.

  • AI_SENTIMENT: executa a classificação de sentimento no conteúdo de texto.

  • AI_COUNT_TOKENS: estima o uso de tokens para prompts.

Funções de AI não afetadas

As seguintes funções de AI não são afetadas por esta mudança de comportamento:

  • AI_EXTRACT: essa função já trata os erros retornando as informações de erro como um campo separado no resultado e não causa falhas nas consultas com várias linhas devido a um único erro. O comportamento de AI_EXTRACT é semelhante ao novo comportamento das outras funções de AI quando return_error_details é TRUE, embora essa função não aceite return_error_details.

  • AI_AGG e AI_SUMMARIZE_AGG: funções agregadas não estão no escopo desta BCR. A Snowflake ainda está considerando como as linhas que causam erros devem se comportar na agregação. O comportamento dessas funções pode mudar em uma BCR futura.

  • AI_EMBED: essa função retorna um VECTOR, que não é compatível com objetos VARIANT. O comportamento dessa função pode mudar em uma BCR futura.

  • Funções de AI mais antigas no namespace SNOWFLAKE.CORTEX. A Snowflake não pretende mudar o comportamento dessas funções.

Funções auxiliares

Esta BCR inclui duas funções auxiliares que ajudam a extrair informações do objeto de detalhes do erro retornado quando return_error_details está definido como TRUE. Essas funções permitem acesso prático a comportamentos alternativos de tratamento de erros quando return_error_details está definido como TRUE.

  • AI_NULL_IF_ERROR: retorna NULL se o campo error do valor fornecido não é NULL, caso contrário, retorna o campo value. Esse é o mesmo comportamento de quando return_error_details está definido como FALSE.

  • AI_THROW_IF_ERROR: gera um erro do campo error do objeto fornecido se ele não é NULL, caso contrário, retorna o campo value. Esse é o mesmo comportamento que as funções de AI tinham antes dessa mudança de comportamento.

Exemplos

Os exemplos a seguir ilustram o novo comportamento de tratamento de erros. Esses exemplos usam AI_TRANSLATE, mas o comportamento é o mesmo para todas as funções afetadas.

Novo comportamento com e sem erro

A primeira amostra de código exibe a saída quando a função é bem-sucedida, e o segundo exemplo mostra a saída quando a função falha devido a um código de idioma inválido.

-- succeeds
SELECT AI_TRANSLATE(spanish_comment, 'es', 'en') as english_comment, "Este es un commentario" as spanish_comment;
Copy

Resultado:

+-------------------+------------------+
| ENGLISH_COMMENT   | SPANISH_COMMENT  |
|-------------------+------------------|
| This is a comment | Este es un       |
|                   | comentario       |
+-------------------+------------------+

-- fails
SELECT AI_TRANSLATE(spanish_comment, 'es', 'xx') as english_comment, "Este es un commentario" as spanish_comment;
Copy

Resultado

+-------------------+------------------+
| ENGLISH_COMMENT   | SPANISH_COMMENT  |
|-------------------+------------------|
| NULL              | Este es un       |
|                   | comentario       |
+-------------------+------------------+

Novo comportamento com detalhes do erro

Como já foi mencionado, a primeira amostra de código é o caso de sucesso e a segunda é o caso de erro.

  -- succeeds
  SELECT AI_TRANSLATE(spanish_comment, 'es', 'en', TRUE) as result, "Este es un commentario" as spanish_comment;

Result:
Copy
+--------------------------------+------------------+
| RESULT                         | SPANISH_COMMENT  |
|--------------------------------|------------------|
| {                              | Este es un       |
|   "value": "This is a comment",| comentario       |
|   "error": NULL                |                  |
| }                              |                  |
+--------------------------------+------------------+

-- fails
SELECT AI_TRANSLATE(spanish_comment, 'es', 'xx', TRUE) as result, "Este es un commentario" as spanish_comment;
Copy

Resultado:

+--------------------------------+------------------+
| RESULT                         | SPANISH_COMMENT  |
|--------------------------------|------------------|
| {                              | Este es un       |
|   "value": NULL,               | comentario       |
|   "error": "Invalid language   |                  |
|           \"xx\"               |                  |
+--------------------------------+------------------+

Consulta com várias linhas

Os exemplos a seguir mostram como usar o novo comportamento de tratamento de erros em uma consulta com várias linhas. Se ocorrer um erro ao processar uma linha, essa linha não será incluída no resultado. Os dados de exemplo são considerados uma tabela contendo comentários de usuários em vários idiomas, e a consulta tenta traduzir todos para o inglês usando AI_TRANSLATE.

SELECT
  AI_TRANSLATE(comment, comment_language, 'en') as translation_result,
  comment_language,
  comment
FROM comments
WHERE translation_result IS NOT NULL;
Copy

O exemplo abaixo mostra como usar o parâmetro return_error_details para obter o mesmo resultado que o exemplo anterior.

SELECT
  AI_TRANSLATE(comment, comment_language, 'en', TRUE) as translation_result,
  comment_language,
  comment
FROM comments
WHERE translation_result:value IS NOT NULL;
Copy

Ref: 2184