Créer une fonction définie par l’utilisateur¶

Créer une UDF¶

1. Écrivez la logique d’une fonction en tant que gestionnaire à l’aide de l’un des langages pris en charge, notamment Python, Java et Scala.

2. Choisissez un outil ou une API pour créer la fonction avec le gestionnaire que vous avez écrit.

   Pour plus d’informations sur chacun de ces éléments, voir Outils de création d’UDFs.

   SQL	Utilisez SQL et écrivez la logique dans un ou plusieurs langages.
   Snowpark	Utilisez l’API Snowpark pour Java, Python ou Scala.
   Ligne de commande	Exécutez les commandes CLI pour créer la fonction.
   Python API	Exécutez les commandes Python côté client pour créer la fonction.
   REST	Adressez des requêtes à l’API RESTful pour créer la fonction.

3. Exécutez la fonction à l’aide de l’un des outils suivants, selon vos besoins.

Outils de création d’UDFs¶

Vous pouvez créer une UDF en utilisant l’une des méthodes disponibles avec Snowflake, en fonction du langage et de l’ensemble des paramètres dont vous disposez. Choisissez l’outil qui correspond à vos besoins dans la table suivante.

Propriétés clés¶

Les paragraphes suivants décrivent certaines des propriétés requises ou généralement utilisées lors de la création d’une fonction.

Nom de la fonction:

Le nom de la fonction ne doit pas nécessairement correspondre au nom du gestionnaire. Pour plus d’informations sur les contraintes et les conventions relatives aux noms, voir Nommage et surcharge de procédures et d’UDFs.

Arguments:

Pour plus d’informations sur les exigences, voir Définition des arguments pour UDFs et les procédures stockées.

Type de retour:

Pour plus d’informations sur la façon dont Snowflake fait correspondre les types de données SQL aux types de données des gestionnaires, voir Mappage des types de données entre SQL et les langages de traitement.

Nom du gestionnaire:

Si nécessaire, il s’agit du nom de la classe ou de la méthode contenant le code qui s’exécute lorsque la fonction est exécutée. Vous devez spécifier un nom de gestionnaire uniquement pour les gestionnaires écrits en Java, Python et Scala. Pour les gestionnaires JavaScript et SQL, tout le code spécifié en ligne sera exécuté comme le gestionnaire.

Dépendances:

Pour un gestionnaire écrit en Java, Python ou Scala, vous devrez peut-être aussi spécifier la bibliothèque Snowpark, par exemple lors de la création de la fonction.

Pour plus d’informations sur la mise à disposition des dépendances pour votre gestionnaire, voir Mettre les dépendances à la disposition de votre code.

Environnement d’exécution du langage du gestionnaire:

Lorsque le langage du gestionnaire est Java, Python ou Scala, spécifiez la version d’exécution pour indiquer la version d’environnement d’exécution prise en charge à utiliser. Gardez à l’esprit que si vous utilisez la version par défaut, celle-ci évoluera au fil du temps.

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Le privilège USAGE relatif à la base de données et au schéma parents est exigé pour effectuer des opérations sur tout objet d’un schéma.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

Les notes sur l’utilisation décrivent les langages pris en charge pour l’écriture des gestionnaires. Bien que les notes des sections suivantes fassent référence aux clauses de la commande SQL CREATE FUNCTION, ces clauses sont généralement représentées d’une autre manière dans d’autres outils que vous pouvez utiliser pour créer des fonctions.

Créer une UDF avec SQL¶

Vous pouvez créer une UDF avec SQL en suivant les étapes suivantes.

Vous créez une UDF en suivant les étapes suivantes :

1. Écrivez le code du gestionnaire qui s’exécute lorsque l” UDF est appelée.

   Vous pouvez utiliser l’un des langages du gestionnaire pris en charge. Pour plus d’informations, voir Langages et outils pris en charge.

2. Choisissez si vous allez garder le code du gestionnaire en ligne avec l’instruction CREATE FUNCTION SQL ou si vous allez y faire référence dans une zone de préparation.

   Chacun a ses avantages. Pour plus d’informations, voir Conserver le code du gestionnaire en ligne ou dans une zone de préparation.

3. Exécutez une instruction CREATE FUNCTION dans SQL, en spécifiant les propriétés de la fonction.

   Le code de l’exemple suivant crée une UDF appelée function_name avec un gestionnaire en ligne HandlerClass.handlerMethod.

   create function function_name(x integer, y integer)
     returns integer
     language java
     handler='HandlerClass.handlerMethod'
     target_path='@~/HandlerCode.jar'
     as
     $$
         class HandlerClass {
             public static int handlerMethod(int x, int y) {
               return x + y;
             }
         }
     $$;
   

   Copy

   Les paragraphes suivants décrivent certaines des propriétés requises ou généralement utilisées lors de la création d’une fonction.

   • Nom de la fonction.

     Le nom de l’UDF ne doit pas nécessairement correspondre au nom de la méthode du gestionnaire. L’instruction CREATE FUNCTION associe le nom de l’UDF au gestionnaire.

     Pour plus d’informations sur les contraintes et les conventions relatives aux noms, voir Nommage et surcharge de procédures et d’UDFs.

   • Les arguments de la fonction, le cas échéant.

     Voir Définition des arguments pour UDFs et les procédures stockées.

   • Type de retour avec la clause RETURNS.

     Pour une valeur de retour scalaire, la clause RETURNS spécifiera un seul type de retour ; pour une valeur de retour tabulaire, RETURNS spécifiera le mot clé TABLE précisant le type de colonne dans la valeur de retour tabulaire.

     Pour plus d’informations sur la façon dont Snowflake fait correspondre les types de données SQL aux types de données des gestionnaires, voir Nommage et surcharge de procédures et d’UDFs.

   • Nom du gestionnaire avec la clause HANDLER.

     Si nécessaire, il s’agit du nom de la classe ou de la méthode contenant le code qui s’exécute lorsque l’UDF est appelée. Vous devez spécifier un nom de gestionnaire uniquement pour les gestionnaires écrits en Java et en Python. Pour les gestionnaires JavaScript et SQL, tout le code spécifié en ligne sera exécuté comme le gestionnaire.

     Le tableau suivant décrit la forme de la valeur de la clause HANDLER en fonction du langage et du type de fonction du gestionnaire.

     Langage du gestionnaire	UDF	UDTF
     Java	Nom de la classe et de la méthode. Par exemple : MyClass.myMethod	Nom de la classe seulement. Le nom de la méthode du gestionnaire est prédéterminé par l’interface requise.
     JavaScript	Aucun.	Aucun.
     Python	Nom de la classe et de la méthode si une classe est utilisée ; sinon, nom de la fonction. Par exemple : module.my_function ou my_function	Nom de la classe seulement. Le nom de la méthode du gestionnaire est prédéterminé par l’interface requise.
     SQL	Aucun.	Aucun.

   • Dépendances requises par le gestionnaire, le cas échéant, en utilisant les clauses IMPORTS ou PACKAGES.

     Pour plus d’informations sur la mise à disposition des dépendances pour votre gestionnaire, voir Mettre les dépendances à la disposition de votre code.

   • Exécution du langage du gestionnaire avec la clause RUNTIME_VERSION.

     Lorsque le langage du gestionnaire est Java ou Python, utilisez la clause RUNTIME_VERSION pour spécifier la version d’exécution prise en charge à utiliser. En omettant la clause, Snowflake utilisera la valeur par défaut, qui peut changer à l’avenir.