Snowflake Cortex AI関数：複数行のエラー処理の改善（プレビュー）¶

注意

この動作変更は2026_02バンドルにあります。

バンドルの現在のステータスについては、バンドル履歴をご参照ください。

この動作変更バンドルが有効になっている場合、ほとんどの:doc:`Snowflake Cortex AI関数</user-guide/snowflake-cortex/aisql>`はエラー発生時にエラーを発生させるのではなく、NULLを返します。これにより、一部の行にエラーが発生しても、複数行のクエリを完了できます。さらに、:doc:`AI_PARSE_DOCUMENT</sql-reference/functions/ai_parse_document>`関数は、他のAI関数のエラー処理との一貫性を高めるために戻り値を変更します。

変更前	大半のAI関数は、関数が成功しないとエラーを発生させるため、1行を処理できない場合でも複数行のクエリは完了しません。
変更後	大半のAI関数は関数が失敗した場合にNULLを返すため、一部の行を処理できない場合でも複数行のクエリを完了できます。エラーのある行は、複数行の結果から簡単に除外できます。影響を受けるAI関数に新しく追加されたオプションの最終パラメーター``return_error_details``が存在し、TRUEに設定されている場合、関数は以前の結果タイプではなく、``value``と``error``のフィールドを持つ:ref:`OBJECT<label-data_type_object>`を返します。関数が成功した場合、``error``フィールドはNULLになり、``value``フィールドには実際の戻り値が含まれます。関数が失敗した場合、``value``フィールドはNULLになり、``error``フィールドにはエラーメッセージが含まれます。この動作により、エラーのある行を複数行の結果から簡単に除外できるだけでなく、後で確認できるようにエラーを記録することもできます。さらに、他のAI関数との整合性を高めるため、:doc:`AI_PARSE_DOCUMENT</sql-reference/functions/ai_parse_document>`関数の戻り値に若干の変更が加えられています。変更点は以下のとおりです。引数がFALSEであるか、``return_error_details``引数が存在しない場合、かつエラーが発生した場合、関数はNULLを返します。 ``return_error_details``が存在し、かつTRUEの場合の戻り値は、以前の動作と比較して以下の違いがあります。 ``metadata``フィールドは、以前はトップレベル値フィールドのサブフィールドでしたが、現在ではそれ自体がトップレベルフィールドとなっています。トップレベルの``value``フィールド内にある``errorInformation``サブフィールドは、トップレベルのerrorフィールドとの一貫性を保つために``error``に名称変更されました。しかし、エラーが発生していない場合、サブフィールドの``error``は存在しませんが、トップレベルの``error``フィールドはNULLとなります。

変更前

大半のAI関数は、関数が成功しないとエラーを発生させるため、1行を処理できない場合でも複数行のクエリは完了しません。

変更後

大半のAI関数は関数が失敗した場合にNULLを返すため、一部の行を処理できない場合でも複数行のクエリを完了できます。エラーのある行は、複数行の結果から簡単に除外できます。

影響を受けるAI関数に新しく追加されたオプションの最終パラメーター``return_error_details``が存在し、TRUEに設定されている場合、関数は以前の結果タイプではなく、``value``と``error``のフィールドを持つ:ref:`OBJECT<label-data_type_object>`を返します。関数が成功した場合、``error``フィールドはNULLになり、``value``フィールドには実際の戻り値が含まれます。関数が失敗した場合、``value``フィールドはNULLになり、``error``フィールドにはエラーメッセージが含まれます。この動作により、エラーのある行を複数行の結果から簡単に除外できるだけでなく、後で確認できるようにエラーを記録することもできます。

さらに、他のAI関数との整合性を高めるため、:doc:`AI_PARSE_DOCUMENT</sql-reference/functions/ai_parse_document>`関数の戻り値に若干の変更が加えられています。変更点は以下のとおりです。

引数がFALSEであるか、``return_error_details``引数が存在しない場合、かつエラーが発生した場合、関数はNULLを返します。
``return_error_details``が存在し、かつTRUEの場合の戻り値は、以前の動作と比較して以下の違いがあります。
- ``metadata``フィールドは、以前はトップレベル値フィールドのサブフィールドでしたが、現在ではそれ自体がトップレベルフィールドとなっています。
- トップレベルの``value``フィールド内にある``errorInformation``サブフィールドは、トップレベルのerrorフィールドとの一貫性を保つために``error``に名称変更されました。しかし、エラーが発生していない場合、サブフィールドの``error``は存在しませんが、トップレベルの``error``フィールドはNULLとなります。

影響を受けるAI関数¶

次のAI関数は、この動作変更の影響を受けます。

AI_COMPLETE：指定された大規模言語モデル（LLM）を使用して、テキストまたは画像プロンプトからテキスト応答を生成します。
AI_CLASSIFY：テキストまたは画像をユーザー定義のカテゴリに分類します。
AI_FILTER：自然言語で表現されたテキストと画像にセマンティックフィルターを適用します。
AI_PARSE_DOCUMENT：ドキュメント構造、テキスト、画像、テーブルをMarkdownとして抽出します。
AI_TRANSCRIBE：音声またはビデオファイルを、話者IDとタイムスタンプ付きで文字に変換します。
AI_TRANSLATE：サポートされている言語間でテキストを翻訳します。
AI_SENTIMENT：テキストコンテンツに対して感情分類を実行します。
AI_COUNT_TOKENS：プロンプトのトークン使用量を推定します。

影響を受けないAI関数¶

次のAI関数は、この動作変更の影響を*受けません*。

AI_EXTRACT：この関数は、結果の個別のフィールドとしてエラー情報を返すことによって既にエラーを処理しており、単一のエラーが原因で複数行のクエリを失敗させることはありません。AI_EXTRACTの動作は``return_error_details``がTRUEの場合の他のAI関数の新しい動作に似ていますが、関数は``return_error_details``を受け入れません。
AI_AGG：集計関数はこのBCRのスコープ内にありません。Snowflakeは、集計時にエラーが発生する行をどのように処理すべきかを検討中です。これらの関数の動作は将来のBCRで変更される可能性があります。
AI_EMBED：この関数はVECTORを返しますが、VARIANTオブジェクトでは現在サポートされていません。この関数の動作は将来のBCRで変更される可能性があります。
SNOWFLAKE.CORTEX名前空間にある古いAI関数。Snowflakeはこれらの関数の動作を変更する予定はありません。

ヘルパー関数¶

このBCRには、:code:`return_error_details`がTRUEに設定されている場合に返されるエラー詳細オブジェクトから情報を抽出するのに役立つ2つのヘルパー関数が含まれていますこれらの関数は、:code:`return_error_details`がTRUEに設定されている場合に、代替のエラー処理動作に簡単にアクセスできるようにします。

AI_NULL_IF_ERROR:指定された値の:code:`error`フィールドがNULLでない場合はNULLを返し、それ以外の場合は:code:`value`フィールドを返します。これは、:code:`return_error_details`をFALSEに設定した場合と同じ動作です。
AI_THROW_IF_ERROR:指定されたオブジェクトの:code:`error`フィールドがNULLでない場合はエラーを発生させ、それ以外の場合はその:code:`value`フィールドを返します。これは、この動作変更以前のAI関数の動作と同じです。

例¶

次の例は、新しいエラー処理動作を示しています。これらの例では、AI_TRANSLATEを使用していますが、動作は影響を受けるすべての関数で同じです。

エラーの有無による新しい動作¶

最初のコード例は、関数が成功した場合の出力を示し、2番目の例は、無効な言語コードのために関数が失敗した場合の出力を示しています。

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

Copy

結果:

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

結果

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

エラーの詳細に関する新しい動作¶

前回と同様、最初のコードサンプルは成功ケースで、2番目はエラーケースです。

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

Copy

以下の例は、前の例と同じ結果を得るために:code:`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;

Copy

参照:2184