Analyse de base des données exécutées par les consommateurs¶

Mise en place de l’environnement¶

To use the API, you must use a warehouse that SAMOOHA_APP_ROLE has privileges in. app_wh is one of a number of warehouses with access to the API. Choose the warehouse that is appropriate for your needs. (You can also use your own warehouse, if you choose.)

The SAMOOHA_APP_ROLE role is required to access the API.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Créer la salle blanche¶

The next step is to create a new clean room. This is done with a single API call that specifies whether the clean room is for internal or external use. Internal clean rooms can be accessed only by consumers within the same organization; external clean rooms can be used by consumers outside the organization. For both clean room types, consumers must be invited to use the clean room to be able to access it.

Les salles blanches externes déclenchent des contrôles de sécurité supplémentaires lorsque certaines actions sont effectuées. Lorsque cela se produit, vous devez appeler provider.view_cleanroom_scan_status pour voir quand l’analyse de sécurité est terminée, et vous pouvez passer à l’action suivante.

L’exemple suivant crée une salle blanche interne :

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

Lier les données à la salle blanche¶

Both the provider and consumer can link (import) tables, views, and other supported data objects into a clean room. When you link data, the API creates a hidden, secure view inside the clean room that is based on the linked source object. You reference the linked object by its source name, not its internal view name, in all clean room procedures.

Data linked into the clean room can’t be accessed directly by any clean room collaborators. Linked data is accessed using a template imported into the clean room (unless you enable free-form SQL queries on your data).

Before an object can be linked into a clean room, the object must be registered. Registering an object grants proper access privileges to the SAMOOHA_APP_ROLE on the object. You can either register an object directly, or register a parent object (such as a database or schema) to access child objects. You can register an object in either the UI or the API.

Objects are registered at the account level, not the clean room level; you need to register an object only once per account, and it can be linked into any clean room in the account. (You can link only objects registered in your own account.) After you register an object, the object is available for linking by any clean room in the account. Learn more about registration.

L’exemple suivant lie des données dans la table CUSTOMERS de la base de données exemple SAMOOHA_SAMPLE_DATABASE. Cette base de données est enregistrée automatiquement lorsque vous installez l’environnement de salle blanche dans un compte, vous n’avez donc pas besoin de l’enregistrer. Vous pouvez lier ou dissocier des objets à tout moment dans une salle blanche, et les résultats se propagent rapidement à tous les collaborateurs.

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

Définir la politique de jointure¶

If you add a template to the clean room that allows the consumer to join on your data, you should set a clean room join policy on your data. A clean room join policy specifies which columns can be joined on in queries run by collaborators. Your own join policies don’t constrain your own queries.

Clean rooms support a few types of data policies that you can set on linked data. These policies are similar to, but not the same as, the equivalent Snowflake policies, and are applied only on the internal view, not on the source data. Any Snowflake policies that are set on the source data are propagated to the views linked into a clean room. Clean room policies are set on the linked data only, not on the source data.

Vous pouvez définir des politiques uniquement sur les données que vous liez ; vous ne pouvez pas définir de politiques sur les données d’autres personnes.

L’exemple suivant montre comment définir une politique de jointure qui permet à deux colonnes de la table liée d’être jointes :

CALL samooha_by_snowflake_local_db.provider.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
   'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_PHONE']);

En savoir plus sur les politiques de jointure.

Ajouter des modèles à une salle blanche¶

A clean room template is a valid JinjaSQL template that typically evaluates to a SQL query. A template, sometimes called an analysis, can be passed arguments by the caller, and can access any data linked into the clean room. Both providers and consumers can add templates into a clean room and run them.

Snowflake provides a few standard templates, but you will probably write your own custom templates.

Any clean room policies that you set are enforced only if the template includes policy filters in the template, so make sure that the templates you add to a clean room include these filters. For more information about policies, see Comprendre les politiques relatives aux tables de clean room.

Par défaut, seuls les consommateurs peuvent exécuter des modèles. Si un fournisseur veut exécuter un modèle, il doit demander l’autorisation au consommateur. De même, si un consommateur veut télécharger un modèle, il doit demander l’autorisation au fournisseur.

Pour plus d’informations sur la création d’un modèle personnalisé, voir Ajouter des modèles personnalisés à une salle blanche et Référence d’un modèle de salle blanche personnalisé.

L’exemple suivant montre comment ajouter un modèle fourni par Snowflake à la salle blanche :

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['prod_overlap_analysis']);

Définir des politiques de colonnes¶

Les politiques de colonnes de salle blanche spécifient quelles colonnes de vos tables peuvent être projetées dans les requêtes exécutées par les collaborateurs. Une politique de colonnes est liée à la fois à une colonne et à un modèle, de sorte que différentes colonnes peuvent être définies comme projetables avec différents modèles. Un modèle doit être présent dans une salle blanche pour que vous puissiez définir des politiques de colonnes pour ce modèle.

Column policies, like all policies, are overwrite-only; this means that setting column policies completely overwrites any existing column policies set by that account. Both the provider and the consumer can set column policies on their data. Learn more about column policies.

L’exemple suivant montre comment autoriser la projection de quatre colonnes à partir de la base de données exemple des salles blanches qui a été liée précédemment :

CALL samooha_by_snowflake_local_db.provider.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.CUSTOMERS:REGION_CODE']);

Partager avec des consommateurs¶

Only consumers invited by the provider can access the clean room. Consumers can’t share a clean room with other consumers. Designated consumers can’t access the clean room until it is published. Invitations to join a clean room are at the account level, not at the user level.

L’exemple suivant montre comment partager une salle blanche avec deux consommateurs. La procédure utilise deux listes parallèles, délimitées par des virgules, de localisateurs de comptes consommateurs et d’IDs de comptes de partage de données consommateur.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

Définir la version par défaut¶

Les salles blanches sont des applications natives versionnées. Certaines actions, telles que l’ajout de code à une salle blanche, génèrent une nouvelle version corrective de l’application. Les consommateurs doivent installer la salle blanche dans leur compte. La version qu’ils installent est basée sur le numéro de version par défaut que vous spécifiez. Si vous publiez ultérieurement une nouvelle version de la salle blanche et que vous incrémentez le numéro de version par défaut, toutes les versions installées par les consommateurs seront automatiquement mises à jour et les nouvelles installations seront par défaut la nouvelle version. En savoir plus sur la gestion des versions des salles blanches.

L’exemple suivant montre comment définir la version par défaut d’une salle blanche sur V1.0.0, qui est la version initiale d’une salle blanche, si vous n’avez pas importé de code :

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

Publier la salle blanche¶

Publiez ou republiez la salle blanche comme indiqué dans l’exemple suivant. La première fois que cette procédure est appelée, elle rend la salle blanche visible et installable par tous les consommateurs avec lesquels vous l’avez partagée. Vous devez appeler cette procédure chaque fois que vous apportez des modifications importantes, par exemple lorsque vous mettez à jour la version par défaut ou lorsque vous apportez des modifications spécifiques à l’UI de salle blanche.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Le consommateur peut désormais installer la salle blanche, lier des données, définir des politiques et exécuter des modèles, comme décrit ci-dessous.

Mise en place de l’environnement¶

Like the provider, the consumer must use a warehouse that SAMOOHA_APP_ROLE can access. However, unlike the provider, the consumer can either use the SAMOOHA_APP_ROLE role directly for full API access, or a clean room administrator in that account can grant a more limited role that gives privileges to run a subset of the API for consumers. This limited role, sometimes generically called a « run role, » is granted by a user with full clean room privileges. Learn how to grant limited API access.

Un rôle d’exécution ne vous permet pas d’installer une salle blanche, vous devez donc utiliser le rôle SAMOOHA_APP_ROLE, comme le montre l’exemple suivant :

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Installer la salle blanche¶

L’extrait suivant montre comment répertorier toutes les salles blanches qui sont installées et celles que vous êtes invité à installer :

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

Installez la salle blanche que le fournisseur a partagée avec vous, comme indiqué dans l’exemple suivant. Vous devez spécifier le localisateur de compte du fournisseur lorsque vous installez une salle blanche.

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

Ajouter des données et définir des politiques¶

If the clean room templates allow the consumer to include their own data in a query, the consumer registers data, links data, and sets policies like the provider does. Be sure to use the consumer versions of the procedures, as shown in the following example:

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MY_DATABASE.PUBLIC.EXPOSURES'
  ]);

La politique de jointure du fournisseur indique sur quelles colonnes du fournisseur il est possible de joindre des données. Cet exemple montre comment vérifier les colonnes des fournisseurs sur lesquelles vous pouvez joindre d’autres colonnes :

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

A provider needs the consumer’s approval to run a template in the clean room. As a result, most consumers don’t bother setting policies on the tables that they link in. Nevertheless, we recommend that you consider adding policies in case a provider asks to run a template later, because you might forget to add appropriate policies at that time.

If you do set policies, they are enforced only if the template includes a join_policy or column_policy filter to the column in the template, so make sure that the templates you add to a clean room include these filters to enforce your policies. To examine the templates in a clean room, call consumer.view_added_templates. For more information about policies, see Comprendre les politiques relatives aux tables de clean room.

Effectuer l’analyse¶

Avant d’exécuter un modèle, vous l’examinez généralement pour voir ce qu’il fait et quelles variables il accepte, puis vous examinez quelles tables de fournisseurs sont disponibles dans la salle blanche.

-- View the list of templates available in this clean room,
-- and the source code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);