Fonction Snowflake Cortex AI : Améliorations apportées à la gestion des erreurs multi-lignes (Avant-première)¶

Attention

Ce changement de comportement est présent dans le bundle 2026_02.

Pour connaître le statut actuel du bundle, reportez-vous à Historique du bundle.

Lorsque ce bundle de changements de comportement est activé, la plupart des fonctions Snowflake Cortex AI retournent NULL en cas d’erreur, plutôt que de générer l’erreur. Cela permet d’effectuer des requêtes à plusieurs lignes même si certaines lignes contiennent des erreurs. En outre, la fonction AI_PARSE_DOCUMENT modifie sa valeur de retour pour plus de cohérence avec la gestion des erreurs des autres fonctions AI.

Avant la modification	La plupart des fonctions AI signalent une erreur lorsque la fonction échoue, empêchant l’exécution des requêtes multi-lignes lorsqu’une seule ligne ne peut être traitée.
Après la modification	La plupart des fonctions AI renvoient NULL lorsque la fonction échoue, permettant l’exécution des requêtes multi-lignes lorsque certaines lignes ne peuvent être traitées. Les lignes comportant des erreurs peuvent facilement être exclues des résultats multi-lignes. Un nouveau paramètre final facultatif dans les fonctions AI concernées, `return_error_details`, lorsqu’il est présent et défini sur TRUE,fait en sorte que les fonctions renvoient un OBJECT avec les champs `value` et `error` plutôt que l’ancien type de résultat. Si la fonction a réussi, le champ `error` est NULL et le champ `value` contient la valeur de retour réelle. Si la fonction échoue, le champ `value` est NULL et le champ `error` contient un message d’erreur. En plus de permettre l’exclusion facile des lignes contenant des erreurs des résultats multi-lignes, ce comportement permet d’enregistrer les erreurs pour un examen ultérieur. De plus, des modifications mineures apportées à la valeur de retour de la fonction AI_PARSE_DOCUMENT la rendent plus cohérente avec les autres fonctions AI, comme suit : Lorsque l’argument `return_error_details` est FALSE ou absent, et qu’une erreur se produit, la fonction renvoie NULL. Lorsque `return_error_details` est présent et TRUE, la valeur de retour présente les changements suivants par rapport au comportement précédent : Le champ `metadata`, qui était auparavant un sous-champ du champ de valeurs de niveau supérieur, est désormais lui-même un champ de niveau supérieur. Le sous-champ `errorInformation` du champ de niveau supérieur `value` est renommé `error` par souci de cohérence avec le champ d’erreur de niveau supérieur. Cependant, le sous-champ `error` n’est pas présent lorsqu’aucune erreur ne se produit, alors que le champ `error` de niveau supérieur est NULL.

Avant la modification

La plupart des fonctions AI signalent une erreur lorsque la fonction échoue, empêchant l’exécution des requêtes multi-lignes lorsqu’une seule ligne ne peut être traitée.

Après la modification

La plupart des fonctions AI renvoient NULL lorsque la fonction échoue, permettant l’exécution des requêtes multi-lignes lorsque certaines lignes ne peuvent être traitées. Les lignes comportant des erreurs peuvent facilement être exclues des résultats multi-lignes.

Un nouveau paramètre final facultatif dans les fonctions AI concernées, return_error_details, lorsqu’il est présent et défini sur TRUE,fait en sorte que les fonctions renvoient un OBJECT avec les champs value et error plutôt que l’ancien type de résultat. Si la fonction a réussi, le champ error est NULL et le champ value contient la valeur de retour réelle. Si la fonction échoue, le champ value est NULL et le champ error contient un message d’erreur. En plus de permettre l’exclusion facile des lignes contenant des erreurs des résultats multi-lignes, ce comportement permet d’enregistrer les erreurs pour un examen ultérieur.

De plus, des modifications mineures apportées à la valeur de retour de la fonction AI_PARSE_DOCUMENT la rendent plus cohérente avec les autres fonctions AI, comme suit :

Lorsque l’argument return_error_details est FALSE ou absent, et qu’une erreur se produit, la fonction renvoie NULL.
Lorsque return_error_details est présent et TRUE, la valeur de retour présente les changements suivants par rapport au comportement précédent :
- Le champ metadata, qui était auparavant un sous-champ du champ de valeurs de niveau supérieur, est désormais lui-même un champ de niveau supérieur.
- Le sous-champ errorInformation du champ de niveau supérieur value est renommé error par souci de cohérence avec le champ d’erreur de niveau supérieur. Cependant, le sous-champ error n’est pas présent lorsqu’aucune erreur ne se produit, alors que le champ error de niveau supérieur est NULL.

Fonctions AI concernées¶

Les fonctions AI suivantes sont concernées par ce changements de comportement :

AI_COMPLETE : Génère des réponses textuelles à partir d’invites de texte ou d’image à l’aide d’un grand modèle de langage (LLM) spécifié.
AI_CLASSIFY : Classe le texte ou les images dans des catégories définies par l’utilisateur.
AI_FILTER : Applique des filtres sémantiques sur le texte et les images exprimés en langage naturel.
AI_PARSE_DOCUMENT : Extrait la structure du document, le texte, les images et les tableaux au format Markdown.
AI_TRANSCRIBE : Transfère des fichiers audio ou vidéo avec identification du locuteur et horodatages.
AI_TRANSLATE : Traduit le texte entre les langues prises en charge.
AI_SENTIMENT : Effectue une classification des sentiments sur le contenu textuel.
AI_COUNT_TOKENS : Estime l’utilisation de jetons pour les invites.

Fonctions AI non concernées¶

Les fonctions AI suivantes ne sont pas concernées par ce changement de comportement :

AI_EXTRACT : Cette fonction gère déjà les erreurs en renvoyant les informations d’erreur sous la forme d’un champ distinct dans le résultat et ne provoque pas l’échec des requêtes multi-lignes en raison d’une seule erreur. Le comportement de AI_EXTRACT est similaire au nouveau comportement des autres fonctions AI lorsque return_error_details est TRUE, bien que cette fonction n’accepte pas return_error_details.
AI_AGG et AI_SUMMARIZE_AGG : Les fonctions d’agrégation ne sont pas concernées par cette BCR. Snowflake réfléchit encore à la manière dont les lignes qui provoquent des erreurs doivent se comporter dans l’agrégation. Le comportement de ces fonctions pourrait changer dans une future BCR.
AI_EMBED : Cette fonction renvoie un VECTOR, qui n’est pas pris en charge actuellement pour les objets VARIANT. Le comportement de cette fonction pourrait changer dans une future BCR.
Anciennes fonctions AI dans l’espace de noms SNOWFLAKE .CORTEX. Snowflake n’a pas l’intention de modifier le comportement de ces fonctions.

Fonctions d’assistance¶

Cette BCR comprend deux fonctions d’aide qui permettent d’extraire des informations de l’objet de détails d’erreur renvoyé lorsque return_error_details est défini sur TRUE. Ces fonctions fournissent un accès pratique à un comportement alternatif de traitement des erreurs lorsque return_error_details est défini sur TRUE.

AI_NULL_IF_ERROR : Renvoie NULL si le champ error de la valeur donnée n’est pas NULL, sinon renvoie le champ value. Il s’agit du même comportement que lorsque return_error_details est défini sur FALSE.
AI_THROW_IF_ERROR : Indique une erreur du champ error de l’objet fourni s’il n’est pas NULL, sinon renvoie le champ value. Il s’agit du même comportement que celui des fonctions AI avant ce changement.

Exemples¶

Les exemples suivants illustrent le nouveau comportement de gestion des erreurs. Ces exemples utilisent AI_TRANSLATE, mais le comportement est le même pour toutes les fonctions concernées.

Nouveau comportement avec et sans erreur¶

Le premier exemple de code montre la sortie lorsque la fonction réussit, et le deuxième exemple montre la sortie lorsque la fonction échoue en raison d’un code de langue non valide.

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

Copy

Résultat :

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

Résultat

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

Nouveau comportement avec des détails d’erreur¶

Comme précédemment, le premier exemple de code est le cas de réussite et le second est le cas d’erreur.

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

Résultat :

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

Requête multi-lignes¶

Les exemples suivants montrent comment utiliser le nouveau comportement de gestion des erreurs dans une requête multi-lignes. Si une erreur se produit lors du traitement d’une ligne, cette ligne n’est pas incluse dans le résultat. Les données d’exemple sont supposées être un tableau contenant des commentaires d’utilisateurs dans différentes langues, et la requête tente de les traduire tous en anglais à l’aide de AI_TRANSLATE.

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

Copy

L’exemple ci-dessous montre comment utiliser le paramètre return_error_details pour obtenir le même résultat que dans l’exemple précédent.

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

Copy

Réf : 2184