Exemples de gestionnaires d’UDF Python¶

Conditions préalables¶

Avant que votre code de gestionnaire Python puisse lire un fichier sur une zone de préparation, vous devez effectuer les opérations suivantes pour mettre le fichier à la disposition du code :

1. Créez une zone de préparation accessible à votre gestionnaire.

   Vous pouvez utiliser une zone de préparation externe ou une zone de préparation interne. Si vous utilisez une zone de préparation interne, il peut s’agir d’une zone de préparation utilisateur lorsque vous prévoyez de créer une procédure stockée avec droits de l’appelant. Sinon, vous devez utiliser une zone de préparation nommée. Snowflake ne prend actuellement pas en charge l’utilisation d’une zone de préparation de table pour les dépendances UDF.

   Pour en savoir plus sur la création d’une zone de préparation, voir CREATE STAGE. Pour en savoir plus sur le choix d’un type de zone de préparation interne, voir Sélection d’une zone de préparation interne pour les fichiers locaux.

   Des privilèges adéquats sur la zone de préparation doivent être attribués au rôle suivant, en fonction de votre casse :

   Cas d’utilisation	Rôle
   UDF ou procédure stockée avec droits du propriétaire	Rôle qui possède l’UDF ou la procédure stockée en cours d’exécution.
   Procédure stockée avec droits de l’appelant	Rôle de l’utilisateur.

   Pour plus d’informations, voir Accorder des privilèges pour les fonctions définies par l’utilisateur.

2. Copiez le fichier que votre code lira dans la zone de préparation.

   Vous pouvez copier le fichier d’un lecteur local vers une zone de préparation interne en utilisant la commande PUT. Pour des informations sur la mise en zone de préparation de fichiers avec PUT, voir Mise en zone de préparation de fichiers de données à partir d’un système de fichiers local.

   Vous pouvez copier le fichier d’un lecteur local vers une zone de préparation externe à l’aide de l’un des outils fournis par votre service de stockage dans le Cloud. Pour obtenir de l’aide, consultez la documentation de votre service de stockage dans le Cloud.

Calcul du hachage perceptuel d’une image avec un gestionnaire Python en ligne¶

Cet exemple utilise SnowflakeFile pour lire une paire de fichiers images en zone de préparation et utiliser le hachage perceptuel (pHash) de chaque fichier pour déterminer le degré de similitude des images entre elles.

Créez une UDF qui renvoie la valeur phash d’une image, en spécifiant le mode d’entrée comme étant binaire en transmettant rb pour l’argument mode :

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

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

Créez une deuxième UDF qui calcule la distance entre les valeurs de phash de deux images :

CREATE OR REPLACE FUNCTION calc_phash_distance(h1 STRING, h2 STRING)
  RETURNS INT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('imagehash')
  HANDLER = 'run'
AS $$
import imagehash

def run(h1, h2):
  return imagehash.hex_to_hash(h1) - imagehash.hex_to_hash(h2)
$$;

Mettez en zone de préparation les fichiers images et actualisez la table du répertoire :

PUT file:///tmp/image1.jpg @images AUTO_COMPRESS=FALSE;
PUT file:///tmp/image2.jpg @images AUTO_COMPRESS=FALSE;

ALTER STAGE images REFRESH;

Appelez l’UDFs :

SELECT
  calc_phash_distance(
    calc_phash(build_scoped_file_url(@images, 'image1.jpg')),
    calc_phash(build_scoped_file_url(@images, 'image2.jpg'))
  ) ;

Traitement d’un fichier CSV à l’aide d’une UDTF¶

Cet exemple utilise SnowflakeFile pour créer une UDTF qui extrait le contenu d’un fichier CSV et renvoie les lignes dans un tableau.

Créez l’UDTF avec un gestionnaire en ligne :

CREATE FUNCTION parse_csv(file_path STRING)
  RETURNS TABLE (col1 STRING, col2 STRING, col3 STRING)
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('snowflake-snowpark-python')
  HANDLER = 'csvparser'
AS $$
from snowflake.snowpark.files import SnowflakeFile

class csvparser:
  def process(self, stagefile):
    with SnowflakeFile.open(stagefile) as f:
      for line in f.readlines():
        lineStr = line.strip()
        row = lineStr.split(",")
        try:
          # Read the columns from the line.
          yield (row[1], row[0], row[2], )
        except:
          pass
$$;

Mettez en zone de préparation le fichier CSV et actualisez la table du répertoire :

PUT file:///tmp/sample.csv @data_stage AUTO_COMPRESS=FALSE;

ALTER STAGE data_stage REFRESH;

Appelez l’UDTF en lui transmettant l’URL d’un fichier :

SELECT * FROM TABLE(PARSE_CSV(build_scoped_file_url(@data_stage, 'sample.csv')));

Traitement de plusieurs fichiers¶

Vous pouvez lire et traiter plusieurs fichiers en transmettant la colonne RELATIVE_PATH d’une table de répertoire à votre gestionnaire. Pour plus d’informations sur la colonne RELATIVE_PATH, consultez le résultat d’une requête de table de répertoire.

Appelez l’UDF pour traiter plusieurs fichiers :

L’exemple suivant appelle une UDF au sein d’une instruction CREATE TABLE pour traiter chaque fichier sur une zone de préparation, puis stocker les résultats dans une nouvelle table.

À des fins de démonstration, l’exemple repose sur les hypothèses suivantes :

• Une zone de préparation nommée my_stage contient plusieurs fichiers texte.

• Il existe une UDF nommée get_sentiment qui effectue une analyse des sentiments sur du texte non structuré. L’UDF prend en entrée le chemin d’un fichier texte et renvoie une valeur représentant le sentiment.

CREATE OR REPLACE TABLE sentiment_results AS
SELECT
  relative_path
  , get_sentiment(build_scoped_file_url(@my_stage, relative_path)) AS sentiment
FROM directory(@my_stage);

Copy

Appelez l’UDTF pour traiter plusieurs fichiers :

L’exemple suivant appelle une UDTF nommée parse_excel_udtf. L’exemple transmet le relative_path de la table du répertoire à la zone de préparation nommée my_excel_stage.

SELECT t.*
FROM directory(@my_stage) d,
TABLE(parse_excel_udtf(build_scoped_file_url(@my_excel_stage, relative_path)) t;

Copy

Lecture de fichiers avec des URLs et des URIs de zones de préparation¶

L’accès à un fichier avec SnowflakeFile nécessite par défaut des URLs scopées. Cela rend votre code résistant aux attaques par injection de fichiers. Toutefois, vous pouvez faire référence à l’emplacement d’un fichier en utilisant une URI ou une URL de zone de préparation. Pour ce faire, vous devez appeler la méthode SnowflakeFile.open avec l’argument mot-clé require_scoped_url = False.

Cette option est utile lorsque vous voulez permettre à un fournisseur de fournir une URI qui n’est accessible qu’au propriétaire de l’UDF. Par exemple, vous pouvez utiliser une URI de zone de préparation pour l’accès aux fichiers si vous possédez une UDF et que vous souhaitez lire vos fichiers de configuration ou vos modèles de machine learning. Nous ne recommandons pas cette option si vous travaillez avec des fichiers dont les noms sont imprévisibles, tels que les fichiers créés en fonction des entrées de l’utilisateur.

Cet exemple lit un modèle de machine learning dans un fichier et utilise le modèle dans une fonction pour effectuer un traitement du langage naturel pour l’analyse des sentiments. L’exemple appelle open avec require_scoped_url = False. Dans les deux formats de localisation des fichiers (URI et URL de zone de préparation), le propriétaire de l’UDF doit avoir accès au fichier modèle.

Créez l’UDF avec un gestionnaire en ligne :

CREATE OR REPLACE FUNCTION extract_sentiment(input_data STRING)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('snowflake-snowpark-python','scikit-learn')
  HANDLER = 'run'
AS $$
from snowflake.snowpark.files import SnowflakeFile
from sklearn.linear_model import SGDClassifier
import pickle

def run(input_data):
  model_file = '@models/NLP_model.pickle'
  # Specify 'mode = rb' to open the file in binary mode.
  with SnowflakeFile.open(model_file, 'rb', require_scoped_url = False) as f:
    model = pickle.load(f)
    return model.predict([input_data])[0]
$$;

Mettez en zone de préparation le fichier modèle et actualisez la table du répertoire :

PUT file:///tmp/NLP_model.pickle @models AUTO_COMPRESS=FALSE;

ALTER STAGE models REFRESH;

Vous pouvez également spécifier l’UDF avec l’URL de la zone de préparation du modèle pour extraire le sentiment.

Par exemple, créez une UDF avec un gestionnaire en ligne qui spécifie un fichier en utilisant une URL de zone de préparation :

CREATE OR REPLACE FUNCTION extract_sentiment(input_data STRING)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('snowflake-snowpark-python','scikit-learn')
  HANDLER = 'run'
AS $$
from snowflake.snowpark.files import SnowflakeFile
from sklearn.linear_model import SGDClassifier
import pickle

def run(input_data):
  model_file = 'https://my_account/api/files/my_db/my_schema/models/NLP_model.pickle'
  # Specify 'rb' to open the file in binary mode.
  with SnowflakeFile.open(model_file, 'rb', require_scoped_url = False) as f:
    model = pickle.load(f)
    return model.predict([input_data])[0]
$$;

Appelez l’UDF avec les données d’entrée :

SELECT extract_sentiment('I am writing to express my interest in a recent posting made.');