Charger et exécuter des fonctions personnalisées dans une salle blanche¶

Vue d’ensemble¶

Vous pouvez charger des UDFs et des UDTFs Python personnalisées dans votre salle blanche et les exécuter à partir de vos modèles pour effectuer des actions de données complexes. Ces actions comprennent le machine learning ou la manipulation personnalisée des données dans une requête, dans le cadre d’une seule étape ou d’un flux à plusieurs étapes. Python est le seul langage de codage pris en charge pour les UDFs personnalisées.

Votre code importé peut importer et utiliser des paquets à partir d’un bundle de packages Python approuvés et l’APISnowpark.

Les fournisseurs et les consommateurs peuvent charger du code Python personnalisé dans une salle blanche, bien que le processus soit différent pour les fournisseurs et les consommateurs. Chaque bundle de code importé peut définir plusieurs fonctions qui s’appellent entre elles, mais un bundle n’expose qu’une seule fonction de gestionnaire. Cette fonction de gestionnaire peut être appelée par des modèles créés ou exécutés par quiconque utilise la salle blanche. Si le code crée des tables internes, ces tables sont accessibles comme décrit dans la section Conception de flux à plusieurs étapes.

Le code importé ne peut pas être supprimé, mais il peut être mis à jour.

Cette page vous montre comment charger et exécuter des UDFs et des UDTFs Python personnalisées en tant que fournisseur ou consommateur.

Code soumis par le fournisseur¶

Les fonctions soumises par le fournisseur peuvent être chargées sous forme de code en ligne ou à partir d’une zone de préparation Snowflake. Les deux techniques sont couvertes ici.

Votre code chargé peut importer et utiliser nativement des packages à partir d’un ensemble approuvé de packages Python. Si vous avez besoin d’un package non proposé par défaut, vous devez utiliser Snowpark Container Services dans une salle blanche pour héberger votre code.

Vous ne pouvez pas voir le code importé, ni même votre propre code, alors veillez à inclure une copie de ce que vous chargez exactement dans une salle blanche.

Voici une vue de haut niveau de la manière dont un fournisseur ajoute du code à une salle blanche :

1. Le fournisseur crée et configure la salle blanche de manière habituelle.

2. Le fournisseur charge le code en appelant provider.load_python_into_cleanroom. Vous pouvez charger votre code en ligne directement dans cette procédure ou charger un fichier de code dans une zone de préparation. Puis, indiquez l’emplacement de la zone de préparation dans cette procédure.

   Bien que votre code puisse inclure plusieurs fonctions, un seul gestionnaire est exposé pour chaque chargement. Pour exposer plusieurs fonctions pour les modèles, téléchargez chaque gestionnaire en appelant provider.load_python_into_cleanroom.

3. Après chaque chargement de code réussi, une nouvelle version corrective de la salle blanche est générée. Vous devez ensuite améliorer la version par défaut en appelant provider.set_default_release_directive avec le nouveau numéro de correctif. Si la salle blanche est exposée à l’extérieur, les contrôles de sécurité sont exécutés avant d’installer votre code et vous devez appeler provider.view_cleanroom_scan_status pour confirmer que les contrôles de sécurité ont réussi avant d’incrémenter la version par défaut.

4. Vous créez et chargez un modèle personnalisé qui appelle votre code. Le modèle appelle la fonction de gestionnaire à l’aide du champ d’application de cleanroom, qui est : cleanroom.my_function. Par exemple, un modèle qui appelle une fonction simple_add personnalisée que vous avez chargée pourrait ressembler à ceci :

   SELECT cleanroom.simple_add(1, 2), cleanroom.simple_add({{ price | sqlsafe | int }}, {{ tax | sqlsafe | int }})
   

   Copy

5. Le consommateur exécute votre modèle de la même manière que tout autre modèle.

   Astuce

   Si le consommateur rencontre une erreur de montage lorsqu’il installe une salle blanche avec du code personnalisé, cela peut indiquer une erreur de syntaxe dans le code.

Vous trouverez des exemples de code démontrant ce flux dans la section d’exemple de code écrit par le fournisseur.

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
$cleanroom_name,
'simple_add',                         -- Name used to call the UDF from a template.
['first INTEGER', 'second INTEGER'],  -- Arguments of the UDF, specified as '<variable_name> <SQL type>' pairs.
['numpy', 'pandas'],                  -- Packages imported by the UDF.
'INTEGER',                            -- SQL return type of UDF.
'add_two',                            -- Handler function in your code called when external name is called.
$$
import numpy as np   # Not used, but you can load supported packages.
import pandas as pd

def add_two(first, second):
    return first + second
$$
);

-- Save the following code as reverser.py:
--import numpy as np
--def main(some_string):
--  '''Return the reverse of a string plus a random number 1-10'''
--  return some_string[::-1] + str(np.random.randint(1,10))

-- Get the stage for your clean room.
CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

-- Save the file to the stage. Here is how to do it by using the Snowflake CLI
PUT file://~/reverser.py <STAGE_NAME> overwrite=True auto_compress=False;

-- Load the code from the stage into the clean room.
CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'reverse', -- Name used to call the function
    ['some_string  STRING'], -- Arguments and SQL types
    ['numpy'],               -- Any required packages
    ['/reverser.py'],        -- Relative path to file on stage
    'STRING',                -- Return type
    'reverser.main'          -- <FILE_NAME>.<FUNCTION_NAME>
);

-- Uploading code, even from a stage, increases the patch number.
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name, 'V1_0', <NEW_PATCH_NUMBER>);

-- Upload a template that calls the function.
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $udf_template_name,
    $$
    SELECT
      p.status,
      cleanroom.reverse(p.status)
    FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS AS p
    LIMIT 100;
    $$
);

-- Switch to the consumer account and run the template to see the results.

Code soumis par le consommateur¶

Un consommateur peut soumettre du code d’UDF ou d’UDTF et l’appelez à partir d’un modèle personnalisé. Le code téléchargé par le consommateur est regroupé dans une seule procédure avec un modèle personnalisé et téléchargé dans un seul appel de procédure. Le code du consommateur est lié directement à ce modèle et ne peut pas être appelé par d’autres modèles.

Pour charger du code en tant que consommateur, vous devez comprendre la syntaxe des modèles personnalisés et comment soumettre un modèle défini par le consommateur.

Notez que tout code chargé par un consommateur peut être vu par le fournisseur lorsqu’il demande l’autorisation de l’importer. Le code du consommateur est également visible chaque fois qu’un fournisseur ou un consommateur examine le modèle.

Voici un aperçu des étapes à suivre pour charger un code consommateur personnalisé :

1. Le fournisseur crée la salle blanche de la manière standard, puis invite le consommateur.

2. Le consommateur installe et configure la salle blanche de la manière standard.

3. Le consommateur prépare un modèle. Le modèle appelle l’UDF ou l’UDTF dans l’espace de noms cleanroom. Par exemple, pour appeler la fonction calculate_tax définie par le consommateur, un modèle simple peut ressembler à l’extrait suivant :

   SELECT {{ cleanroom.calculate_tax(p.cost) }} AS Tax FROM my_db.my_sch.sales AS p;
   

   Copy

4. Le consommateur prépare son code Python. Nous vous recommandons d’utiliser des guillemets doubles (" ") plutôt que des guillemets simples (' ') dans votre code afin d’éviter tout échappement supplémentaire nécessaire ultérieurement. Votre code peut faire référence à un bundle de bibliothèques Python sélectionnées.

5. Le consommateur transmet son code Python à consumer.generate_python_request_template. La procédure renvoie le code Python sous forme de procédure stockée, avec un espace réservé pour le modèle JinjaSQL personnalisé. Il existe plusieurs chaînes de plusieurs lignes dans le modèle qui utilisent $$ en tant que délimiteurs à plusieurs lignes.

6. Remplacez l’espace réservé du modèle dans la sortie de generate_python_request_template par votre modèle JinjaSQL.

7. Dans le modèle combiné, échappez les guillemets simples comme suit : \'. En effet, les guillemets simples seront utilisés comme délimiteurs externes pour toute la chaîne de procédure multiligne. Par exemple :

     BEGIN
   
     CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
     RETURNS boolean
     LANGUAGE PYTHON
     RUNTIME_VERSION = 3.10
     PACKAGES = (\'numpy\')
   
     HANDLER = \'custom_compare\'
     AS $$
     import numpy as np
   
     def custom_compare(min_status:str, max_status:str, this_status:str):
       statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
       return ((statuses.index(this_status) >= statuses.index(min_status)) &
               (statuses.index(this_status) <= statuses.index(max_status)))
     $$;
   
     -- Custom template
     LET SQL_TEXT varchar := $$
     SELECT
       c.status,
       c.hashed_email
     FROM IDENTIFIER( {{ my_table[0] }} ) as c
     WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
     $$;
   
     LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
     RETURN TABLE(RES);
   
     END;
   

   Copy

8. Appelez consumer.create_template_request avec votre modèle combiné. Utilisez des guillemets simples (' ') au lieu de délimiteurs à double signe de dollar ($$...$$) autour du code que vous fournissez pour la procédure stockée dans l’argument template_definition. Par exemple :

   CALL samooha_by_snowflake_local_db.consumer.create_template_request(
     $cleanroom_name,
     $template_name,
     '
   BEGIN
   
   -- First, define the Python UDF.
   CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
   RETURNS boolean
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.10
   PACKAGES = (\'numpy\')
   
   HANDLER = \'custom_compare\'
   AS $$
   import numpy as np
   
   def custom_compare(min_status:str, max_status:str, this_status:str):
     statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
     return ((statuses.index(this_status) >= statuses.index(min_status)) &
             (statuses.index(this_status) <= statuses.index(max_status)))
       $$;
   
   -- Then define and execute the SQL query.
   LET SQL_TEXT varchar := $$
   SELECT
     c.status,
     c.hashed_email
   FROM IDENTIFIER( {{ my_table[0] }} ) as c
   WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
   $$;
   
   -- Execute the query and then return the result.
   LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
   RETURN TABLE(RES);
   
   END;
   ');
   

   Copy

9. Le consommateur et le fournisseur poursuivent avec le flux de modèles défini par le consommateur :

   1. Le fournisseur voit la requête de modèle (provider.list_pending_template_requests) et l’approuve ensuite en appelant approve_template_request. Dans la requête, le fournisseur peut voir le modèle et le code en bundle.

   2. Le consommateur vérifie le statut de la requête (consumer.list_template_requests), et lorsque le statut est APPROVED, il exécute le modèle (consumer.run_analysis).