Création d’UDFs Python¶

Écriture le module et la fonction Python¶

Écrivez un module qui suit les spécifications ci-dessous :

• Définissez le module. Un module est un fichier contenant des définitions et des instructions Python.

• Définissez une fonction à l’intérieur du module.

• Si la méthode accepte des arguments, chaque argument doit être l’un des types de données spécifiés dans la colonne Python Data Type de la table SQL-Python Type Mappings.

  Les arguments de fonction sont liés par leur position, et non par leur nom. Le premier argument transmis à l’UDF est le premier argument reçu par la méthode Python.

• Spécifiez une valeur de retour appropriée. Comme une UDF Python doit être une fonction scalaire, elle doit renvoyer une valeur à chaque fois qu’elle est appelée. Le type de la valeur de retour doit être l’un des types de données spécifiés dans la colonne Python Data Type de la table SQL-Python Type Mappings. Le type de la valeur de retour doit être compatible avec le type de données SQL spécifié dans la clause RETURNS de l’instruction CREATE FUNCTION.

• Votre module peut contenir plus d’une fonction. La fonction qui est appelée par Snowflake peut appeler d’autres fonctions dans le même module ou dans d’autres modules.

• Votre fonction (et toute fonction appelée par votre fonction) doit respecter les contraintes Snowflake imposées pour les UDFs Python.

Création d’une UDF Python en ligne¶

Pour une UDF en ligne, vous fournissez le code source Python dans le cadre de l’instruction CREATE FUNCTION.

Par exemple, l’instruction suivante crée une UDF Python en ligne qui ajoute +1 à un nombre entier donné :

CREATE OR REPLACE FUNCTION addone(i INT)
  RETURNS INT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  HANDLER = 'addone_py'
AS $$
def addone_py(i):
 return i+1
$$;

Le code source Python est spécifié dans la clause AS. Le code source peut être délimité soit de guillemets simples, soit d’une paire de signes de dollar ($$). L’utilisation du double signe dollar est généralement plus facile si le code source contient des guillemets simples intégrés.

Appelez l’UDF :

SELECT addone(10);

Voici la sortie :

+------------+
| ADDONE(10) |
|------------|
|         11 |
+------------+

Le code source Python peut contenir plus d’un module, et plus d’une fonction dans un module, donc la clause HANDLER spécifie le module et la fonction à appeler.

Une UDF Python en ligne peut appeler du code dans les modules qui sont inclus dans la clause IMPORTS.

Pour plus de détails sur la syntaxe de l’instruction CREATE FUNCTION, voir CREATE FUNCTION.

Pour plus d’exemples, voir Exemples d’UDF Python en ligne.

Création d’une UDF Python avec du code téléchargé à partir d’une zone de préparation¶

Les instructions suivantes créent une simple UDF Python en utilisant du code téléchargé à partir d’une zone de préparation. La zone de préparation hébergeant le fichier doit être lisible par le propriétaire de l’UDF. En outre, les fichiers ZIP doivent être autonomes et ne pas dépendre de scripts d’installation supplémentaires pour être exécutés.

Créez un fichier Python nommé sleepy.py qui contient votre code source :

def snore(n):   # return a series of n snores
  result = []
  for a in range(n):
    result.append("Zzz")
  return result

Lancez SnowSQL (CLI client) et utilisez la commande PUT pour copier le fichier du système de fichiers local vers une zone de préparation utilisateur par défaut, nommée @~. (La commande PUT ne peut pas être exécutée par la GUI Snowflake.)

put
file:///Users/Me/sleepy.py
@~/
auto_compress = false
overwrite = true
;

Si vous supprimez ou renommez le fichier, vous ne pouvez plus appeler l’UDF. Si vous devez mettre à jour votre fichier, faites-le pendant qu’aucun appel à l’UDF ne soit possible. Si l’ancien fichier .jar se trouve toujours dans la zone de préparation, la commande PUT doit inclure la clause OVERWRITE=TRUE.

Créez l’UDF. Le gestionnaire spécifie le module et la fonction.

CREATE OR REPLACE FUNCTION dream(i INT)
  RETURNS VARIANT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  HANDLER = 'sleepy.snore'
  IMPORTS = ('@~/sleepy.py')

Appelez l’UDF :

SELECT dream(3);

+----------+
| DREAM(3) |
|----------|
| [        |
|   "Zzz", |
|   "Zzz", |
|   "Zzz"  |
| ]        |
+----------+

CREATE OR REPLACE FUNCTION multiple_import_files(s STRING)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  IMPORTS = ('@python_udf_dep/bar/python_imports_a.zip', '@python_udf_dep/foo/python_imports_b.zip')
  HANDLER = 'compute'
AS $$
def compute(s):
  return s
$$;