Snowflake Data Clean Rooms : guide de référence pour l’API de consommateur¶
Le contenu suivant détaille toutes les APIs du développeur fournies par Snowflake Data Clean Rooms pour les consommateurs. Toutes les fonctions s’inscrivent dans le schéma suivant :
samooha_by_snowflake_local_db.consumer
Configuration 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, veuillez contacter votre administrateur de compte.
use role samooha_app_role;
use warehouse app_wh;
Attribuez un nom à la salle blanche que le fournisseur vous a communiquée :
set cleanroom_name = 'Test Cleanroom 1';
Installation d’une salle blanche¶
Installez la salle blanche que le fournisseur a partagée via les commandes suivantes :
consumer.install_cleanroom¶
Description : installe la salle blanche sur le compte du consommateur avec le fournisseur associé et la salle blanche sélectionnée.
Arguments : cleanroom_name (string), provider_account_locator (string)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');
consumer.is_enabled¶
Description : Une fois la salle blanche installée, il faut environ 1 minute au fournisseur pour finir de la configurer et l’activer de son côté. Cette fonction permet à l’utilisateur de vérifier le statut de la salle blanche et de voir si elle est activée ou non. L’indicateur passe généralement à True au bout d’une minute environ après l’installation de la salle blanche.
Arguments : cleanroom_name (string)
Retourne : est activé (boolean)
Exemple :
call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
consumer.uninstall_cleanroom¶
Description : désinstalle la salle blanche sur le compte du consommateur. Cette opération supprime toutes les bases de données associées à la salle blanche, y compris la base de données partagée de la salle blanche. Notez que la salle blanche peut toujours être réinstallée avec consumer.install_cleanroom.
Arguments : cleanroom_name (string)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Configuration de l’analyse d’exécution par le fournisseur¶
library.is_provider_run_enabled¶
Description : vérifie si l’analyse de l’exécution du fournisseur est activée dans cette salle blanche. Remarque : une autorisation explicite doit encore être donnée en appelant consumer.enable_templates_for_provider_run (voir ci-dessous).
Arguments : cleanroom_name (string)
Retourne : message activé (string)
Exemple :
call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
library.is_consumer_run_enabled¶
Description : vérifie si l’analyse du cycle du consommateur est activée dans cette salle blanche. Cet indicateur détermine si le consommateur de la salle blanche (l’installateur) peut effectuer des analyses, ou agir en tant que fournisseur de données dans le cadre de la collaboration.
Arguments : cleanroom_name (string)
Retourne : message activé (string)
Exemple :
call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
consumer.enable_templates_for_provider_run¶
Description : si, dans une salle blanche, l’analyse de l’exécution par le fournisseur est activée (c’est-à-dire que le fournisseur de la salle blanche a marqué la salle blanche pour permettre aux fournisseurs d’effectuer des analyses), cette procédure doit être appelée par le consommateur pour les activer. Cette procédure est nécessaire pour donner une approbation explicite, modèle par modèle, aux fournisseurs qui souhaitent effectuer des analyses.
Le dernier paramètre booléen permet au consommateur d’activer la confidentialité différentielle pour les analyses du fournisseur, s’il est défini sur TRUE.
Arguments :
cleanroom_name (string) - Le nom de la salle blanche.
template_names (array of strings) - Un tableau d’un ou plusieurs modèles dans la salle blanche qui devraient être activés pour l’analyse du fournisseur
enable_differential_privacy(boolean) - Si TRUE, active la confidentialité différentielle pour tous les modèles listés dans
template_names
. La confidentialité différentielle ne peut être activée pour ces modèles que si elle est activée pour la salle blanche elle-même. Vous pouvez vérifier le statut de confidentialité différentielle pour une salle blanche en appelantconsumer.is_dp_enabled
.
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
Enregistrer et annuler l’enregistrement des données¶
Utilisez la commande suivante pour enregistrer et annuler l’enregistrement des bases de données, des schémas et des objets. Les tables et les vues doivent être enregistrées avant de pouvoir être liées à la salle blanche. Si vous enregistrez une base de données ou un schéma, tous les objets de cette base de données ou de ce schéma sont enregistrés.
consumer.register_db¶
Description : l’ajout d’une base de données dans la salle blanche vous permet de lier n’importe quel ensemble de données de la base. Si ce n’est pas le cas, les autorisations devront être accordées à samooha_app_role individuellement.
Arguments : db_name (string)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
library.register_schema¶
Description : similaire à register_db
, mais opère au niveau d’un schéma. Une table ou une chaîne représentant le nom pleinement qualifié du schéma peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier les objets au schéma à la salle blanche.
Si vous souhaitez enregistrer un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.register_managed_access_schema
plutôt.
Arguments : schema_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.register_managed_access_schema¶
Description : similaire à register_schema
, mais enregistre un schéma qui a été créé avec le paramètre WITH MANAGED ACCESS. Une table ou une chaîne représentant le nom pleinement qualifié du schéma peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier les objets au schéma à la salle blanche.
Arguments : schema_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.register_objects¶
Description : Accorde l’accès en salle blanche aux tables et aux vues de tous types, les rendant ainsi disponibles pour les lier dans la salle blanche via l’appel à consumer.link_datasets
. Vous pouvez enregistrer des groupes d’objets plus larges en appelant library.register_schema
, library.register_managed_access_schema
ou consumer.register_db
.
Arguments :
object_names (array) - Tableau de noms d’objets entièrement qualifiés. Ces objets peuvent ensuite être reliés à la salle blanche.
Retourne : message de réussite (string)
Exemples
Pour enregistrer une table et une vue :
call samooha_by_snowflake_local_db.library.register_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
library.register_table_ou_vue – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.register_objects.
Description : enregistre les tables et les vues de tous types.
Arguments : object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)
Sortie : message de réussite (string)
Exemples
Pour enregistrer une table :
call samooha_by_snowflake_local_db.library.register_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
false,
false,
false);
Pour enregistrer une table Iceberg :
call samooha_by_snowflake_local_db.library.register_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
true,
false,
false);
library.register_table – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.register_objects.
Description : similaire à register_db
, mais opère au niveau d’une table. Une table ou une chaîne représentant le nom pleinement qualifié de la table peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier la table à la salle blanche.
Si vous souhaitez enregistrer des tables dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.register_managed_access_table
plutôt.
Arguments : table_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_managed_access_table – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.register_objects.
Description : similaire à register_table
, mais enregistre les tables dans un schéma qui a été créé avec le paramètre WITH MANAGED ACCESS. Une table ou une chaîne représentant le nom pleinement qualifié de la table peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier la table à la salle blanche.
Arguments : table_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_view – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.register_objects.
Description : similaire à register_db
, mais opère au niveau d’un vue. Un tableau ou une chaîne représentant le nom pleinement qualifié de la vue peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier la vue à la salle blanche.
Si vous souhaitez enregistrer des vues dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.register_managed_access_view
plutôt.
Arguments : view_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.register_managed_access_view – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.register_objects.
Description : similaire à register_view
, mais enregistre les vues dans un schéma qui a été créé avec le paramètre WITH MANAGED ACCESS. Un tableau ou une chaîne représentant le nom pleinement qualifié de la vue peut être transmis, et des sélections d’attributions au rôle SAMOOHA_APP_ROLE sont effectuées, permettant à l’utilisateur de lier la vue à la salle blanche.
Arguments : view_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_db¶
Description : annule la procédure register_db
et supprime les autorisations au niveau de la base de données accordées au rôle SAMOOHA_APP_ROLE et à l’application native Snowflake Data Clean Room. Cette opération supprime également toute base de données de l’élément déroulant d’UI.
Arguments : db_name (string)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
library.unregister_schema¶
Description : annule l’enregistrement d’un schéma, ce qui empêche les utilisateurs de lier leurs tables et vues à la salle blanche.
Si vous souhaitez annuler l’enregistrement d’un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.unregister_managed_access_schema
plutôt.
Arguments : schema_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.unregister_managed_access_schema¶
Description : similaire à unregister_schema
, mais annule l’enregistrement d’un schéma qui a été créé avec le paramètre WITH MANAGED ACCESS.
Arguments : schema_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
library.unregister_objects¶
Description : Révoque l’accès en salle blanche aux tables et vues de tous types. Les objets ne seront plus disponibles pour les utilisateurs dans les salles blanches gérées par ce compte.
Arguments :
object_names (array) - Tableau de noms d’objets pleinement qualifiés pour lesquels l’accès doit être révoqué.
Retourne : message de réussite (string)
Exemples
Pour annuler l’enregistrement d’une table et d’une vue :
call samooha_by_snowflake_local_db.library.unregister_objects(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
library.unregister_table_or_view – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.unregister_objects.
Description : annule l’enregistrement des tables et des vues de tous types.
Arguments : object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)
Sortie : message de réussite (string)
Exemples
Pour annuler l’enregistrement d’une table :
call samooha_by_snowflake_local_db.library.unregister_table_or_view(
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
false,
false,
false,
false);
library.unregister_table – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.unregister_objects
Description : similaire à unregister_db
, mais opère au niveau d’une table. Un tableau ou une chaîne représentant le nom de table complet peut être transmis pour annuler l’enregistrement des tables. Les utilisateurs ne peuvent pas lier des tables non enregistrées à une salle blanche.
Si vous souhaitez annuler l’enregistrement des tables dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.unregister_managed_access_table
plutôt.
Arguments : table_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_managed_access_table – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.unregister_objects
Description : similaire à unregister_table
, mais annule l’enregistrement des tables dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS).
Arguments : table_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_view – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.unregister_objects
Description : similaire à unregister_db
, mais opère au niveau d’un vue. Un tableau ou une chaîne représentant le nom de vue complet peut être transmis pour annuler l’enregistrement des vues. Les utilisateurs ne peuvent pas lier des vues non enregistrées à une salle blanche.
Si vous souhaitez annuler l’enregistrement des vues dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS), utilisez library.unregister_managed_access_view
plutôt.
Arguments : view_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
library.unregister_managed_access_view – Obsolète¶
Attention
Cette commande est désormais obsolète. Utilisez library.unregister_objects
Description : similaire à unregister_view
, mais annule l’enregistrement des vues dans un schéma d’accès géré (c’est-à-dire un schéma créé avec le paramètre WITH MANAGED ACCESS).
Arguments : view_name (array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Lier et dissocier des ensembles de données¶
Une fois qu’un ensemble de données a été enregistré, vous pouvez lier des tables ou des vues de cet ensemble de données à une salle blanche spécifique. Vous pouvez également dissocier une table ou une vue d’une salle blanche spécifique pour supprimer l’accès à ces données depuis la salle blanche.
consumer.link_datasets¶
Description : Lier une table ou une vue à la salle blanche, en donnant aux modèles de cette salle blanche l’accès à la table, selon les politiques de jointure et de colonne que vous spécifiez.
Arguments :
cleanroom_name (string) - Nom de la salle blanche à laquelle l’accès doit être accordé
tables_list (array of strings) - Liste des noms de tables ou de vues entièrement qualifiés à exposer à la salle blanche. Ces objets doivent d’abord être enregistrés (mis à la disposition de l’environnement de la salle blanche) avec la méthode d’enregistrement.
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.unlink_datasets¶
Description : Supprime l’accès aux tables ou vues spécifiées dans la salle blanche spécifiée pour tous les utilisateurs. Cela ne fonctionne que pour les données fournies par les consommateurs.
Arguments :
cleanroom_name (string) - Nom de la salle blanche dont l’accès doit être supprimé.
tables_list (array of strings) - Liste des noms de tables ou de vues entièrement qualifiés dont l’accès doit être bloqué.
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.unlink_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.view_consumer_datasets¶
Description : Voir toutes les tables et vues liées à la salle blanche spécifiée par n’importe quel consommateur de ce compte.
Arguments :
cleanroom_name (string) - Nom de la salle blanche.
Retourne : Table des objets liés à la salle blanche spécifiée, ainsi que le nom de la vue interne de la salle blanche pour chaque objet.
Exemple :
call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);
Analyse exécutée par le fournisseur¶
consumer.set_join_policy¶
Description : spécifie les colonnes sur lesquelles le fournisseur est autorisé à effectuer une jointure lors de l’exécution de modèles dans la salle blanche, lors de l’utilisation de l’analyse d’exécution du fournisseur. Notez que la politique de colonne est replace only, donc si la fonction est appelée à nouveau, la politique de colonne précédemment définie est complètement remplacée par la politique actuelle.
Notez que les contrôles sont effectués en analysant la requête SQL à exécuter sur les données pour toute colonne non autorisée. Les requêtes comportant des caractères génériques peuvent ne pas être détectées par ces contrôles, et il convient de faire preuve de discernement lors de la conception du modèle d’analyse.
Arguments : cleanroom_name(string), table_and_col_names(array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);
consumer.set_column_policy¶
Description : définit les colonnes des données sur lesquelles le fournisseur peut effectuer des opérations. Cette fonction ne doit être appelée qu’après l’ajout du modèle. Il s’agit également d’une fonction du modèle, de sorte que les entrées doivent être de la forme template_name:full_table_name:column_name. Notez que la politique de colonne est replace only, donc si la fonction est rappelée, la politique de colonne précédemment définie est complètement remplacée par la politique actuelle.
La politique de colonne ne doit pas être appliquée aux colonnes d’identité telles que l’adresse e-mail. Elle ne doit être utilisée que pour les colonnes d’agrégats et de groupes.
Notez que les contrôles sont effectués en analysant la requête SQL à exécuter sur les données pour toute colonne non autorisée. Les requêtes comportant des caractères génériques peuvent ne pas être détectées par ces contrôles, et il convient de faire preuve de discernement lors de la conception du modèle d’analyse.
Les vérifications sont effectuées sur des arguments SQL Jinja appelés dimensions ou measure_columns. Veillez à utiliser ces balises pour activer cette vérification.
Arguments : cleanroom_name(string), analysis_and_table_and_columns(array)
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:CAMPAIGN']);
Modèles¶
Les commandes suivantes permettent aux utilisateurs de travailler avec les modèles disponibles dans la salle blanche.
consumer.view_template_definition¶
Description : les définitions du modèle de salle blanche sont disponibles pour aider à déterminer quels paramètres doivent être transmis au modèle.
Note
Notez que toutes les procédures de Samooha sont chiffrées et ne sont pas visibles par défaut. Cependant, tous les modèles personnalisés que vous ajoutez vous seront visibles.
Arguments : cleanroom_name (string), template_name (string)
Retourne : La définition du modèle (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');
consumer.get_arguments_from_template¶
Description : définit la manière dont les données doivent être organisées et les données requises pour chaque modèle afin de garantir que le résultat est facilement assimilable.
Arguments : cleanroom_name (string), template_name (string)
Retourne : Liste d’arguments et spécification (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');
Chaînes de modèles¶
Les commandes suivantes permettent aux utilisateurs de travailler avec les chaînes de modèles disponibles dans la salle blanche. Pour des informations générales sur l’utilisation des chaînes de modèles, voir Utilisation des APIs du développeur pour exécuter les modèles de manière séquentielle.
consumer.view_added_template_chains¶
Description : permet de voir les chaînes de modèles actuellement actives dans la salle blanche.
Arguments : cleanroom_name (string)
Renvoie : Les chaînes de modèles ajoutées (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);
consumer.view_template_chain_definition¶
Description : renvoie les attributs d’une chaîne de modèles.
Arguments : cleanroom_name (string), template_chain_name (string)
Renvoie : Définition de la chaîne de modèles (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');
consumer.get_arguments_from_template_chain¶
Description : renvoie les arguments attendus pour tous les modèles de la chaîne de modèles.
Arguments : cleanroom_name (string), template__chain_name (string)
Retourne : Liste d’arguments et spécification (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.get_arguments_from_template_chain($cleanroom_name, 'insights_chain');
Exécuter des analyses¶
Les commandes suivantes exécutent une analyse ou une activation spécifique en fonction du modèle spécifié.
consumer.run_analysis¶
Description : Exécute une analyse à l’aide d’un modèle ou d’une chaîne de modèles et renvoie la table des résultats.
Si la confidentialité différentielle est activée, la requête peut échouer si vous avez atteint votre limite budgétaire pour ce modèle.
Arguments :
cleanroom_name (string) - Nom de la salle blanche dans laquelle le modèle doit être exécuté.
template_name (string) - Nom du modèle ou de la chaîne de modèles à exécuter dans la salle blanche.
consumer_tables (array of string) - Tableau de noms de tables de consommateurs entièrement qualifiés. Ces valeurs sont affectées à la variable de modèle
my_table
. Ces tables doivent déjà être liées à la salle blanche. Pour connaître les tables disponibles, appelezconsumer.view_consumer_datasets
. Par exemple, si vous transmettez [“mytable1”, “mytable2”, “mytable3”], le modèle peut accéder à ces valeurs en tant que{{my_table[0]}}
,{{my_table[1]}}
et{{my_table[2]}}
respectivement.provider_tables (array of string) - Tableau de noms de tables de fournisseurs entièrement qualifiés. Ces valeurs sont affectées à la variable de modèle
source_table
. Ces tables doivent déjà être liées à la salle blanche. Pour connaître les tables disponibles, appelezconsumer.view_provider_datasets
. Par exemple, si vous transmettez [“sourcetable1”, “sourcetable2”, “sourcetable3”], le modèle peut accéder à ces valeurs en tant que{{source_table[0]}}
,{{source_table[1]}}
et{{source_table[2]}}
respectivement.analysis_arguments (objet) - Un objet contenant des paires de clés/valeurs transmises au modèle. Le modèle peut accéder à la variable par le nom de clé. Si vous indiquez
{'age': 20}
, le modèle accède à la valeur sous la forme{{age}}
. Transmettez un objet vide si aucune valeur n’est requise. Pour voir quelles valeurs sont nécessaires, examinez le modèle en question en appelantconsumer.view_template_definition
. Cet objet a une valeur réservée facultative :epsilon
(flottant, facultatif) - Spécifie la valeur epsilon pour la confidentialité différentielle, si la confidentialité différentielle est activée pour cette salle blanche. La valeur par défaut est 0.1.
use_cache (booléen, facultatif) - Utilisation ou non des résultats mis en cache pour la même requête. La valeur par défaut est TRUE. L’ensemble est défini sur FALSE lorsque vous testez et modifiez un modèle afin de garantir que la requête est réexécutée en utilisant la dernière version du modèle à chaque fois.
Retourne : (Table) Résultats de la requête.
Exemple :
call samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
'prod_overlap_analysis',
['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'], -- Consumer tables
['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'], -- Provider tables
object_construct(
'max_age', 30
)
);
Activation¶
Pour plus d’informations sur l’activation des résultats, voir Utilisation des APIs de développement pour envoyer des résultats à un compte Snowflake en vue de leur activation.
consumer.set_activation_policy¶
Description : Définit les colonnes qui peuvent être utilisées dans les modèles d’activation. Cela garantit que seules les colonnes approuvées par le consommateur peuvent être utilisées avec le modèle d’activation.
Entrée : cleanroom_name (string), columns (array)
L’argument columns est passée au format <template_name>:<fully_qualified_table_name>:<column_name>
.
Sortie : Success message
Exemple :
call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
consumer.approve_provider_activation_consent¶
Description : Approuve la requête du fournisseur pour autoriser l’activation du fournisseur, c’est-à-dire la possibilité de pousser les résultats vers le compte Snowflake du fournisseur. Suppose que le fournisseur a déjà appelé provider.request_provider_activation_consent
pour demander une autorisation.
Entrée : cleanroom_name (string), activation_template_name (string)
Sortie : Success message
Exemple :
call consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');
consumer.run_activation¶
Description : Exécute un modèle qui renvoie les résultats vers un compte Snowflake pour activation.
Arguments : cleanroom_name (string), segment_name (string), template_name (string), consumer_tables (array), provider_tables (array), activation_arguments (object), consumer_direct_activation (boolean), application_id (string)
Si le consommateur transmet les résultats à son propre compte Snowflake en vue de leur activation, définissez l’argument consumer_direct_activation sur TRUE
.
Passez une chaîne vide comme argument à application_id.
Renvoie : Message de réussite
Exemple :
call samooha_by_snowflake_local_db.consumer.run_activation(
$cleanroom_name,
'my_activation_segment',
'activation_custom_template',
['consumer_source_table'],
['provider_source_table'],
object_construct( -- Custom arguments needed for the template
'dimensions', ['p.CAMPAIGN'], -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
'where_clause', 'p.EMAIL=c.EMAIL'
));
Modèles définis par le consommateur¶
Les APIs suivantes vous permettent d’ajouter des modèles définis par le consommateur à une salle blanche. Pour plus d’informations, voir Utilisation des API du développeur pour ajouter des modèles définis par le consommateur.
consumer.create_template_request¶
Description : envoie une requête au fournisseur d’une salle blanche lui demandant d’approuver un modèle personnalisé afin qu’il puisse être ajouté à la salle blanche.
Arguments : cleanroom_name (string), template_name (string), template_definition (string)
Retourne : message de réussite (string)
Exemple :
CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom',
'my_analysis',
$$
SELECT
identifier({{ dimensions[0] | column_policy }})
FROM
identifier({{ my_table[0] }}) c
INNER JOIN
identifier({{ source_table[0] }}) p
ON
c.identifier({{ consumer_id }}) = identifier({{ provider_id | join_policy }})
{% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
$$);
consumer.generate_python_request_template¶
Description : Génère un modèle de salle blanche consommateur qui inclut du code Python personnalisé. Le modèle généré comprend votre code Python et un espace réservé pour votre modèle JinjaSQL. Transmettez votre modèle final à consumer.list_template_requests
.
En savoir plus sur les modèles définis par les consommateurs
Arguments :
function_name (string) - Le nom de la fonction Python que votre modèle SQL doit appeler pour exécuter votre fonction.
arguments (array of string) - Liste des arguments pour votre fonction Python, où chaque argument est une chaîne délimitée par des espaces au format « <argument_name> <argument_type> ». Par exemple :
['data variant', 'scale integer']
.packages (array of string) - Tableau des noms de paquets nécessaires à votre code Python. S’il n’y en a pas, spécifiez un tableau vide. Exemple :
['pandas','numpy']
.imports (array of strings) - Toutes les bibliothèques Python personnalisées requises pour le code Python. Doit être un tableau de zéros ou plusieurs adresses de zone de préparation. Exemple :
['@db.schema.stage/my_python_sproc.py']
rettype (string) - Le type de retour SQL de votre fonction. Exemples :
'integer'
,'varchar'
.handler (string) - Le nom de la fonction gestionnaire principale dans votre code Python. Il s’agit généralement de
'main'
.code (string) - Votre implémentation du code Python. Si vous incluez une importation et que votre gestionnaire désigné est défini dans une importation, il peut s’agir d’une chaîne vide.
Retourne : Modèle python généré (string). Remplacez l’espace réservé par votre code SQL.
Exemple :
Appelez la fonction d’aide avec un exemple Python trivial.
call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
'my_func', // SQL should use this name to call your function
['data variant', 'index integer'], // Arguments and types for the function
['pandas', 'numpy'], // Standard libraries used
[], // No custom libraries needed.
'integer', // Return type integer
'main', // Standard main handler
// Python implementation as UDF
$$
import pandas as pd
import numpy as np
def main(data, index):
df = pd.DataFrame(data) # you can do something with df but this is just an example
return np.random.randint(1, 100)
$$
);
Voici la réponse à l’appel précédent. Insérez votre JinjaSQL comme indiqué dans l’espace réservé, et passez-le dans consumer.create_template_request
.
BEGIN
-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')
HANDLER = 'main'
AS '
import pandas as pd
import numpy as np
def main(data, index):
df = pd.DataFrame(data) # you can do something with df but this is just an example
return np.random.randint(1, 100)
';
-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';
-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);
END;
consumer.list_template_requests¶
Description : répertorie les requêtes effectuées par le consommateur pour ajouter un modèle à une salle blanche.
Arguments : cleanroom_name (string)
Renvoie : request_id(string), provider_identifier(string), template_name(string), template_definition(string), request_status(string), reason(string)
Exemple :
CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');
Méthodes d’obtention des métadonnées de la salle blanche¶
Les méthodes suivantes montrent les propriétés pertinentes de la salle blanche :
consumer.describe_cleanroom¶
Description : crée un résumé textuel contenant toutes les informations sur ce qui a été ajouté à la salle blanche, y compris les modèles, les ensembles de données, les politiques, etc.
Arguments : cleanroom_name(string)
Retourne : Chaîne de description extensive de la salle blanche (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
consumer.view_provider_datasets¶
Description : permet de voir tous les ensembles de données qui ont été ajoutés à la salle blanche par le fournisseur.
Arguments : cleanroom_name(string)
Retourne : Tous les noms des jeux de données des fournisseurs dans cleanroom (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
consumer.view_join_policy¶
Description : décrit les colonnes que les utilisateurs peuvent rejoindre en toute sécurité à l’intérieur d’une salle blanche, définies par le consommateur sur les ensembles de données des consommateurs.
Arguments : cleanroom_name (string)
Retourne : La politique de jointure (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
consumer.view_provider_join_policy¶
Description : décrit les colonnes que les utilisateurs peuvent rejoindre en toute sécurité à l’intérieur d’une salle blanche, définies par le fournisseur sur les ensembles de données du fournisseur.
Arguments : cleanroom_name (string)
Retourne : La politique de jointure (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
consumer.view_added_templates¶
Description : permet de voir tous les modèles actifs dans la salle blanche.
Arguments : cleanroom_name (string)
Retourne : Les modèles ajoutés (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
consumer.view_column_policy¶
Description : donne une vue de toutes les politiques de colonne qui ont été appliquées à la salle blanche par le consommateur.
Arguments : cleanroom_name (string)
Retourne : La politique de la colonne (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
consumer.view_provider_column_policy¶
Description : permet de voir toutes les politiques de colonne qui ont été appliquées à la salle blanche par le fournisseur.
Arguments : cleanroom_name (string)
Retourne : La politique de la colonne (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
consumer.view_cleanrooms¶
Description : Affiche toutes les salles blanches jointes (installées) ou joignables par ce compte. Les salles blanches qui ont échoué ne sont pas représentées. Dans la table des résultats :
IS_ALREADY_INSTALLED : True si la salle blanche est rejointe (onglet Joined dans l’application Web), False si vous avez été invité à rejoindre la salle blanche mais que vous ne l’avez pas rejointe (onglet Invited dans l’application Web).
Problème connu - Cette méthode peut parfois ne pas afficher les salles blanches désinstallées. Si vous savez qu’une salle blanche a été partagée avec vous mais qu’elle n’apparaît pas dans la liste, appelez
consumer.describe_cleanroom
pour voir si cette salle blanche est disponible pour être rejointe.
Arguments : Aucun
Retourne : Toutes les salles blanches existantes classées par date de création (table)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_cleanrooms();
-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Confidentialité différentielle¶
Ces commandes permettent de contrôler la confidentialité différentielle dans la salle blanche. Vous pouvez également spécifier la confidentialité différentielle au niveau du modèle lorsque vous appelez consumer.enable_templates_for_provider_run
.
En savoir plus sur la gestion de la confidentialité différentielle.
consumer.is_dp_enabled¶
Description : vérifie si la confidentialité différentielle a été activée dans la salle blanche.
Arguments : cleanroom_name(string)
Retourne : Indique si DP est activé pour la salle blanche (boolean)
Exemple :
call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
consumer.view_remaining_privacy_budget¶
Description : visualise le budget de confidentialité restant qui peut être utilisé pour effectuer des requêtes à partir de la salle blanche. Une fois le budget épuisé, d’autres appels à run_analysis ne seront pas autorisés jusqu’à ce que le budget soit réinitialisé. Le budget est réinitialisé quotidiennement.
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Arguments : cleanroom_name (string)
Retourne : Le budget restant pour la protection de la confidentialité (flottant)
Exemple :
call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Méthodes d’aide générales¶
Utilisez les méthodes suivantes pour faciliter la fonctionnalité générale de la salle blanche.
consumer.set_cleanroom_ui_accessibility¶
Description : Affiche ou cache les salles blanches dans l’application Web pour les consommateurs du compte courant.
Arguments :
cleanroom_name(string) - Le nom de la salle blanche.
visibility_status(string) - Une des valeurs suivantes, sensible à la casse :
HIDDEN - Cache la salle blanche spécifiée dans l’application Web à tous les utilisateurs du compte consommateur actuel. La salle blanche restera accessible via des appels API.
EDITABLE - Rend la salle blanche visible dans l’application Web.
Retourne : message de réussite (string)
Exemple :
call samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
library.enable_local_db_auto_upgrades¶
Description : active la tâche, samooha_by_snowflake_local_db.admin.expected_version_task
, qui met automatiquement à niveau la Snowflake Native App pour Snowflake Data Clean Rooms à mesure que de nouvelles versions sont publiées.
Arguments : Aucun
Retourne : message de réussite (string)
Exemple :
CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
library.disable_local_db_auto_upgrades¶
Description : désactive la tâche, samooha_by_snowflake_local_db.admin.expected_version_task
, qui met automatiquement à niveau la Snowflake Native App pour Snowflake Data Clean Rooms à mesure que de nouvelles versions sont publiées.
Arguments : Aucun
Retourne : message de réussite (string)
Exemple :
CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();