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
Copy

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;
Copy

Attribuez un nom à la salle blanche que le fournisseur vous a communiquée :

set cleanroom_name = 'Test Cleanroom 1';
Copy

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>');
Copy

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);
Copy

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);
Copy

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)
Copy

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)
Copy

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 appelant consumer.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);
Copy

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');
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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);
Copy

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);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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');
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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']);
Copy

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');
Copy

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');
Copy

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);
Copy

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');
Copy

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');
Copy

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, appelez consumer.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, appelez consumer.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 appelant consumer.view_template_definition. Cet objet a une valeur réservée facultative :

  • 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
  )
);
Copy

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' ]);
Copy

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'
  ));
Copy

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 %};
  $$);
Copy

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)
    $$
);
Copy

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;
Copy

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');
Copy

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);
Copy

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);
Copy

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);
Copy

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);
Copy

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);
Copy

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);
Copy

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);
Copy

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;
Copy

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);
Copy

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);
Copy

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');
Copy

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();
Copy

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();
Copy