Conserver le code du gestionnaire en ligne ou dans une zone de préparation¶

Lors de la création d’une fonction définie par l’utilisateur (UDF) ou d’une procédure stockée avec SQL, vous pouvez spécifier si le code du gestionnaire est en ligne avec la SQL qui la crée ou externe à la SQL, par exemple dans un fichier dans une zone de préparation. Cette rubrique décrit la différence.

Dans ce chapitre :

Différences pratiques¶

Avantages du gestionnaire en ligne¶

Cette option est généralement plus facile à mettre en œuvre. Après avoir utilisé vos outils de développement pour vérifier que votre code fonctionne comme il le devrait, vous pouvez le déployer en le copiant dans l’instruction SQL que vous exécutez pour créer la fonction ou la procédure. Vous pouvez conserver le code à cet endroit, en le mettant à jour avec une instruction SQL (comme avec ALTER FUNCTION ou ALTER PROCEDURE) sans avoir à conserver le code ailleurs.

Avantages du gestionnaire dans la zone de préparation¶

Lorsque vous utilisez un gestionnaire dans la zone de préparation, vous :

Pouvez utiliser du code précédemment compilé, par exemple lorsque vous avez déjà une sortie compilée mais que vous n’avez pas la source.
Pouvez utiliser le code du gestionnaire qui pourrait être trop volumineux pour être collé dans l’instruction SQL avec laquelle vous créez la fonction ou la procédure. Le code en ligne a une limite supérieure sur la taille du code source.
Pouvez réutiliser le code du gestionnaire de plusieurs fonctions ou procédures. Le code dans la zone de préparation peut contenir plusieurs fonctions de gestion dans lesquelles chaque fonction peut être utilisée par une UDF ou une procédure différente. Lorsque vous créez plusieurs UDFs ou procédures, ils peuvent chacun spécifier le même fichier de gestionnaire, mais spécifier une fonction de gestionnaire différente mise en œuvre dans ce fichier.

En revanche, le gestionnaire des fonctions ou procédures en ligne ne contient généralement qu’une seule fonction appelable. Cette fonction appelable peut appeler d’autres fonctions, et ces autres fonctions peuvent être définies dans le même fichier de code ou dans un autre fichier de code dans la zone de préparation.
Vous pourriez trouver plus pratique d’utiliser les outils de test et de débogage existants pour effectuer la majeure partie du travail de développement. Cela est particulièrement vrai si le code est vaste ou complexe.

Utilisation d’un gestionnaire en ligne¶

Lorsque vous utilisez un gestionnaire en ligne, vous incluez le code source du gestionnaire dans la clause AS de l’instruction SQL créant la fonction ou la procédure. Par exemple, vous pouvez inclure le code du gestionnaire dans la clause AS de l’instruction CREATE FUNCTION ou CREATE PROCEDURE elle-même.

À l’intérieur de la clause AS, vous devez entourer le code de guillemets simples ou d’une paire de signes de dollar ($$). L’utilisation du double signe dollar peut être plus facile, par exemple lorsque le code source contient des guillemets simples intégrés.

Si le code source du gestionnaire en ligne doit être compilé (comme dans le cas d’un gestionnaire écrit en Java ou Scala), Snowflake compile la source et stocke la sortie (comme un fichier JAR) pour une utilisation ultérieure. Vous pouvez éventuellement spécifier un emplacement pour un fichier de sortie résultant avec la clause TARGET_PATH.

Snowflake gère la sortie compilée de la manière suivante :

Si l’instruction SQL (comme CREATE FUNCTION) utilise TARGET_PATH pour spécifier un emplacement pour le fichier de sortie, Snowflake compile le code une fois et conserve la sortie compilée pour une utilisation ultérieure.
Si l’instruction SQL ne précise pas l’emplacement du fichier, Snowflake recompile le code pour chaque instruction SQL qui appelle la fonction ou la procédure. Snowflake nettoie automatiquement le fichier après la fin de l’instruction SQL.

Note

En tant que meilleure pratique lors de l’utilisation d’un gestionnaire Java ou Scala en ligne, pensez à spécifier une valeur pour le paramètre TARGET_PATH. Cela peut améliorer les performances car Snowflake réutilisera le résultat compilé du code du gestionnaire au lieu de recompiler le code pour chaque appel à la procédure ou à l’UDF.

Attention

Lorsque le code du gestionnaire est défini en ligne, il est capturé en tant que métadonnées. Si vous ne souhaitez pas que le code soit capturé sous forme de métadonnées, vous pouvez le déployer d’une autre manière, par exemple en utilisant un gestionnaire en zone de préparation.

Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, consultez Champs de métadonnées dans Snowflake.

Exemple en ligne avec le gestionnaire Java¶

Le code de l’exemple suivant crée une procédure stockée MYPROC avec un gestionnaire en ligne en Java. Le gestionnaire est la méthode run de la classe MyJavaClass.

CREATE OR REPLACE PROCEDURE MYPROC(fromTable STRING, toTable STRING, count INT)
  RETURNS STRING
  LANGUAGE JAVA
  RUNTIME_VERSION = '11'
  PACKAGES = ('com.snowflake:snowpark:latest')
  HANDLER = 'MyJavaClass.run'
  AS
  $$
    import com.snowflake.snowpark_java.*;

    public class MyJavaClass {
      public String run(Session session, String fromTable, String toTable, int count) {
        session.table(fromTable).limit(count).write().saveAsTable(toTable);
        return "SUCCESS";
      }
    }
  $$;

Copy

Pour les informations de référence CREATE PROCEDURE, voir CREATE PROCEDURE.

Utilisation d’un gestionnaire dans la zone de préparation¶

Lorsque vous utilisez un gestionnaire dans la zone de préparation, vous utilisez la clause IMPORTS pour référencer le gestionnaire à un autre endroit, tel qu’une zone de préparation. Par exemple, vous pouvez spécifier le chemin d’accès au gestionnaire avec la clause IMPORTS d’une instruction SQL telle que CREATE PROCEDURE ou CREATE FUNCTION.

Mise du gestionnaire en zone de préparation pour une utilisation à partir d’une fonction ou d’une procédure¶

La procédure suivante décrit comment ajouter un fichier de gestionnaire à l’environnement dans lequel votre fonction ou procédure s’exécute.

Si nécessaire, comme dans le cas d’un gestionnaire écrit en Java ou en Scala, compilez et empaquetez le code du gestionnaire pour le télécharger dans une zone de préparation. Pour plus d’informations sur les outils de construction, voir Empaquetage du code de gestionnaire.

Pour un gestionnaire écrit en Python, vous pouvez utiliser la source du module du gestionnaire.
Téléchargez le fichier du gestionnaire dans une zone de préparation comme décrit dans Mettre les dépendances à la disposition de votre code.
Faites référence au fichier du gestionnaire lorsque vous créez la fonction ou la procédure.

Vous faites référence au fichier du gestionnaire dans la clause IMPORTS, comme décrit dans Référencement de la dépendance.

Le code de l’exemple suivant crée un UDF appelé my_udf dont le gestionnaire, MyClass.myFunction, est écrit en Java. La clause IMPORTS du code spécifie que le fichier du gestionnaire, appelé my_handler.jar, se trouve dans la zone de préparation mystage dans le sous-répertoire handlers de l’étape. Au moment de l’exécution, Snowflake ajoute le gestionnaire JAR au classpath.
```
CREATE FUNCTION my_udf(i NUMBER)
  RETURNS NUMBER
  LANGUAGE JAVA
  IMPORTS = ('@mystage/handlers/my_handler.jar')
  HANDLER = 'MyClass.myFunction'
```
Copy
Pour des CREATE FUNCTION informations de référence, voir CREATE FUNCTION.

Mises en garde et meilleures pratiques¶

Si vous supprimez ou renommez le fichier du gestionnaire, vous ne pouvez plus appeler la fonction ou la procédure. Si vous devez mettre à jour votre fichier du gestionnaire, alors :

Assurez-vous d’abord qu’aucun appel n’est effectué vers la fonction ou la procédure qui utilise le gestionnaire.
Utilisez la commande PUT pour télécharger un nouveau fichier du gestionnaire. Si l’ancien fichier du gestionnaire se trouve toujours dans la zone de préparation lorsque vous téléchargez le nouveau, utilisez la clause OVERWRITE=TRUE de la commande PUT pour écraser l’ancien fichier du gestionnaire.