Snowflake Cortex AI Function: Multirow error handling improvements (Pending)

注意

此行为变更包含在 2026_02 捆绑包中。

有关捆绑包的当前状态，请参阅 捆绑包历史记录。

启用此行为变更捆绑包后，大多数 Snowflake Cortex AI 函数 在发生错误时将返回 NULL，而不是抛出错误。这样即使某些行存在错误，多行查询仍可完成。此外，AI_PARSE_DOCUMENT 函数更改了其返回值，使其与其他 AI 函数的错误处理方式保持一致。

变更前

大多数 AI 函数在执行失败时会抛出错误；在这种情况下，即使只有一行无法处理，也会导致整个多行查询中断。

变更后

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

在受影响的 AI 函数中新增了一个可选的末尾参数 return_error_details。当该参数存在并设置为 TRUE 时，函数将返回一个包含 value 和 error 字段的 OBJECT 对象，而不是之前的返回结果类型。如果函数执行成功，则 error 字段为 NULL，且 value 字段包含实际返回值。如果函数执行失败，则 value 字段为 NULL，且 error 字段包含错误消息。此行为不仅方便从多行结果中排除错误行，还允许将错误记录下来供日后复查。

此外，对 AI_PARSE_DOCUMENT 函数返回值的细微调整使其与其他 AI 函数更加一致，如下所示：

  • 当 return_error_details 实参为 FALSE 或不存在且发生错误时，函数返回 NULL。

  • 当 return_error_details 存在且为 TRUE 时，返回值与之前的行为相比有以下变化：

    • metadata 字段（以前是顶级值字段的子字段）现在本身即为一个顶级字段。

    • 顶级 value 字段的 errorInformation 子字段已重命名为 error，以便与顶级错误字段保持一致。不过，如果没有发生错误，则不存在 error 子字段，而顶级 error 字段则为 NULL。

受影响的 AI 函数

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

  • AI_COMPLETE：使用指定的大型语言模型 (LLM)，根据文本或图像提示生成文本响应。

  • AI_CLASSIFY：将文本或图像分类为用户定义的类别。

  • AI_FILTER：对以自然语言表达的文本和图像应用语义筛选器。

  • AI_PARSE_DOCUMENT：将文档结构、文本、图像和表格提取为 Markdown 格式。

  • AI_TRANSCRIBE：转录音频或视频文件，并带有说话者识别和时间戳。

  • AI_TRANSLATE：在支持的语言之间翻译文本。

  • AI_SENTIMENT：对文本内容执行情感分类。

  • AI_COUNT_TOKENS：估算提示的令牌使用量。

不受影响的 AI 函数

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

  • AI_EXTRACT：此函数已通过在结果中将错误信息作为独立字段返回来处理错误，因此不会因单行错误而导致多行查询失败。当 return_error_details 为 TRUE 时，AI_EXTRACT 的行为与其他 AI 函数的新行为类似，尽管此函数不接受 return_error_details。

  • AI_AGG 和 AI_SUMMARIZE_AGG：聚合函数不在本次 BCR 的范围内。Snowflake 仍在考虑在聚合操作中应如何处理导致错误的行。这些函数的行为可能会在未来的 BCR 中发生变更。

  • AI_EMBED：此函数返回一个 VECTOR，目前 VARIANT 对象尚不支持该类型。此函数的行为可能会在未来的 BCR 中发生变更。

  • SNOWFLAKE.CORTEX 命名空间中的旧版 AI 函数。Snowflake 无意更改这些函数的行为。

辅助函数

此 BCR 包含两个辅助函数，用于协助从 return_error_details 设置为 TRUE 时返回的错误详细信息对象中提取信息。当 return_error_details 设置为 TRUE 时，这些函数提供了对备选错误处理行为的便捷访问。

  • AI_NULL_IF_ERROR：选择使用 时默认使用的角色和仓库。如果给定值的 error 字段不是 NULL，则返回 NULL；否则返回 value 字段。这与 return_error_details 设置为 FALSE 时的行为相同。

  • AI_THROW_IF_ERROR：选择使用 时默认使用的角色和仓库。如果所提供对象的 error 字段不是 NULL，则抛出该错误；否则返回 value 字段。这与此行为变更前 AI 函数的行为相同。

示例

以下示例说明了新的错误处理行为。这些示例使用的是 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;

以下示例展示了如何使用 return_error_details 参数来实现与上一个示例相同的结果。

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

参考：2184