Snowflake Cortex AI Function: Multirow error handling improvements (Preview)¶

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	Most AI Functions return NULL when the function does not succeed, allowing multi-row queries to complete when some rows cannot be processed. Rows with errors can easily be excluded from multi-row results. 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.

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

Most AI Functions return NULL when the function does not succeed, allowing multi-row queries to complete when some rows cannot be processed. Rows with errors can easily be excluded from multi-row results.

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.

Affected AI functions¶

The following AI Functions are affected by this behavior change:

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.

Unaffected AI functions¶

The following AI Functionsare not affected by this behavior change:

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.
Older AI Functions in the SNOWFLAKE.CORTEX namespace. Snowflake does not intend to change these functions’ behavior.

Helper functions¶

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.

Examples¶

The following examples illustrate the new error handling behavior. These examples use AI_TRANSLATE, but the behavior is the same for all affected functions.

New behavior with and without error¶

The first code sample shows output when the function succeeds, and the second example shows output when the function fails due to an invalid language code.

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

Copy

Result:

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

Result

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

New behavior with error details¶

As before, the first code sample is the success case and the second is the error case.

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

Result:

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

Multirow query¶

The following examples show how to use the new error handling behavior in a multirow query. If an error occurs when processing a row, that row is not included in the result. The example data is assumed to be a table containing user comments in various languages, and the query attempts to translate them all into English using AI_TRANSLATE.

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

Copy

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;

Copy

Ref: 2184