Utiliser Snowflake Collaboration Data Clean Rooms

Cette rubrique fournit un guide détaillé de l’utilisation des salles blanches de données de collaboration. Il fournit également des détails sur toutes les étapes clés nécessaires pour créer ou participer à une collaboration.

Exigences

  • Vous devez disposer de la dernière version de Snowflake Data Clean Rooms.

  • Les propriétaires et les fournisseurs de données doivent utiliser Snowflake Enterprise Edition. Les gestionnaires d’analyses peuvent utiliser la Standard Edition.

  • Vous avez besoin d’accéder à l’API Data Clean Rooms Collaboration pour pouvoir voir ou gérer les collaborations. Pour plus d’informations, voir Gérer l’accès à l’API de collaboration DCR.

  • Vous devez désactiver les rôles secondaires dans votre environnement lorsque vous utilisez l’API de collaboration :

    USE SECONDARY ROLES NONE;
    Copy

Workflow de collaboration de base dans les salles blanches

Voici un scénario simple de collaboration en salle blanche :

  1. Le propriétaire de la collaboration enregistre éventuellement les modèles ou les offres de données qu’il souhaite voir apparaître dans la configuration initiale de la collaboration.

  2. Le propriétaire demande éventuellement à tous les collaborateurs prévus d’enregistrer les modèles ou les offres de données qu’ils souhaitent voir apparaître dans la configuration initiale de la collaboration. Les collaborateurs donnent alors les IDs de ressource de tous les éléments qu’ils ont enregistrés.

  3. Ensuite, le propriétaire crée une collaboration. La collaboration est définie par une spécification YAML qui répertorie les collaborateurs, leurs rôles et toutes les ressources qui doivent être présentes dans la version initiale de la collaboration.

    • Lorsqu’une collaboration est créée, l’ensemble des collaborateurs et de leurs rôles est fixe : seuls les collaborateurs ayant un rôle dans la définition de la collaboration sont invités à participer. De même, l’ensemble des gestionnaires d’analyses est fixe. Toutefois, tout collaborateur peut également devenir un fournisseur de données en intégrant de nouvelles données dans la collaboration.

    • Si votre collaboration inclut des utilisateurs dans d’autres régions d’hébergement Cloud, ils doivent activer l’exécution automatique inter-Cloud sur leur compte avant de pouvoir examiner et rejoindre la collaboration.

  4. Le propriétaire rejoint la collaboration qu’il a créée, ce qui rend la collaboration active. La collaboration est désormais visible et accessible à tous les collaborateurs mentionnés dans les spécifications.

  5. Les collaborateurs examinent et rejoignent la collaboration.

  6. Les collaborateurs peuvent alors éventuellement ajouter des ressources à la collaboration, comme des modèles, et, s’il s’agit d’un fournisseur de données, des offres de données.

  7. Les gestionnaires d’analyses peuvent alors exécuter tous les modèles qui leur sont attribués dans la collaboration, en utilisant toutes les données disponibles pour eux dans la collaboration (et éventuellement des données locales non partagées). Le gestionnaire d’analyses prend en charge le coût de l’analyse. Les modèles peuvent soit renvoyer les résultats de la requête dans la réponse, soit activer les résultats pour l’appelant ou un autre collaborateur.

Les sections suivantes décrivent les détails de chacune de ces étapes.

Créer une collaboration

Pour créer une collaboration, vous concevez une spécification de collaboration qui définit l’ensemble des collaborateurs et leurs rôles. Le propriétaire de la collaboration peut éventuellement enregistrer et lier toutes les autres ressources qu’il souhaite mettre à disposition dans la collaboration initiale, et inclure ces ressources dans la spécification de collaboration. Si le propriétaire prévoit d’utiliser des ressources provenant de collaborateurs, il peut également inviter ces utilisateurs à enregistrer leurs ressources et à donner au propriétaire les IDs de ressources à inclure dans la spécification de collaboration.

Le propriétaire appelle alors INITIALIZE pour commencer à créer la collaboration. Il s’agit d’un processus asynchrone ; il doit donc appeler GET_STATUS jusqu’à ce que le statut soit CREATED.

Le propriétaire doit ensuite rejoindre sa collaboration en appelant JOIN. La jointure est également un processus asynchrone, le propriétaire doit donc appeler GET_STATUS pour suivre la progression de la jointure. Lorsque le statut de la collaboration est JOINED, la collaboration sera active et tous les collaborateurs peuvent voir et rejoindre la collaboration. Tant que le propriétaire n’a pas rejoint la collaboration, aucun collaborateur ne peut voir ou rejoindre la collaboration.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
$$
api_version: 2.0.0
spec_type: collaboration
name: my_first_collaboration
owner: alice
collaborator_identifier_aliases:
  alice: example_com.acct_abc
  bob: another_example.acct_xyz
analysis_runners:
  bob:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
  alice:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
    templates: []
$$
);
SET collaboration_name = '<collaboration_name>';

-- Creating a collaboration is asynchronous. Check to see when collaboration is CREATED.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Collaboration is visible here when it's created.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();

-- Join the collaboration you created.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.JOIN($collaboration_name);

-- Joining a collaboration is asynchronous. Call get_status until the status is JOINED.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);
Copy

Ajouter des ressources à une collaboration

Tout collaborateur peut ajouter des ressources à une collaboration ou supprimer les ressources qu’il a ajoutées à la collaboration. L’ajout d’une ressource à un groupe de collaboration comporte deux étapes :

  1. Le propriétaire de la ressource crée une spécification de définition des ressources pour la ressource et l’utilise pour enregistrer la ressource dans son compte. Vous pouvez enregistrer la ressource dans le registre par défaut de votre compte, ou utiliser un registre personnalisé.

  2. Un collaborateur lie la ressource à une collaboration. Une fois que la ressource est liée, elle peut être utilisée par les collaborateurs désignés. Certains types de ressources, tels que les modèles, peuvent être liés par n’importe quel collaborateur ; d’autres ressources, telles que les offres de données, ne peuvent être liées que par des utilisateurs ayant un rôle de fournisseur de données. Les ressources ne sont généralement disponibles que pour des collaborateurs spécifiques tels que définis par la spécification de collaboration et le partage de ressources.

Les ressources peuvent être ajoutées à une collaboration avant ou après la création de la collaboration.

Les ressources prennent en charge la gestion des versions ; cependant, la création d’une nouvelle ressource avec une nouvelle version ne supprime pas la version précédente de la collaboration.

Les ressources sont nommées de manière unique en combinant le nom et la version fournis par l’utilisateur (et l’alias, pour les offres de données).

Vous pouvez ajouter les ressources suivantes à une collaboration :

Modèles

Les modèles sont des modèles de salle blanche JinjaSQL pouvant être exécutés par des collaborateurs spécifiés. Tout collaborateur peut enregistrer et ajouter un modèle à une collaboration, à condition que tous les collaborateurs concernés approuvent la demande, comme décrit dans les étapes suivantes. Vous pouvez uniquement ajouter ou supprimer les modèles enregistrés sur votre compte.

Pour ajouter un modèle à une collaboration :

  1. Concevez un modèle pour la collaboration et intégrez-le dans une spécification du modèle.

  2. Enregistrez le modèle en appelant REGISTRY.REGISTER_TEMPLATE. Cela renvoie un ID de modèle.

  3. Lier le modèle Le processus dépend de l’existence ou non de la collaboration :

    • Pour ajouter un modèle avant la création de la collaboration, indiquez l’ID de modèle au propriétaire de la collaboration, qui l’ajoute à la spécification de collaboration, définissant qui peut l’exécuter.

       alice:
   data_providers:
     bob:
       data_offerings: []
   templates:
   - id: bob_template_v1 # Alice can run this template, seemingly registered by bob.
      Copy

    • Pour ajouter un modèle à une collaboration existante, vous devez demander l’autorisation à tous les collaborateurs concernés par le modèle. Procédez comme suit pour ajouter un modèle à une collaboration existante :

      1. Appelez REGISTER_TEMPLATE pour enregistrer le modèle dans votre compte, ce qui le rend disponible pour l’ajouter aux collaborations.

      2. Appelez ADD_TEMPLATE_REQUEST avec l’ID de modèle pour démarrer le flux d’approbation afin d’ajouter le modèle à une collaboration spécifique, pour des utilisateurs spécifiques.

        Tous les collaborateurs concernés par la ressource voient la demande lorsqu’ils appellent VIEW_UPDATE_REQUESTS.

      3. Les collaborateurs qui voient la demande avec le statut PENDING doivent appeler APPROVE_UPDATE_REQUEST ou REJECT_UPDATE_REQUEST.

        • Si un collaborateur rejette la demande, la demande de mise à jour est rejetée.

        • Les collaborateurs ne peuvent pas modifier ultérieurement une approbation en un rejet, ni un rejet en une approbation.

        Lorsque le statut de la demande est APPROVED, le modèle est disponible pour les utilisateurs spécifiés dans la demande d’ajout de modèle. Si la demande est REJECTED, tout motif fourni par la partie qui a rejeté la demande est visible dans le rapport de demande. Un court délai peut s’écouler entre l’approbation du modèle par tous les utilisateurs et la disponibilité du modèle. Appelez view_templates si vous souhaitez vous assurer que le modèle est disponible.

Astuce

Pour voir les modèles que vous avez enregistrés, appelez REGISTRY.VIEW_REGISTERED_TEMPLATES.

Conception de modèles pour une collaboration

Les modèles de collaboration sont identiques aux modèles de salle blanche, à quelques exceptions près :

  • Les tables partagées listées dans la collaboration sont utilisées pour alimenter la variable source_table du modèle.

  • my_table est utilisé uniquement si un gestionnaire d’analyses souhaite utiliser des données locales, non partagées. Si vous utilisez la variable my_table dans un modèle, sachez que les tables attribuées à cette variable ne sont pas partagées avec la collaboration.

  • Les colonnes des sources de données peuvent porter de nouveaux noms lorsqu’elles sont exposées au modèle ou à l’utilisateur. Voir Renommage de colonne source pour savoir comment et quand les colonnes sources sont renommées. Les modèles et les arguments fournis par l’utilisateur (tels qu’un nom de colonne de jointure) doivent utiliser le nom final et non le nom d’origine si la colonne est renommée.

  • Les modèles d’activation dans une collaboration n’ont pas besoin d’être nommés activation_template_name. Toutes les autres exigences du modèle d’activation continuent de s’appliquer.

Pour plus d’informations sur la syntaxe des modèles personnalisés dans Snowflake Data Clean Rooms, voir Référence d’un modèle de salle blanche personnalisé.

Offres de données

Une offre de données est un ensemble d’une ou plusieurs vues de données partagées avec des gestionnaires d’analyses spécifiques dans le cadre d’une collaboration. Les offres de données peuvent être ajoutées par tous les fournisseurs de données répertoriés dans une collaboration. Les offres de données sont exposées dans un format défini comme data offering ID.alias, où l’alias est une vue spécifique dans l’offre de données. Vous ne pouvez partager des offres de données avec un collaborateur donné que si vous êtes répertorié comme fournisseur de données pour ce gestionnaire d’analyses dans la spécification de collaboration.

Une offre de données est une vue en direct des données, et non un instantané des données au moment de la création ou de l’enregistrement de l’offre de données. Toutes les politiques de Snowflake appliquées aux données sources sont actives dans la collaboration.

Lorsque vous enregistrez une offre de données, Snowflake crée une vue pour chaque source de données répertoriée dans la spécification de l’offre de données. La vue ne comprend que les colonnes répertoriées dans la spécification de l’offre de données. Lorsque vous liez une offre de données à une collaboration, Snowflake crée une copie de cette vue, dont l’accès est protégé pour tous les gestionnaires d’analyses pouvant accéder à cette offre de données, selon la spécification de collaboration. Si vous déplacez, renommez ou modifiez les autorisations d’accès aux tables sous-jacentes, l’offre de données deviendra inutilisable via les liens précédemment enregistrés.

Si vous utilisez Snowflake Standard Edition, vous ne pouvez pas partager d’offre de données avec d’autres collaborateurs, mais vous pouvez utiliser vos propres données dans une requête.

Exigences :

  • Vous devez disposer du privilège OWNERSHIP sur toutes les données que vous souhaitez partager. Si cela n’est pas le cas, vous recevez une erreur de type « octroi d’utilisation de référence manquante » lorsque vous essayez de rejoindre la collaboration. Découvrez comment résoudre ce problème.

  • Vous devez disposer du rôle de fournisseur de données dans une collaboration.

Les offres de données sont ajoutées à une collaboration selon les étapes suivantes :

  1. Créez une spécification de l’offre de données pour vos données.

  2. Enregistrez l’offre de données en appelant REGISTRY.REGISTER_DATA_OFFERING, qui renvoie une ID d’offre de données.

    Cette étape rend les données disponibles pour être reliées à toute collaboration à laquelle vous pouvez accéder. Vous pouvez utiliser le même ID d’offre de données pour partager une offre de données avec plusieurs collaborations.

  3. L’étape suivante dépend de la création ou non de la collaboration :

    • Si la collaboration n’a pas encore été créée, le fournisseur de données transmet l’ID d’offre de données au créateur de la collaboration afin qu’il l’ajoute à la définition de la collaboration. Lorsqu’une offre de données est ajoutée à la définition de la collaboration, celle-ci sera visible par tous les membres de la collaboration une fois que le fournisseur de données aura rejoint la collaboration.

    • Si la collaboration a déjà été créée, le fournisseur de données rejoint la collaboration et appelle COLLABORATION.LINK_DATA_OFFERING avec l’ID d’offre de données, le nom de la collaboration et les personnes avec lesquelles les données peuvent être partagées Un court délai peut s’écouler entre le moment où une offre de données est approuvée par tous les utilisateurs et celui où elle est disponible à l’utilisation. Appelez view_data_offerings si vous souhaitez vous assurer que les données sont disponibles.

    Vous pouvez supprimer des ressources de données d’une collaboration en appelant unlink_data_offering.

Chaque offre de données représente une ou plusieurs tables ou vues. Les tables individuelles sont accessibles en utilisant la syntaxe collaborator alias.data offering ID.dataset alias, où l’ID d’offre de données est une combinaison des valeurs de nom et de version fournies par l’utilisateur, et l’alias est une table unique dans l’offre. Considérez le nom, la version et l’alias comme un système de portée lorsque vous enregistrez vos offres de données.

Par exemple, vous pouvez enregistrer l’offre de données suivante concernant les données de vente, où chaque table est spécifique à un État US :

api_version: 2.0.0
spec_type: data_offering
version: v0
name: examplecorp_sales_by_state
datasets:
 - alias: AL
   data_object_fqn: mydb.mysch.al_data
 - alias: NY
   data_object_fqn: mydb.mysch.ny_data
 - alias: CA
   data_object_fqn: mydb.mysch.ca_data
Copy

Le gestionnaire d’analyses référence alors ces tables en tant que data offering id.AL, data offering id.NY ou data offering id.CA.

Les offres de données ne sont pas visibles dans une collaboration tant que l’utilisateur qui a enregistré l’offre de données ne rejoint pas la collaboration.

Astuce

Si vous ne disposez pas du privilège OWNERSHIP sur les données que vous partagez, vous obtiendrez une erreur lorsque vous essayerez de rejoindre la collaboration ou de lier votre offre de données. Le message d’erreur donne des informations sur une commande SQL qu’un ACCOUNTADMIN doit exécuter pour accorder l’accès aux données à la collaboration. Une fois que l’ACCOUNTADMIN aura exécuté la commande, vous pourrez rejoindre la collaboration. Voir plus d’informations.

Lors de l’exécution d’une requête, les gestionnaires d’analyses transmettent les offres de données par ID au paramètre source_tables de COLLABORATION.RUN.

Pour voir vos offres de données enregistrées, appelez VIEW_REGISTERED_DATA_OFFERINGS.

Appliquez des politiques d’utilisation à vos données

Il existe deux façons d’appliquer une politique de colonnes Snowflake, telle qu’une politique de jointure ou d’agrégation, à vos données partagées :

Appliquer la politique à vos données sources

Toutes les politiques de Snowflake appliquées aux données sources s’appliquent également à la vue de l’offre des données dans la collaboration.

Si vous appliquez des politiques Snowflake à vos données sources, assurez-vous d’en informer vos collaborateurs, afin qu’ils n’essaient pas, sans le savoir, d’exécuter une requête qui joint une colonne non joignable ou qui ne regroupe pas alors qu’elle le devrait. Vous pouvez mentionner des politiques de Snowflake dans le champ description de votre offre de données.

Appliquer la politique à l’offre de données (utilisation des requêtes libres uniquement)

Vous pouvez appliquer les politiques de Snowflake aux requêtes de forme libre dans vos données partagées sans les appliquer aux données sources. Ces politiques sont appliquées à vos données lorsqu’elles sont consultées à l’aide de requêtes libres, en plus des politiques Snowflake appliquées directement à la table source.

Pour ajouter des politiques SQL de forme libre à vos données :

  1. Créez un type de politique pris en charge par Collaboration Data Clean Rooms.

  2. Ajoutez les informations suivantes à la définition de vos offres de données :

    • Définissez allowed_analyses: template_and_freeform_sql.

    • Ajoutez une section freeform_sql_policies à la définition de l’ensemble de données.

    • Ajoutez les sections des types de politiques appropriés sous freeform_sql_policies, répertoriant les politiques Snowflake que vous avez créées, et les colonnes de collaboration auxquelles les appliquer.

Les collaborateurs voient les types de politiques appliqués à vos données lorsqu’ils appellent COLLABORATION.VIEW_DATA_OFFERINGS.

Vous pouvez réutiliser une politique sur plusieurs colonnes sur plusieurs tables.

Exemple :

CREATE OR REPLACE AGGREGATION POLICY my_db.public.my_agg_policy AS ()
  RETURNS AGGREGATION_CONSTRAINT ->
    AGGREGATION_CONSTRAINT(MIN_GROUP_SIZE => 5);
Copy

Renommage de colonne source

Les noms des colonnes exposés au modèle ou à l’appelant SQL de forme libre sont déterminés par les valeurs category et column_type qui décrivent la colonne dans sa définition de l’offre de données. Le renommage des colonnes suit cette règle :

  • Si category pour la colonne est join_custom ou passthrough, le nom de la colonne d’origine est exposé.

  • Si category est join_standard, la colonne est alors renommée en tant que valeur column_type.

  • Si category est timestamp, la colonne est renommée timestamp dans l’offre de données.

Par exemple, si la colonne de la table source est nommée user_email_address, comment cette colonne est exposée au modèle ou au SQL de forme libre dépend de la façon dont elle est définie dans la définition de l’offre de données :

  • Si la catégorie des colonnes est join_standard et que column_type est présent :

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_standard
       column_type: hashed_email_sha256
    Copy

    Alors, la valeur column_type est utilisée dans les requêtes et les modèles :

    SELECT HASHED_EMAIL_SHA256 FROM source_table[0];
    Copy

  • Si la catégorie des colonnes est join_custom :

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_custom
       column_type: hashed_email_sha256
    Copy

    Le nom de la colonne source d’origine est alors utilisé dans les requêtes et les modèles :

    -- column_type is ignored for join_custom columns.
SELECT user_email_address FROM source_table[0];
    Copy

Rejoindre une collaboration

Vous devez rejoindre une collaboration pour toutes les ressources que vous avez apportées à la collaboration pour qu’elles soient disponibles dans la collaboration, ou pour pouvoir exécuter une analyse dans la collaboration.

  • Le créateur appelle uniquement COLLABORATION.JOIN.

  • Les non-créateurs appellent COLLABORATION.REVIEW, puis COLLABORATION.JOIN.

    Important

    Si votre compte se trouve sur une région d’hébergement Cloud différente de celle du propriétaire de la collaboration :

La jointure est un processus asynchrone ; appelez GET_STATUS pour voir quand votre statut est annoncé comme JOINED.

Effectuer une analyse

Vous pouvez exécuter des analyses en exécutant un modèle dans la requête ou en exécutant une requête SQL de forme libre sur les données de collaboration. Vous devez être un gestionnaire d’analyses désigné dans une collaboration pour pouvoir exécuter une analyse. La spécification de collaboration détermine si vous pouvez exécuter un modèle, activer des résultats ou exécuter des requêtes SQL de forme libre. Vos capacités, ainsi que les données et modèles à votre disposition, sont décrits dans la spécification de collaboration.

Le gestionnaire d’analyses prend en charge le coût d’exécution d’une analyse.

Exécuter une analyse à partir d’un modèle

Pour exécuter une analyse à partir d’un modèle, affichez la liste des modèles que vous pouvez exécuter, affichez la liste des offres de données que vous pouvez utiliser, puis appelez COLLABORATION.RUN avec vos valeurs sous forme de paramètres individuels ou de spécification d’analyse au format YAML :

-- See which data offerings are available.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- See which templates you can run.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: My_analysis
    description: Sales results Q2 2025
    template: sales_join_template

    template_configuration:
      view_mappings:
        source_tables:
          -  user1_alias.data_offering_v1.table1
          -  user2_alias.another_data_offering_v1.table_2
      arguments:
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );
Copy

Activer et exécuter des requêtes SQL de forme libre sur vos données

Un fournisseur de données peut permettre aux gestionnaires d’analyses d’exécuter des requêtes SQL sur leurs offres de données de collaboration. Vous devez être membre d’une collaboration et disposer du rôle de gestionnaire d’analyses avec une autorisation SQL de forme libre sur une offre de données pour pouvoir exécuter des requêtes SQL de forme libre sur ces données.

Étapes du fournisseur de données

Pour permettre aux collaborateurs d’interroger un ensemble de données à partir de la ligne de commande, définissez allowed_analyses: template_and_freeform_sql dans la description de votre ensemble de données. Les utilisateurs qui rejoignent la collaboration peuvent créer des requêtes SQL de forme libre sur les ensembles de données auxquels ils peuvent accéder.

Le format YAML suivant définit un ensemble de données qui autorise les requêtes de forme libre :

api_version: 2.0.0
version: 1
name: my_favorite_dataset
datasets:
  - alias: test_freeform_restricted_agg
    data_object_fqn: samooha_provider_sample_database.audience_overlap.customers
    object_class: custom
    allowed_analyses: template_and_freeform_sql
...
Copy

Étapes du gestionnaire d’analyses

  1. Pour voir quels ensembles de données prennent en charge les requêtes de forme libre, après avoir rejoint une collaboration, le gestionnaire d’analyses exécute COLLABORATION.VIEW_DATA_OFFERINGS. La colonne FREEFORM_SQL_VIEW_NAME dans les résultats montre quelles tables sont accessibles en utilisant le SQL de forme libre, et le nom de la table à utiliser dans la requête SQL.

    CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);
    Copy
    +-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
|   template_view_name          | template_join_columns  | analysis_allowed_columns     | activation_allowed_columns   |      freeform_sql_view_name           |
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
| useralias.data_offering_alias |     ip_address         | email, name, age             |             SSN              | alias_name.test_data_offering_v0.customers|
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+

  2. Le collaborateur peut ensuite interroger la table répertoriée dans la colonne FREEFORM_SQL_VIEW_NAME en utilisant des requêtes SQL de forme libre :

    SELECT * FROM alias_name.test_data_offering_v0.customers;
    Copy

Toutes les politiques appliquées à la table sont mises en œuvre.

Exécuter une analyse avec vos propres données lorsque vous utilisez Standard Edition

Si vous utilisez Standard Edition, vous pouvez exécuter une analyse de la manière standard. Cependant, vous ne pouvez pas ajouter vos données à la description de la collaboration et les partager avec d’autres utilisateurs.

Pour utiliser vos propres données dans une collaboration en tant qu’utilisateur de Standard Edition :

  1. Pour enregistrer votre offre de données, appelez REGISTRY.REGISTER_DATA_OFFERING. Vous devez spécifier les noms des colonnes.

  2. Appelez COLLABORATION.LINK_LOCAL_DATA_OFFERING.

    Vous seul pouvez voir votre offre lorsque vous appelez COLLABORATION.VIEW_DATA_OFFERINGS ; les autres collaborateurs ne verront pas votre source de données répertoriée.

  3. Utilisez l’ID d’offre de données lorsque vous appelez COLLABORATION.RUN, soit dans le paramètre``local_template_view_names``, soit dans le champ local_view_mappings.my_tables si une analyse YAML est transmise. local_template_view_names et local_view_mappings.my_tables renseignent le paramètre my_table dans le modèle.

L’exemple suivant montre comment exécuter un modèle à l’aide de la version au format YAML de la procédure d’exécution. Cet exemple comprend le champ my_tables, qui est renseigné en appelant LINK_LOCAL_DATA_OFFERING.

-- See what data offerings are available. Your own local data will be listed here as well.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: my_analysis
    description: Cross-purchase results for Q4 2025
    template: mytemplate_v1

    template_configuration:
      view_mappings:
        source_tables:
          - ADVERTISER1.ADVERTISER_DATA_V1.CUSTOMERS
          - PUBLISHER.ADVERTISER_DATA_V1.CUSTOMERS
      local_view_mappings:
        my_tables:
          - PARTNER.MY_DATA_V1.MY_CUSTOMERS # Populate my_table array with my own table.
      arguments:  # Template arguments, as name: value pairs
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );
Copy

Activer les résultats de la requête

Note

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, à savoir que vous utilisez un rôle géré par les procédures de gestion des accès, vous devez disposer du privilège REGISTER DATA OFFERING pour rejoindre n’importe quelle collaboration où vous êtes un gestionnaire d’analyses et où la spécification de la collaboration inclut un champ activation_destinations.

Pour activer les résultats d’une requête :

  1. Assurez-vous que toutes les colonnes d’activation possèdent les propriétés suivantes définies dans la spécification appropriée :

    La spécification de l’offre de données pour la table avec la colonne activée doit définir activation_allowed: TRUE pour cette colonne :

     api_version: 2.0.0
 spec_type: data_offering
 name: 2025_orders
 version: 2025_01_01_v1
 description: Activating Cleveland sales results for 2025

 datasets:
  - alias: customers
    data_object_fqn: db1.schema1.orders
    allowed_analyses: template_only
    object_class: custom
    schema_and_template_policies:
      email:
        category: join_standard
        column_type: hashed_email_sha256
        activation_allowed: TRUE
      purchase_amount:
        category: passthrough
        activation_allowed: TRUE
    Copy

    Note

    Toute colonne utilisée dans le modèle avec le filtre activation_policy appliqué doit avoir sa valeur activation_allowed définie sur TRUE dans la spécification de l’offre de données. L’exemple suivant montre un modèle avec la politique d’activation appliquée à deux colonnes fournies par le gestionnaire d’analyses :

    BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT count(*) AS ITEM_COUNT, c.status, c.age_band
    FROM IDENTIFIER({{ my_table[0] }}) AS c
    JOIN IDENTIFIER({{ source_table[0] }}) AS p
    ON {{ c_join_col | sqlsafe | activation_policy }} = {{ p_join_col | sqlsafe | activation_policy }}
    GROUP BY c.status, c.age_band
    ORDER BY c.age_band;
  RETURN 'analysis_results';
END;
    Copy

  2. Le gestionnaire d’analyses appelle RUN pour exécuter l’analyse.

    • Si l’option est activée pour vous-même, les résultats sont disponibles immédiatement dans le compte de l’appelant dans la table consumers_database.ACTIVATION_RESULTS.CONSUMER_DIRECT_ACTIVATION_SUMMARY. Pour savoir comment afficher les résultats de la requête, voir la dernière étape.

    • Si vous activez un autre collaborateur :

      1. Le collaborateur appelle VIEW_ACTIVATIONS jusqu’à ce qu’un statut SHARED soit renvoyé. L’activation sur un autre compte peut prendre beaucoup de temps pour les grands jeux de résultats, car les données doivent être transférées sur le compte du collaborateur et déchiffrées.

      2. Lorsque le statut de l’activation est SHARED, le collaborateur appelle PROCESS_ACTIVATION pour envoyer les résultats sur son compte. La réponse à PROCESS_ACTIVATION comprend les noms de la table et du segment. Cette opération définit le statut d’activation sur PROCESSED.

  3. Pour récupérer les résultats de la requête, exécutez la commande SQL suivante, en indiquant le nom de votre table de résultats et, éventuellement, un nom de segment pour filtrer les résultats :

    SELECT *
  FROM <results_table_name>
    [WHERE segment = <segment_name>];
    Copy

Quitter ou supprimer une collaboration

  • Les non-propriétaires quittent une collaboration en appelant COLLABORATION.LEAVE. Toutes les offres de données qu’ils ont fournies seront supprimées de la collaboration. Vous ne pouvez pas rejoindre à nouveau une collaboration après l’avoir quittée.

  • Les propriétaires de collaboration ne peuvent pas quitter une collaboration ; la propriété ne peut pas être transférée. Un propriétaire de collaboration peut supprimer une collaboration pour tous les collaborateurs en appelant COLLABORATION.TEARDOWN.

Les deux processus sont asynchrones. Vous devez appeler GET_STATUS pour contrôler le statut, et appelez LEAVE ou TEARDOWN à nouveau lorsque GET_STATUS affiche le statut LOCAL_DROP_PENDING.

Activer l’exécution automatique inter-Cloud

Si vous ne vous trouvez pas dans la même région d’hôte Cloud que le propriétaire de la collaboration, l’exécution automatique inter-Cloud (LAF) doit être activée pour votre compte pour que vous puissiez rejoindre la collaboration. Si vous essayez d’examiner une collaboration dans une autre région Cloud et que la LAF n’est pas activée pour votre compte, ou que vous ne disposez pas des autorisations appropriées, vous recevez une erreur lorsque vous appelez REVIEW sur la collaboration.

Note

Lorsque l’exécution automatique inter-Cloud est utilisée dans une collaboration :

  • Les données sont répliquées dans le compte de chaque collaborateur qui peut accéder à ces données.

  • Les données sont également répliquées dans la région du propriétaire, qu’il puisse ou non accéder à l’offre de données. Toutefois, la capacité à accéder aux données est déterminée par les règles de partage de l’offre de données.

Vous pouvez déterminer votre propre région d’hôte Cloud en exécutant SELECT CURRENT_REGION();

Pour activer l’exécution automatique inter-Cloud dans votre compte :

  1. Un administrateur de l’organisation doit activer la LAF sur votre compte en appelant SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT. Pour plus d’informations, voir Gérer les privilèges pour l’exécution automatique.

  2. Disposer des privilèges appropriés pour consulter ou rejoindre une collaboration LAF, utilisez SAMOOHA_APP_ROLE, ou utilisez un rôle doté du privilège MANAGE LISTING AUTO FULFILLMENT au niveau du compte.

Les collaborateurs situés dans une autre région d’hôte Cloud verront un décalage supplémentaire des données en raison de la fréquence de réplication. La fréquence de réplication n’est pas encore configurable dans une Collaboration Data Clean Room.

Exemple : Collaboration entre deux parties

L’exemple suivant illustre une collaboration entre deux parties, où une partie (nommée « alice ») est le créateur de la collaboration, un fournisseur de données pour elle-même et bob et un gestionnaire d’analyses. L’autre partie (nommée « bob ») est un fournisseur de données pour elle-même et alice et un gestionnaire d’analyses.

Cet exemple illustre les actions suivantes :

  • Création d’une collaboration.

  • Enregistrement des modèles et des offres de données.

  • Ajout d’un modèle et d’une offre de données au moment de la création de la collaboration.

  • Rejoindre une collaboration.

  • Ajouter des modèles et des ressources à une collaboration existante.

  • Exécuter une analyse.

Pour exécuter cet exemple, vous devez disposer de deux comptes distincts avec Snowflake Data Clean Rooms installé.

Vous pouvez soit télécharger les fichiers et les importer sur votre compte Snowflake, soit copier et coller le code d’exemple dans les feuilles de calcul de deux comptes distincts en utilisant Snowsight.

Téléchargez les fichiers SQL sources, puis importez-les dans deux comptes distincts qui disposent de Snowflake Data Clean Rooms :