Écriture de procédures stockées en Python¶

Limitations¶

Les procédures stockées de Snowpark ont les limitations suivantes :

• La création de processus n’est pas prise en charge dans les procédures stockées.

• L’exécution de requêtes simultanées n’est pas prise en charge dans les procédures stockées.

• Vous ne pouvez pas utiliser d’APIs qui exécutent des commandes PUT et GET (y compris Session.sql("PUT ...") et Session.sql("GET ...")).

• Lorsque vous téléchargez des fichiers à partir d’une zone de préparation en utilisant session.file.get, la correspondance de modèles n’est pas prise en charge.

• Si vous exécutez votre procédure stockée à partir d’une tâche, vous devez spécifier un entrepôt lors de la création de la tâche. Vous ne pouvez pas utiliser les ressources de calcul sans serveur pour exécuter la tâche.

• La création d’objets temp nommés n’est pas prise en charge dans une procédure stockée relative aux droits du propriétaire. Une procédure stockée avec les droits du propriétaire est une procédure stockée qui s’exécute avec les privilèges du propriétaire de la procédure stockée. Pour plus d’informations, voir les droits de l’appelant ou les droits du propriétaire.

Planification de l’écriture de votre procédure stockée¶

Les procédures stockées s’exécutent dans Snowflake, et vous devez donc planifier le code que vous écrivez en gardant cela à l’esprit.

• Limitez la quantité de mémoire consommée. Snowflake impose des limites à une méthode ou une fonction en matière de quantité de mémoire nécessaire. Pour obtenir des conseils, reportez-vous à Concevoir des gestionnaires qui respectent les contraintes imposées par Snowflake.

• Veillez à ce que la méthode ou la fonction de votre gestionnaire respecte le niveau de « thread safety ».

• Suivez les règles et les restrictions de sécurité. Reportez-vous à Pratiques de sécurité pour UDFs et procédures.

• Déterminez si vous souhaitez que la procédure stockée s’exécute avec les droits de l’appelant ou les droits du propriétaire.

• Envisagez la version snowflake-snowpark-python utilisée pour exécuter les procédures stockées. En raison de limitations dans le processus de version des procédures stockées, la bibliothèque snowflake-snowpark-python disponible dans l’environnement Python des procédures stockées est généralement en retard d’une version par rapport à la version publique. Utilisez le code SQL suivant pour connaître la dernière version disponible :

  select * from information_schema.packages where package_name = 'snowflake-snowpark-python' order by version desc;
  

  Copy

Écriture de la méthode ou de la fonction¶

Lorsque vous écrivez la méthode ou la fonction pour la procédure stockée, notez ce qui suit :

• Spécifiez l’objet Snowpark Session comme premier argument de votre méthode ou fonction. Lorsque vous appelez votre procédure stockée, Snowflake crée automatiquement un objet Session et le transmet à votre procédure stockée. (Vous ne pouvez pas créer l’objet Session vous-même).

• Pour le reste des arguments et pour la valeur de retour, utilisez les types Python qui correspondent aux types de données Snowflake. Snowflake prend en charge les types de données Python énumérés dans Mappages de type de données SQL-Python pour les paramètres et les types de retour

Gestion des erreurs¶

Vous pouvez utiliser les techniques normales de gestion des exceptions de Python pour détecter les erreurs au sein de la procédure.

Si une exception non détectée se produit à l’intérieur de la méthode, Snowflake génère une erreur qui inclut la trace de la pile pour l’exception. Lorsque l’enregistrement des exceptions non gérées est activé, Snowflake enregistre les données relatives aux exceptions non gérées dans une table d’événements.

Mettre les dépendances à la disposition de votre code¶

Si le code de votre gestionnaire dépend d’un code défini en dehors du gestionnaire lui-même (tel que le code défini dans un module) ou de fichiers de ressources, vous pouvez mettre ces dépendances à la disposition de votre code en les téléchargeant dans une zone de préparation. Reportez-vous à Mettre les dépendances à la disposition de votre code, ou pour les feuilles de calcul Python, reportez-vous à Ajouter un fichier Python d’une zone de préparation à une feuille de calcul.

Si vous créez votre procédure stockée à l’aide de SQL, utilisez la clause IMPORTS lors de l’écriture de l’instruction CREATE PROCEDURE, pour pointer vers les fichiers de dépendance.

Accès aux données dans Snowflake à partir de votre procédure stockée¶

Pour accéder aux données dans Snowflake, utilisez les APIs de bibliothèque Snowpark.

Lors du traitement d’un appel à votre procédure stockée Python, Snowflake crée un objet Session Snowpark et transmet cet objet à la méthode ou à la fonction de votre procédure stockée.

Comme c’est le cas avec les procédures stockées dans d’autres langages, le contexte de la session (par exemple, les privilèges, la base de données et le schéma actuels, etc.) est déterminé par le fait que la procédure stockée s’exécute avec les droits de l’appelant ou les droits du propriétaire. Pour plus de détails, voir Accessing and Setting the Session State.

Vous pouvez utiliser cet objet Session pour appeler des APIs dans la bibliothèque Snowpark. Par exemple, vous pouvez créer un DataFrame pour une table ou exécuter une instruction SQL.

Voir le Guide du développeur Snowpark pour plus d’informations.

def run(session, from_table, to_table, count):

  session.table(from_table).limit(count).write.save_as_table(to_table)

  return "SUCCESS"

Lecture de fichiers¶

Vous pouvez lire dynamiquement un fichier en zone de préparation dans votre gestionnaire Python en utilisant la classe SnowflakeFile du module Snowpark snowflake.snowpark.files.

Snowflake prend en charge la lecture de fichiers avec SnowflakeFile tant pour les procédures stockées que pour les fonctions définies par l’utilisateur. Pour plus d’informations sur la lecture de fichiers dans le code de votre gestionnaire, ainsi que d’autres exemples, reportez-vous à Lecture d’un fichier avec un gestionnaire d’UDF Python.

Cet exemple montre comment créer et appeler une procédure stockée sur les droits du propriétaire qui lit un fichier à l’aide de la classe SnowflakeFile.

Créez la procédure stockée avec un gestionnaire en ligne, en spécifiant le mode d’entrée comme étant binaire en transmettant rb pour l’argument mode :

CREATE OR REPLACE PROCEDURE calc_phash(file_path string)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python','imagehash','pillow')
HANDLER = 'run'
AS
$$
from PIL import Image
import imagehash
from snowflake.snowpark.files import SnowflakeFile

def run(ignored_session, file_path):
    with SnowflakeFile.open(file_path, 'rb') as f:
        return imagehash.average_hash(Image.open(f))
$$;

Appelez la procédure stockée :

CALL calc_phash(build_scoped_file_url(@my_files, 'my_image.jpg'));

Utilisation de paquets tiers à partir d’Anaconda¶

Vous pouvez spécifier les paquets Anaconda à installer lorsque vous créez des procédures stockées Python. Pour voir la liste des paquets tiers d’Anaconda, consultez le canal Anaconda Snowflake. Ces paquets tiers sont construits et fournis par Anaconda. Vous pouvez utiliser le canal Anaconda de Snowflake pour des tests et du développement locaux, sans frais, conformément aux conditions supplémentaires relatives aux logiciels embarqués des conditions de service d’Anaconda.

Pour connaître ces limitations, voir Limitations.

Prise en main¶

Avant de commencer à utiliser les paquets fournis par Anaconda dans Snowflake, vous devez accepter les conditions des offres externes.

1. Connectez-vous à Snowsight.

2. Sélectionnez Admin » Billing & Terms.

3. Dans la section Anaconda, sélectionnez Enable.

4. Dans la boîte de dialogue Anaconda Packages , cliquez sur le lien pour consulter la page des conditions des offres externes.

5. Si vous acceptez les conditions, sélectionnez Acknowledge & Continue.

Si une erreur apparaît lorsque vous essayez d’accepter les conditions d’utilisation, il se peut qu’il manque un prénom, un nom ou une adresse e-mail dans votre profil d’utilisateur. Si vous avez un rôle d’administrateur, reportez-vous aux Ajouter des détails sur l’utilisateur à votre profil d’utilisateur pour mettre à jour votre profil à l’aide de Snowsight. Sinon, contactez un administrateur pour mettre à jour votre compte.

Affichage et utilisation des paquets¶

Vous pouvez afficher tous les packages disponibles et leurs informations de version en interrogeant la vue PACKAGES dans Information Schema :

select * from information_schema.packages where language = 'python';

Pour plus d’informations, voir Utilisation de paquets de tiers dans la documentation de Snowflake sur les UDF Python.

Création d’une procédure stockée Python pour automatiser le code de votre feuille de calcul Python¶

Créez une procédure stockée Python à partir de votre feuille de calcul Python pour automatiser votre code. Pour plus de détails sur l’écriture de feuilles de calcul Python, consultez Écriture de code Snowpark dans des feuilles de calcul Python.

Exemple¶

Les exemples de cette section illustrent le retour de valeurs tabulaires à partir d’une procédure qui filtre les lignes où une colonne correspond à une chaîne.

CREATE OR REPLACE TABLE employees(id NUMBER, name VARCHAR, role VARCHAR);
INSERT INTO employees (id, name, role) VALUES (1, 'Alice', 'op'), (2, 'Bob', 'dev'), (3, 'Cindy', 'dev');

CREATE OR REPLACE PROCEDURE filterByRole(tableName VARCHAR, role VARCHAR)
RETURNS TABLE(id NUMBER, name VARCHAR, role VARCHAR)
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'filter_by_role'
AS
$$
from snowflake.snowpark.functions import col

def filter_by_role(session, table_name, role):
   df = session.table(table_name)
   return df.filter(col("role") == role)
$$;

CREATE OR REPLACE PROCEDURE filterByRole(tableName VARCHAR, role VARCHAR)
RETURNS TABLE()
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'filter_by_role'
AS
$$
from snowflake.snowpark.functions import col

def filter_by_role(session, table_name, role):
  df = session.table(table_name)
  return df.filter(col("role") == role)
$$;

CALL filterByRole('employees', 'dev');

+----+-------+------+
| ID | NAME  | ROLE |
+----+-------+------+
| 2  | Bob   | dev  |
| 3  | Cindy | dev  |
+----+-------+------+

Exécution de tâches simultanées à l’aide de processus de travail¶

Vous pouvez exécuter des tâches simultanées à l’aide de processus de travail Python. Cela peut s’avérer utile lorsque vous devez exécuter des tâches parallèles qui tirent parti de plusieurs cœurs CPU sur les nœuds de l’entrepôt.

Pour contourner les cas où le Python Global Interpreter Lock empêche une approche multitâche de s’étendre à tous les cœurs CPU, vous pouvez exécuter des tâches concurrentes à l’aide de processus de travail distincts, plutôt que de threads.

Vous pouvez le faire sur des entrepôts Snowflake en utilisant la classe Parallel de la bibliothèque joblib comme dans l’exemple suivant.

CREATE OR REPLACE PROCEDURE joblib_multiprocessing_proc(i INT)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.8
  HANDLER = 'joblib_multiprocessing'
  PACKAGES = ('snowflake-snowpark-python', 'joblib')
AS $$
import joblib
from math import sqrt

def joblib_multiprocessing(session, i):
  result = joblib.Parallel(n_jobs=-1)(joblib.delayed(sqrt)(i ** 2) for i in range(10))
  return str(result)
$$;

import joblib
joblib.parallel_backend('loky')