Snowflake Cortex AI Function: Multirow error handling improvements¶

Attention

This behavior change is in the 2026_02 bundle.

For the current status of the bundle, refer to Bundle history.

When this behavior change bundle is enabled, most Snowflake Cortex AI Functions return NULL on error, rather than raising the error. This allows multi-row queries to complete even if some rows have errors. Additionally, the AI_PARSE_DOCUMENT function changes its return value to be more consistent with other AI Functions’ error handling.

Before the change Most AI Functions raise an error when the function does not succeed, preventing multi-row queries from completing when even one row cannot be processed.

After the change

大多数 AI 函数在执行失败时会返回 NULL；这允许在部分行无法处理时，多行查询仍能顺利完成。您可以轻松地从多行结果中排除包含错误的行。

A new, optional, final parameter in the affected AI Functions, return_error_details, when present and set to TRUE, causes the functions to return an OBJECT with value and error fields rather than rather than the former result type. If the function succeeded, the error field is NULL and the value field contains the actual return value. If the function failed, the value field is NULL and the error field contains an error message. In addition to allowing rows with errors to be easily excluded from multi-row results, this behavior allows errors to be recorded for later review.

Additionally, minor changes to the AI_PARSE_DOCUMENT function’s return value make it more consistent with other AI Functions, as follows:

When the return_error_details argument is FALSE or not present, and an error occurs, the function returns NULL.
When return_error_details is present and TRUE, the return value has the following changes compared to the previous behavior:
- The metadata field, formerly a subfield of the top-level value field, is now itself a top-level field.
- The errorInformation subfield of the top-level value field is renamed error for consistency with the top-level error field. However, the error subfield is not present when no error occurs, while the top-level error field is NULL.

受影响的 AI 函数¶

以下 AI 函数受此行为变更的影响：

AI_COMPLETE: Generates text responses from text or image prompts using a specified large language model (LLM).
AI_CLASSIFY: Classifies text or images into user-defined categories.
AI_FILTER: Applies semantic filters on text and images expressed in natural language.
AI_PARSE_DOCUMENT: Extracts document structure, text, images, and tables as Markdown.
AI_TRANSCRIBE: Transcribes audio or video files with speaker identification and timestamps.
AI_TRANSLATE: Translates text between supported languages.
AI_SENTIMENT: Performs sentiment classification on text content.
AI_COUNT_TOKENS: Estimates token usage for prompts.

不受影响的 AI 函数¶

以下 AI 函数不受此行为变更的影响：

AI_EXTRACT: This function already handles errors by returning error information as a separate field in the result and does not cause multi-row queries to fail due to a single error. AI_EXTRACT’s behavior is similar to the new behavior of other AI Functions when return_error_details is TRUE, although this function does not accept return_error_details.
AI_AGG and AI_SUMMARIZE_AGG: Aggregate functions are not in scope for this BCR. Snowflake is still considering how rows that cause errors should behave in aggregation. These functions’ behavior might change in a future BCR.
AI_EMBED: This function returns a VECTOR, which is not currently supported for VARIANT objects. This function’s behavior might change in a future BCR.
SNOWFLAKE.CORTEX 命名空间中的旧版 AI 函数。Snowflake 无意更改这些函数的行为。

辅助函数

This BCR includes two helper functions that assist with extracting information from the error details object returned when return_error_details is set to TRUE. These functions provide convenient access to alternative error handling behavior when return_error_details is set to TRUE.

AI_NULL_IF_ERROR: Returns NULL if the error field of the given value is not NULL, otherwise returns the value field. This is the same behavior as when return_error_details is set to FALSE.
AI_THROW_IF_ERROR: Raises an error from error field of the provided object if it is not NULL, otherwise returns the value field. This is the same behavior that AI Functions had before this behavior change.

示例

以下示例说明了新的错误处理行为。这些示例使用的是 AI_TRANSLATE，但所有受影响函数的行为均一致。

有错误和无错误情况下的新行为

第一个代码示例显示函数执行成功时的输出；第二个示例显示因语言代码无效而导致执行失败时的输出。

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

结果：

+-------------------+------------------+
| 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;

结果

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

包含错误详细信息的新行为

与前述一致，第一个代码示例为成功案例，第二个为错误案例。

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

Result:

+--------------------------------+------------------+
| 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;

结果：

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

多行查询

以下示例演示了如何在多行查询中使用新的错误处理行为。如果处理某一行时发生错误，该行将不会包含在结果中。假设示例数据是一张包含各种语言用户评论的表，查询尝试使用 AI_TRANSLATE 将所有评论翻译成英语。

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

The example below shows how to use the return_error_details parameter to achieve the same result as the previous example.

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

参考：2184