Snowflake Cortex AI 함수: 다중 행 오류 처리 개선 사항(미리 보기)

주의

이 동작 변경 사항은 2026_02 번들에 포함되어 있습니다.

번들의 현재 상태는 번들 기록 섹션을 참조하십시오.

이 동작 변경 번들이 활성화되면 대부분의 Snowflake Cortex AI 함수 함수는 다른 AI 함수의 오류 처리와 더 일관되도록 반환 값을 변경합니다.

변경 전

대부분의 AI 함수는 함수가 성공하지 못하면 오류를 발생시켜 하나의 행도 처리할 수 없을 때 다중 행 쿼리가 완료되지 못하게 합니다.

변경 후

대부분의 AI 함수는 함수가 성공하지 못하면 NULL을 반환하여 일부 행을 처리할 수 없을 때 다중 행 쿼리가 완료되도록 합니다. 오류가 있는 행은 다중 행 결과에서 쉽게 제외할 수 있습니다.

영향을 받는 AI 함수의 새로운 선택적 마지막 매개 변수 return_error_details``가 존재하고 TRUE로 설정된 경우, 함수는 이전 결과 유형 대신 ``value 및 error 필드가 있는 OBJECT <label-data_type_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: 문서 구조, 텍스트, 이미지, 테이블을 마크다운으로 추출합니다.

  • AI_TRANSCRIBE: 화자 식별 및 타임스탬프가 포함된 오디오 또는 비디오 파일을 텍스트로 변환합니다.

  • AI_TRANSLATE: 지원되는 언어 간에 텍스트를 번역합니다.

  • AI_SENTIMENT: 텍스트 콘텐츠에 대한 감정 분류를 수행합니다.

  • AI_COUNT_TOKENS: 프롬프트에 대한 토큰 사용량을 추정합니다.

영향을 받지 않는 AI 함수

다음 AI 함수는 이 동작 변경의 영향을 받지 않습니다.

  • AI_EXTRACT: 이 함수는 이미 오류 정보를 결과의 별도 필드로 반환하여 오류를 처리하며 단일 오류로 인해 다중 행 쿼리가 실패하지 않도록 합니다. AI_EXTRACT의 동작은 ``return_error_details``가 TRUE일 때 다른 AI 함수의 새로운 동작과 유사하지만 이 함수는 ``return_error_details``를 허용하지 않습니다.

  • AI_AGG 및 AI_SUMMARIZE_AGG: 집계 함수는 이 BCR의 범위에 포함되지 않습니다. Snowflake는 오류를 유발하는 행이 집계에서 어떻게 동작해야 하는지 여전히 고려 중입니다. 이러한 함수의 동작은 향후 BCR에서 변경될 수 있습니다.

  • AI_EMBED: 이 함수는 VARIANT 오브젝트에 대해 현재 지원되지 않는 VECTOR를 반환합니다. 이 함수의 동작은 향후 BCR에서 변경될 수 있습니다.

  • SNOWFLAKE.CORTEX 네임스페이스의 기존 AI 함수: Snowflake는 이러한 함수의 동작을 변경할 계획이 없습니다.

도우미 함수

이 BCR에는 :code:`return_error_details`가 TRUE로 설정된 경우 반환되는 오류 세부 정보 오브젝트에서 정보를 추출하는 데 도움이 되는 두 개의 헬퍼 함수가 포함되어 있습니다. 이러한 함수를 사용하면 :code:`return_error_details`가 TRUE로 설정된 경우 대체 오류 처리 동작에 편리하게 액세스할 수 있습니다.

  • AI_NULL_IF_ERROR: 지정된 값의 error 필드가 NULL이 아닌 경우 NULL을 반환하고, 그렇지 않은 경우 value 필드를 반환합니다. 이는 :code:`return_error_details`가 FALSE로 설정된 경우와 동일한 동작입니다.

  • AI_THROW_IF_ERROR: NULL이 아닌 경우 제공된 오브젝트의 error 필드에서 오류를 발생시키고, 그렇지 않은 경우 value 필드를 반환합니다. 이는 이 동작 변경 이전의 AI 함수와 동일한 동작입니다.

예

다음 예제에서는 새로운 오류 처리 동작을 보여줍니다. 이 예제에서는 AI_TRANSLATE를 사용하지만, 영향을 받는 모든 함수에 대해 동작은 동일합니다.

오류가 있거나 없는 새로운 동작

첫 번째 코드 샘플은 함수가 성공할 때의 출력을 보여주고, 두 번째 예제에서는 유효하지 않은 언어 코드로 인해 함수가 실패할 때의 출력을 보여줍니다.

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

오류 세부 정보가 포함된 새로운 동작

이전과 마찬가지로, 첫 번째 코드 샘플은 성공 사례이고 두 번째 코드 샘플은 오류 사례입니다.

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

아래 예제에서는 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

Ref: 2184