Introduction aux UDFs Python¶

Fonctionnement d’un gestionnaire Python¶

Lorsqu’un utilisateur appelle une UDF, il transmet le nom et les arguments de l’UDF à Snowflake. Snowflake appelle le code du gestionnaire associé (avec des arguments, le cas échéant) pour exécuter la logique de l’UDF. La méthode de gestion renvoie ensuite la sortie à Snowflake, qui la renvoie au client.

Pour chaque ligne transmise à une UDF, l’UDF renvoie soit une valeur scalaire (c’est-à-dire unique), soit, si elle est définie comme une fonction de table, un ensemble de lignes.

Les UDFs Python peuvent contenir à la fois du nouveau code et des appels vers des paquets existants, ce qui vous offre à la fois flexibilité et réutilisation du code. Par exemple, si vous disposez déjà d’un code d’analyse de données en Python, vous pouvez probablement l’intégrer dans un gestionnaire d’UDF Python.

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

Remarques relatives à la conception¶

Gardez à l’esprit les points suivants pour concevoir un gestionnaire utile.

• Considérations générales. Pour les considérations communes aux UDFs et aux procédures, reportez-vous à Directives et contraintes de conception pour les fonctions et les procédures.

• Mappage de type Python SQL. Lors de l’échange d’arguments et de valeurs de retour avec une UDF, Snowflake fait la conversion entre le langage du gestionnaire et SQL. Pour plus d’informations sur le choix des types de données pour votre code de gestionnaire, reportez-vous à Choisir vos types de données.

• Code empaqueté. Vous pouvez rendre le code de votre gestionnaire disponible soit en ligne avec l’instruction CREATE FUNCTION, soit sur une zone de préparation. Pour plus d’informations sur la différence, reportez-vous à Conserver le code du gestionnaire en ligne ou dans une zone de préparation.

• Optimisation de code. Pour plus d’informations sur l’optimisation du code de votre gestionnaire, par exemple lorsque le code gère des états partagés entre plusieurs lignes, reportez-vous à Optimisation de l’initialisation et contrôle de l’état global dans des UDFs scalaires et Optimisation de l’échelle et des performances.

• Meilleures pratiques. Pour plus d’informations sur les meilleures pratiques, voir Pratiques de sécurité pour UDFs et procédures.

Codage du gestionnaire¶

Des principes de base à des exemples détaillés, les rubriques suivantes décrivent comment écrire un gestionnaire d’UDF en Python.

• Définition de module Java. Vous écrivez la logique d’une UDF dans un module Python. Pour en savoir plus sur la manière dont Snowflake interagit avec votre code, reportez-vous à Conception du module.

• Traitement des erreurs. Pour plus d’informations sur la façon dont Snowflake traite les erreurs générées par les gestionnaires, reportez-vous à Gestion des erreurs.

• Valeurs de retour tabulaires. Vous pouvez renvoyer des valeurs tabulaires ainsi que des valeurs scalaires (individuelles) à partir d’une UDF. Pour plus d’informations sur la manière d’écrire un gestionnaire qui renvoie des valeurs tabulaires, reportez-vous à Écriture d’une UDTF en Python.

• Journalisation et traçage d’événements. Pour plus d’informations sur la capture des données de journal et de trace lors de l’exécution du code de votre gestionnaire, reportez-vous à Journalisation, traçage et métriques.

• Dépendances. Vous pouvez mettre des dépendances à la disposition de votre code au moment de l’exécution en les chargeant dans une zone de préparation. Pour plus d’informations, reportez-vous à Mettre les dépendances à la disposition de votre code.

• Exemples de code Pour une série d’exemples de gestionnaires en Python, reportez-vous à Exemples de gestionnaires d’UDF Python.