Utiliser des clean rooms avec Snowpark¶

Conception générale de flux d’utilisation complexes¶

Bien que vous puissiez générer vos données et les afficher en appelant un seul modèle, dans de nombreux cas, il est préférable de séparer les étapes de génération des données des étapes de visualisation des résultats. De cette façon, un consommateur peut visualiser les résultats plusieurs fois sans déclencher un nouveau calcul à chaque fois, ou voir les données à partir de différents points du processus. Pour diviser votre flux en plusieurs zones de préparation accessibles à l’utilisateur, créez des modèles distincts pour le déclenchement de la génération ou du traitement des données et pour la vue des résultats stockés. Pour en savoir plus sur la conception de flux d’utilisation complexes.

Conditions préalables¶

• Les Clean rooms qui exécutent les UDFs Snowpark doivent être exécutées dans les clean rooms API; elles ne peuvent pas être exécutées dans l’UI Clean room.

• Vous devez comprendre les sujets suivants :

  • Les bases de la création d’une clean room en code.

  • L’API Snowpark Python.

  • Comment télécharger les UDFs Python dans une clean room.

  • Comment créer des modèles personnalisés.

  • Consultez le site conception de flux à plusieurs étapes pour comprendre ce que sont les tables internes.

Utilisation de l’API Snowpark dans une clean room¶

L’utilisation de l’API Snowpark dans votre code Python de clean room est identique au téléchargement et à l’exécution de n’importe quel autre UDF Python, à l’exception du fait que vous devez établir un lien avec la bibliothèque snowflake-snowpark-python.

Créez des UDFs, des UDTFs, et des procédures en exécutant SQL à l’aide de session.sql dans le schéma cleanroom plutôt qu’en utilisant les décorateurs Snowpark. Par exemple :

session.sql("CREATE OR REPLACE FUNCTION cleanroom.udf(...")

Copy

Les étapes de base¶

Voici les étapes de base pour utiliser l’API Snowpark à travers un UDF ou un UDTF dans votre clean room :

Fournisseur

1. Créez la clean room, paramétrez la directive de version par défaut et liez vos données de manière standard.

2. Comme vous avez probablement un cas d’utilisation très spécifique pour votre code, vous n’aurez probablement pas besoin d’ajouter des politiques de jointure ou de colonne dans la clean room, bien que vous puissiez le faire.

3. Chargez le code de votre gestionnaire Snowpark personnalisé dans la clean room en appelant provider.load_python_into_cleanroom. Le code doit charger au minimum le paquet snowflake-snowpark-python, ainsi que tous les autres paquets dont vous avez besoin. Les UDFs peuvent traiter et renvoyer les données ligne par ligne, mais les cas d’utilisation de Snowpark génèrent généralement une table de sortie qui est lue en appelant un modèle de résultats séparé.

4. Mettez à jour la directive de version par défaut (car les ajouts de code génèrent une nouvelle version du correctif).

5. Créez et téléchargez un modèle personnalisé pour exécuter votre code Snowpark. La seule façon d’exécuter un UDF est de le déclencher à partir d’un modèle qui appelle l’UDF. Quelques détails sur le modèle d’appel UDF :

   • Il doit appeler la fonction en utilisant l’alias et les paramètres que vous avez spécifiés dans provider.load_python_into_cleanroom. Le modèle doit utiliser l’espace de noms cleanroom pour appeler l’alias de votre fonction.

   • Si l’UDF enregistre les résultats sur une table dans la clean room et que le nom de la table est différent pour chaque exécution, votre modèle de génération de résultats doit renvoyer le nom de la table de résultats et votre modèle de résultats doit prendre le nom de la table comme argument de la part de l’utilisateur.

6. Téléchargez un modèle personnalisé SQL pour accéder à la table de résultats générée par votre UDF Snowpark, si vous avez généré une table de résultats intermédiaire. Vous pouvez soit utiliser le nom de la table de résultats codé en dur, soit laisser l’utilisateur indiquer le nom de la table généré par votre code et renvoyé par le modèle de génération de résultats.

7. Ajoutez des collaborateurs et publiez la clean room de manière standard.

Consommateur

Le consommateur installe la clean room et effectue l’analyse de manière standard. Si la génération des données et la lecture des résultats sont réparties dans des modèles distincts, le consommateur devra appeler chaque modèle dans la séquence.

Exemple de code¶

L’exemple de code suivant montre comment télécharger et exécuter une régression linéaire de la portée sur le nombre d’impressions pour estimer la pente.

1. Le consommateur exécute d’abord le modèle prod_calculate_regression qui exécute un UDF fournisseur pour générer des résultats. L’UDF fournisseur effectue les actions suivantes :

   1. Prétraitement des données d’impression. Une table dynamique SQL est créée pour relier les données d’impression du fournisseur aux données du consommateur, calculer le nombre distinct d’impressions et la portée par date, et stocker les résultats dans une table intermédiaire à l’intérieur de la clean room. Si le consommateur ne fournit pas de table, le code s’exécute sur l’ensemble de la table d’impressions du fournisseur.

   2. Chargez la table intermédiaire. La table intermédiaire est chargée dans la procédure Snowpark en tant que pandas DataFrame.

   3. Effectuez la régression. La régression est calculée à l’aide de la bibliothèque statsmodels et renvoie les résultats sous forme de pandas DataFrame.

   4. Écrire les résultats dans une table interne à la clean room. Les résultats sont écrits dans une table de résultats à l’intérieur de la clean room, et le suffixe ID du nom de la table est renvoyé au consommateur. Étant donné que la procédure Snowpark est exécutée dans la clean room, elle a une possibilité limitée d’activer les données sur le compte du consommateur. Au lieu de cela, pour que les résultats soient plus sûrs, ils sont écrits dans une table à l’intérieur de la clean room, et le consommateur exécute un autre modèle pour lire les données des résultats.

   5. Abandonner les tables intermédiaires. Les tables intermédiaires créées pendant le calcul à l’intérieur de la clean room et qui ne sont plus nécessaires sont supprimées avant la fin de la procédure Snowpark.

   6. Renvoyer le nom de la table des résultats. Le nom renvoyé au consommateur doit être spécifié lors de l’exécution du modèle pour obtenir les résultats, car les résultats de toutes les exécutions précédentes sont conservés.

2. Le consommateur exécute ensuite le modèle get_results en indiquant le suffixe de la table de résultats renvoyée par le premier modèle pour obtenir les résultats.

Pour exécuter les exemples ci-dessous, vous avez besoin de deux comptes dans la même région d’hébergement web (à moins que vous n’ayez mis en œuvre l’exécution automatique inter-Cloud : un compte pour le fournisseur et un autre compte pour le consommateur.

Le code de l’exemple devrait s’exécuter dans une feuille de calcul Snowflake sans aucune configuration supplémentaire de Snowpark. Si vous travaillez dans un autre environnement, vous devrez peut-être installer et configurer l’API Python Snowpark.

• Exemple de notebook pour le fournisseur

• Exemple de notebook pour les consommateurs

Plus d’informations¶

• Création de fonctions définies par l’utilisateur (UDFs) pour DataFrames dans Python.

• API Snowpark

• Guide du développeur Snowpark pour Python

Conditions préalables¶

Vous devrez comprendre les sujets suivants pour pouvoir utiliser les services de conteneurs de Snowpark dans une clean room :

• Comment créer une clean room en code.

• L’API Snowpark Python si vous utilisez cette API.

• Comment créer des modèles personnalisés.

• Consultez pour concevoir des flux d’utilisation complexes. pour comprendre comment décomposer le traitement des données et l’exposition des résultats en étapes distinctes.

Les étapes de base¶

Fournisseur

1. Créez la spécification du service, le code et les points de terminaison qui traitent les requêtes.

2. Créez un référentiel d’images et accordez à SAMOOHA_APP_ROLE l’accès à ce référentiel.

3. Capturez l’URL de référentiel pour l’étape suivante.

4. Construisez et téléchargez l’image dans l’URL de référentiel.

5. Créez la clean room, créez des liens entre les données, ajoutez des politiques de jonction et ajoutez des consommateurs de manière standard.

6. Définissez les modèles qui appellent les points de service et téléchargez-les dans votre clean room. Les fonctions de service sont créées et appelées dans l’espace de noms service_functions (contrairement aux UDFs, qui sont créées et appelées dans l’espace noms cleanroom).

   -- Template to call an SPCS function named train.
   SELECT service_functions.train(
         {{ source_table[0] }},
         {{ provider_join_col }},
         {{ my_table[0] }},
         {{ consumer_join_col }},
         {{ dimensions | sqlsafe }},
   

   Copy

7. Téléchargez les détails de votre service dans la clean room en appelant provider.load_service_into_cleanroom. Ceci définit l’URL de l’image, les points de terminaison.

   ) AS train_result ;

8. Téléchargez les détails de votre service dans la clean room en appelant provider.load_service_into_cleanroom. Elle définit l’URL d’image, les points de terminaison et d’autres options de service. Les noms des points de terminaison définis ici doivent correspondre à la spécification de votre service et sont les noms que votre modèle utilise pour appeler les fonctions.

   CALL samooha_by_snowflake_local_db.provider.load_service_into_cleanroom(
   $cleanroom_name,
   $$
   spec:
     containers:
     - name: lal
       image: /dcr_spcs/repos/lal_example/lal_service_image:latest
       env:
         SERVER_PORT: 8000
     endpoints:
     - name: lalendpoint
       port: 8000
       public: false
   $$,
   $$
   functions:
     - name: train
       args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY, FILTER VARCHAR
       returns: VARCHAR
       endpoint: lalendpoint
       path: /train
   $$);
   

   Copy

9. Paramétrez la directive de version par défaut pour votre clean room. Chaque fois que vous téléchargez ou modifiez votre service, il crée une nouvelle version du correctif.

10. Publiez votre clean room.

11. Lorsque vous apportez des modifications à l’image, aux fonctions ou au code, vous et le consommateur devez mettre à jour vos instances.

Création du pool de calcul¶

Selon la personne qui doit posséder et configurer le pool de calcul, le fournisseur peut créer le pool de calcul à l’intérieur de la clean room, ou le consommateur peut créer le pool de calcul à l’extérieur de la clean room.

Si le pool de calcul est créé en dehors de la clean room, vous devez accorder les privilèges appropriés à la clean room pour accéder au pool et créer le service, comme indiqué ici :

-- Grant access to a warehouse to run queries. Needed only if the service queries Snowflake accounts.
USE ROLE ACCOUNTADMIN;
GRANT USAGE ON WAREHOUSE APP_WH TO APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>;

-- Grant SAMOOHA_APP_ROLE privileges to create compute pools and create services
GRANT CREATE COMPUTE POOL ON ACCOUNT TO ROLE SAMOOHA_APP_ROLE WITH GRANT OPTION;
GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO ROLE SAMOOHA_APP_ROLE WITH GRANT OPTION;


USE ROLE SAMOOHA_APP_ROLE;
-- Create the compute pool
CREATE COMPUTE POOL DCR_LAL_POOL
  FOR APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>
  min_nodes = 1 max_nodes = 1
  instance_family = highmem_x64_l
  auto_resume = true;

-- Grant the clean room the privileges to access a pool running outside the clean room.
-- Grant the clean room access to the compute pool
GRANT USAGE ON COMPUTE POOL DCR_LAL_POOL TO APPLICATION SAMOOHA_CLEANROOM_<CLEANROOM_NAME>;

-- Allow the clean room to create the service
GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO APPLICATION SAMOOHA_CLEANROOM_APP_<CLEANROOM_NAME>;

Mise à jour de votre code de service ou de votre configuration¶

Si le fournisseur met à jour l’image, les spécifications du service, les noms des points de terminaison ou le code source, le fournisseur et le consommateur doivent prendre les mesures suivantes.

1. Fournisseur :

1. Mettez à jour l’image ou le code source si nécessaire.

2. Appelez provider.load_service_into_cleanroom, qui renvoie un nouveau numéro de patch.

3. Appelez provider.set_default_release_directive en indiquant le nouveau numéro de patch.

2. Consommateur :

• Appelez consumer.start_or_update_service.

Le suivi de votre service¶

Par défaut, les consommateurs peuvent contrôler leur service. Ce comportement peut être modifié en utilisant la valeur allow_monitoring dans l’argument service_config de provider.load_service_into_cleanroom.

Si la surveillance des consommateurs est activée, le consommateur peut accéder aux connecteurs de surveillance d’un service de clean room donné (sous le format SAMOOHA_CLEANROOM_APP_SPCS_cleanroom_name.services.service), de l’ID de service et du conteneur, comme indiqué ci-dessous :

SELECT VALUE AS log_line
  FROM TABLE(
    SPLIT_TO_TABLE(SYSTEM$GET_SERVICE_LOGS(
        'SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service', 0, 'lal'), '\n')
  );

Le consommateur peut également voir l’état de son service, en utilisant la commande DESCRIBE SERVICE comme indiqué ici :

-- See the state of the service.
DESCRIBE SERVICE SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service;

Vous pouvez voir les points de terminaison de service en exécutant SHOW ENDPOINTS IN SERVICE SAMOOHA_CLEANROOM_APP_clean_room_name.services.service;. Par exemple :

SHOW ENDPOINTS IN SERVICE SAMOOHA_CLEANROOM_APP_SPCS_Lookalike_Demo.services.service;

Exemple de code¶

Les Notebooks et le fichier zip suivants montrent comment utiliser Snowflake Container Services dans une clean room. Vous avez besoin de deux comptes avec des clean rooms installées : un pour le fournisseur et un pour le consommateur. Ils doivent se trouver dans la même région d’hébergement Cloud. Utilisez les fichiers de configuration zippés pour définir le service.

• Exemple de notebook pour le fournisseur

• Exemple de notebook pour les consommateurs

• Fichiers de spécification et de configuration du service