Snowflake Data Clean Rooms : analyse des données des fournisseurs¶

Mise en place de l’environnement¶

Exécutez les commandes suivantes pour configurer l’environnement Snowflake avant d’utiliser les APIs du développeur pour travailler avec une Snowflake Data Clean Room. Si vous n’avez pas le rôle SAMOOHA_APP_ROLE, contactez votre administrateur de compte.

use role samooha_app_role;
use warehouse app_wh;

Créer la salle blanche¶

Créez un nom pour la salle blanche. Saisissez un nouveau nom de salle blanche pour éviter toute collision avec des noms de salle blanche existants. Notez que les noms des salles blanches ne peuvent être que alphanumériques. Les noms des salles blanches ne peuvent pas contenir de caractères spéciaux autres que des espaces et des traits de soulignement.

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

Vous pouvez créer une nouvelle salle blanche avec le nom de la salle blanche défini ci-dessus. Si le nom de la salle blanche défini ci-dessus existe déjà en tant que salle blanche existante, ce processus échoue.

Cette procédure dure environ 45 secondes.

Le deuxième argument de provider.cleanroom_init est la distribution de la salle blanche. Il peut s’agir de INTERNAL ou de EXTERNAL. À des fins de test, si vous partagez la salle blanche avec un compte de la même organisation, vous pouvez utiliser INTERNAL pour contourner l’analyse de sécurité automatisée qui doit avoir lieu avant qu’un paquet d’applications ne soit publié aux collaborateurs. Cependant, si vous partagez cette salle blanche avec un compte dans une autre organisation, vous devez utiliser une distribution de salle blanche EXTERNAL.

call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Pour voir le statut de l’analyse de sécurité, utilisez :

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Une fois que vous avez créé votre salle blanche, vous devez définir sa directive de version avant de pouvoir la partager avec un collaborateur. Toutefois, si votre distribution a été définie sur EXTERNAL, vous devez d’abord attendre la fin de l’analyse de sécurité avant de définir la directive de version. Vous pouvez continuer à exécuter le reste des étapes et revenir ici avant l’étape provider.create_cleanroom_listing pendant que l’analyse s’exécute.

Pour définir la directive de version, appelez :

call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Partage interrégional¶

Pour partager une salle blanche avec un client de Snowflake dont le compte se trouve dans une région différente de votre compte, vous devez activer [l’exécution automatique inter-Cloud] (https://other-docs.snowflake.com/fr/collaboration/provider-listings-auto-fulfillment). Pour des informations sur les coûts supplémentaires liés à la collaboration avec des consommateurs d’autres régions, voir Coûts de l’exécution automatique inter-Cloud.

Lorsque vous utilisez les APIs du développeur, l’activation du partage interrégional se fait en deux étapes :

1. Un administrateur Snowflake ayant le rôle ACCOUNTADMIN active l’exécution automatique inter-Cloud pour votre compte Snowflake. Pour plus d’informations, voir Collaborer avec des comptes situés dans des régions différentes.

2. Vous exécutez la commande provider.enable_laf_for_cleanroom pour activer l’exécution automatique inter-Cloud pour la salle blanche. Par exemple :

   call samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);
   

   Copy

Après avoir activé l’exécution automatique inter-Cloud pour la salle blanche, vous pouvez ajouter des consommateurs à votre annonce comme d’habitude à l’aide de la commande provider.create_cleanroom_listing. L’annonce est automatiquement répliquée vers des cloud et des régions distantes, selon les besoins.

Lier et définir la politique de jointure pour l’ensemble de données¶

Liez des tables Snowflake dans la salle blanche. Parcourez la liste des tables de votre compte Snowflake et saisissez les noms de table entièrement qualifiés (Database.Schema.Table) sous forme de tableau. La procédure rend automatiquement la table accessible à la salle blanche en créant une vue sécurisée de la table depuis l’intérieur de la salle blanche, évitant ainsi tout besoin de faire une copie de votre table.

call samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

use role accountadmin;
call samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
use role samooha_app_role;

Si vous souhaitez voir les ensembles de données qui ont été ajoutés à la salle blanche, appelez la procédure suivante.

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Vous pouvez voir les ensembles de données liés à la salle blanche en suivant la procédure suivante :

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

Indiquez quelles colonnes le consommateur est autorisé à joindre lors de l’exécution de modèles dans la salle blanche. Cette procédure doit être appelée sur les colonnes d’identité comme l’adresse e-mail. La politique de jointure est de type « remplacement uniquement », donc si la fonction est appelée à nouveau, la politique de jointure précédemment définie est entièrement remplacée par la nouvelle.

call samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

Si vous souhaitez voir la politique de jointure qui a été ajoutée à la salle blanche, appelez la procédure suivante.

call samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Ajouter des modèles d’analyse à la salle blanche¶

Ajouter une liste de modèles pré-spécifiés à l’aide de leurs identificateurs de noms. Dans ce flux, vous ajoutez un modèle prédéfini qui vous permet d’effectuer des analyses de données sur les ensembles de données du fournisseur de manière sécurisée et approuvée par le fournisseur sur des colonnes approuvées par le fournisseur.

call samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_provider_data_analysis']);

Si vous souhaitez voir les modèles actuellement actifs dans la salle blanche, appelez la procédure suivante.

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Tout modèle ajouté à la salle blanche peut également être supprimé si nécessaire. Voir le Guide de référence du fournisseur API pour plus de détails.

Définir la politique des colonnes pour chaque table¶

Affichez les données liées pour voir les colonnes présentes dans la table. Pour voir les 10 premières lignes, appelez la procédure suivante.

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

Définissez les colonnes que le consommateur peut regrouper, agréger (par exemple, SUM ou AVG) et généralement utiliser dans une analyse pour chaque combinaison de table et de modèle. Cela offre une certaine souplesse, de sorte qu’une même table peut permettre des sélections de colonnes différentes en fonction du modèle sous-jacent. Cette fonction ne doit être appelée qu’après l’ajout du modèle.

Notez que la politique de colonnes est remplacement uniquement, donc si la fonction est appelée à nouveau, la politique de colonnes précédemment définie est complètement remplacée par la nouvelle.

La politique de colonnes ne doit pas être utilisée pour les colonnes d’identité telles que l’adresse e-mail, HEM ou RampID, car vous ne souhaitez pas que le consommateur puisse effectuer des groupes en fonction de ces colonnes. Dans l’environnement de production, le système déduit intelligemment les colonnes PII et bloque cette opération, mais cette fonction n’est pas disponible dans l’environnement sandbox. Elle ne doit être utilisée que pour les colonnes par lesquelles vous souhaitez que le consommateur puisse faire des agrégations et des groupes, comme le statut, la tranche d’âge, le canal ou le nombre de jours d’activité.

call samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE']);

Si vous souhaitez voir la politique de colonnes qui a été ajoutée à la salle blanche, appelez la procédure suivante.

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Partager avec un consommateur¶

Enfin, ajoutez un consommateur de données à la salle blanche en ajoutant son localisateur de compte Snowflake et ses noms de compte, comme indiqué ci-dessous. Le nom du compte Snowflake doit être de la forme suivante : <ORGANIZATION>.<ACCOUNT_NAME>.

show versions in application package samooha_cleanroom_Provider_Data_Analysis_Demo_clean_room;

call samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
call samooha_By_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, '<CONSUMER_ACCOUNT_NAME>');

Plusieurs localisateurs de comptes de consommateurs peuvent être transmis à la fonction provider.add_consumers sous la forme d’une chaîne séparée par des virgules ou sous la forme d’appels distincts à provider.add_consumers.

Si vous souhaitez voir les consommateurs qui ont été ajoutés à cette salle blanche, appelez la procédure suivante.

call samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Afficher les salles blanches qui ont été récemment créées en suivant la procédure suivante :

call samooha_by_snowflake_local_db.provider.view_cleanrooms();

Afficher plus en détail la salle blanche récemment créée via la procédure suivante.

call samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

Une salle blanche créée peut également être supprimée. La commande suivante supprime entièrement la salle blanche, de sorte que les consommateurs qui avaient auparavant accès à la salle blanche ne pourront plus l’utiliser. Si une salle blanche portant le même nom est souhaitée à l’avenir, elle doit être réinitialisée à l’aide du flux ci-dessus.

call samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Mise en place de l’environnement¶

Exécutez les commandes suivantes pour configurer l’environnement Snowflake avant d’utiliser les APIs du développeur pour travailler avec une Snowflake Data Clean Room. Si vous n’avez pas le rôle SAMOOHA_APP_ROLE, contactez votre administrateur de compte.

use role samooha_app_role;
use warehouse app_wh;

Installer la salle blanche¶

Une fois qu’un partage de salle blanche a été installé, la liste des salles blanches disponibles peut être vue à l’aide de la commande ci-dessous.

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

Attribuez un nom à la salle blanche que le fournisseur vous a partagée.

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

La commande suivante installe la salle blanche sur le compte du consommateur avec le fournisseur associé et la salle blanche sélectionnée.

Cette procédure peut prendre environ 45 secondes.

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

Une fois la salle blanche installée, le fournisseur doit terminer la mise en place de la salle blanche de son côté avant de pouvoir l’utiliser. La fonction ci-dessous vous permet de vérifier le statut de la salle blanche. Une fois qu’elle a été activée, vous devriez être en mesure d’exécuter la commande Run Analysis ci-dessous. Il faut généralement environ une minute pour que la salle blanche soit activée.

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

Effectuer l’analyse¶

Maintenant que la salle blanche est installée, vous pouvez exécuter le modèle d’analyse donné à la salle blanche par le fournisseur à l’aide d’une commande « run_analysis ». Vous pouvez voir comment chaque champ est déterminé dans les sections ci-dessous.

-- Example run analysis procedure with single provider dataset

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,                    -- cleanroom
  'prod_provider_data_analysis',      -- template name

  [],                                 -- consumer tables - this is empty since this template operates only on provider data
  
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],    -- the provider table we want to carry out analysis on

  object_construct(                        -- The keyword arguments needed for the SQL Jinja template
      'dimensions', ['p.STATUS'],          -- Group by column

      'measure_type', ['COUNT'],           -- Aggregate function you want to perform like COUNT, AVG, etc.

      'measure_column', ['p.DAYS_ACTIVE'], -- The column that you want to perform aggregate function on

      'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Acts as a filter to consider only certain records
                                                      -- $$ is used to pass string literals
    )
);

Pour chacune des colonnes auxquelles vous devez faire référence dans le filtrage « where_clause » de l’ensemble de données ou dans les dimensions ou measure_columns, vous pouvez utiliser p. pour faire référence aux champs des tables de fournisseurs et c. pour faire référence aux champs des tables de consommateurs. Utilisez p2, p3, etc., pour plusieurs tables de fournisseurs et c2, c3, etc., pour plusieurs tables de consommateurs.

Remarque : dans ce flux, vous pouvez voir que l’analyse des données du fournisseur est activée dans la salle blanche, ce qui signifie que vous pouvez effectuer des analyses de données sécurisées et privatisées sur les ensembles de données du fournisseur dans la salle blanche. Vous n’avez pas besoin de lier votre ensemble de données. Consultez le flux De bout en bout : analyse de chevauchement pour un exemple où les deux parties peuvent lier des ensembles de données pour une analyse conjointe.

Comment déterminer les entrées de run_analysis ?¶

Pour exécuter l’analyse, vous devez transmettre plusieurs paramètres à la fonction run_analysis. Cette section vous montrera comment déterminer les paramètres à transmettre.

Noms de modèles

Tout d’abord, vous pouvez voir les modèles d’analyse pris en charge en appelant la procédure suivante.

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

Pour exécuter une analyse avec un modèle, vous ne savez pas quels arguments spécifier à ce stade et quels types sont attendus. Vous pouvez donc visualiser le modèle à l’aide de cette fonction, s’il s’agit d’un modèle personnalisé.

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_provider_data_analysis');

Celui-ci peut souvent contenir un grand nombre de paramètres Jinja SQL différents. La fonctionnalité suivante analyse le modèle Jinja SQL et extrait les arguments qui doivent être spécifiés dans run_analysis dans une liste pratique

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_provider_data_analysis');

Noms des ensembles de données

Si vous souhaitez voir les noms des ensembles de données qui ont été ajoutés à la salle blanche par le fournisseur, appelez la procédure suivante. Notez que vous ne pouvez pas voir les données présentes dans les ensembles de données qui ont été ajoutés à la salle blanche par le fournisseur en raison des propriétés de sécurité de la salle blanche.

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

Colonnes de dimensions et de mesures

Lors de l’exécution de l’analyse, il se peut que vous souhaitiez filtrer, grouper et agréger certaines colonnes. Si vous voulez voir la politique de colonnes qui a été ajoutée à la salle blanche par le fournisseur, appelez la procédure suivante.

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Erreurs courantes

Si vous obtenez l’erreur Not approved : unauthorized columns used à la suite de l’analyse de l’exécution, vous voudrez peut-être voir la politique de jointure et la politique de colonnes définies par le fournisseur à nouveau.

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Il est également possible que vous ayez épuisé votre budget de confidentialité et que vous ne puissiez donc plus exécuter de requêtes. Le budget de confidentialité restant peut être vu à l’aide de la commande ci-dessous. Il se réinitialise tous les jours, sinon le fournisseur de la salle blanche peut le réinitialiser.

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

Vous pouvez vérifier si la confidentialité différentielle a été activée pour votre salle blanche en utilisant l’API suivante :

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);