Activating query results¶

Aperçu de l’activité¶

Le fournisseur ou le consommateur peut envoyer les résultats du modèle en dehors de la clean room dans le cadre d’une activité appelée activation. Snowflake supporte trois types d’activité :

Activation du fournisseur, où les résultats sont poussés vers une table dans le compte Snowflake du fournisseur.
Activation du consommateur, où les résultats sont poussés vers une table dans le compte Snowflake du consommateur.
Activation par un tiers, où le fournisseur ou le consommateur pousse les résultats vers un tiers approuvé par Snowflake, tel que LiveRamp ou Meta Ads Manager, par le biais d’un connecteur d’activation.

In all cases, the template must support activation, and parties should approve activation for any columns of their own data that will be activated. Data providers specify which columns of their data are activated by setting an activation policy. For more about clean room policies see Comprendre les politiques relatives aux tables de clean room.

L’activation prend en charge la protection différentielle de la vie privée, si elle est activée, et respecte les règles et les budgets de protection différentielle de la vie privée.

Important

Si le consommateur et le fournisseur se trouvent dans des régions Cloud différentes, vous devez activer Exécution automatique inter-cloud dans les comptes et pour les deux salles blanches.

Activation des fournisseurs et des consommateurs¶

Vous pouvez configurer une clean room pour qu’elle enregistre les résultats du modèle dans le compte Snowflake du fournisseur ou du consommateur. Le fournisseur et le consommateur doivent tous deux approuver l’activation de toute donnée sortant de la clean room.

Activation is implemented using a dedicated activation template. In the clean rooms UI, an activation template can be associated with an analysis template, and the user can run the analysis template, view the results, then run the associated activation template. The Snowflake-provided Audience Overlap & Segmentation flow does this.

An activation template need not be identical to any associated analysis template. The activation template is often a subset of the analysis template.

Modèles pris en charge¶

Les modèles suivants permettent l’activation du fournisseur et du consommateur :

Audience Overlap & Segmentation
Modèles personnalisés

Combinaisons prises en charge¶

Activation can be run either by the provider or the consumer. (Learn more about provider-run analyses.)

Les combinaisons suivantes sont possibles :

	Activation du fournisseur	Activation du consommateur	Activation par un tiers
Gestion par le fournisseur	✅	❌	UI only
Gestion par le consommateur	✅	✅	UI only

Résultats¶

Les Résultats de l’activation du fournisseur sont enregistrés sur le compte du fournisseur dans la table SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY.

Les Résultats de l’activation du consommateur sont enregistrés sur le compte du consommateur dans la table SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Reportez-vous à pour consulter les résultats afin de savoir comment lire les données.

Mise en œuvre de l’activation du fournisseur ou du consommateur¶

Configuration

L’activation lors des UI de clean room exige que le compte des clean rooms permette l’activation.
Pour l’activation par le fournisseur, la clean room doit être configurée pour prendre en charge l’analyse par le fournisseur.

1. Créez ou rejoignez une clean room

Lorsque vous créez ou rejoignez une clean room, à l’étape Configure Analysis & Query, sous Activation Settings, indiquez quelles colonnes doivent être ajoutées aux résultats activés sur votre compte.

2. Exécutez le modèle et activez les résultats

Pour exécuter l’activation associée à votre analyse, procédez comme suit :

Exécutez votre analyse.
Après avoir exécuté une analyse, sélectionnez Results » Activate.
Sous Activation Hub, sélectionnez le nom du compte fournisseur ou consommateur à activer.
Fournissez des informations spécifiques au modèle d’activation, par exemple en fournissant des noms de segmentation descriptifs ou en sélectionnant des colonnes d’activation.
Provide a segment name: this is an arbitrary string used to identify a set of results from a given run. You can provide a different string for each activation to group each run’s results separately, or you can use the same segment name over multiple runs if you want to combine results.
Sélectionnez Push Data.
To learn how to view activated results, see Vue des résultats de l’activation des fournisseurs et des consommateurs.

L’activation est exécutée différemment selon la personne qui l’exécute et selon qu’il s’agit d’une activation de consommateur ou de fournisseur.

Important

La première fois qu’un consommateur active des données vers un compte de fournisseur dans une clean room, le fournisseur doit établir un pipeline de données en se connectant à l’UI de clean room pour ce compte et en restant connecté jusqu’à 30 minutes. Cette opération ne doit être effectuée qu’une seule fois par clean room et par consommateur. Tant que cela n’est pas fait, les données n’apparaîtront pas sur le compte du fournisseur, même si l’activation réussit.

Voici comment un consommateur peut envoyer des résultats à son propre compte Snowflake.

Fournisseur

Créez la clean room, créez des liens entre les ensembles de données et définissez des politiques de jonction, comme pour une clean room standard.

Choisissez un modèle standard Snowflake supporté par <label-dcr_activation_supported_templates>, ou ajoutez un modèle d’activation personnalisé <label-dcr_custom_templates_activation> à la clean room. Si cette clean room doit être utilisée dans l’UI, vous devez fournir une forme web avec les champs d’activation appropriés, comme décrit dans la documentation du modèle.

Activez le modèle pour l’activation du consommateur en appelant provider.enable_template_for_consumer_activation.

To specify which provider columns can be activated, set the activation policy in the clean room for the enabled template by calling provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs, définissez la directive de version par défaut et publiez la clean room, comme d’habitude.

Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction, comme pour une clean room standard.

To specify which consumer columns can be activated, set the activation policy in the clean room for that template by calling consumer.set_activation_policy.

Exécutez l’activité en appelant consumer.run_activation, le dernier paramètre étant défini sur TRUE pour indiquer qu’il s’agit d’une activation de consommateur.

Visualisez les résultats, comme décrit ci-dessous.

Exemples

Download the following examples and upload them as worksheet files in your Snowflake account. You will need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

:télécharger :Code d'exemple du fournisseur</samples/clean-rooms/c-run-c-activation-p.sql>
:télécharger :Code d'exemple pour les consommateurs</samples/clean-rooms/c-run-c-activation-c.sql>

Voici comment un consommateur peut envoyer des résultats au compte Snowflake d’un fournisseur.

Important

Si le consommateur et le fournisseur n’ont pas tous les deux les UI de clean room installées, et que le consommateur s’active auprès du fournisseur :

Le consommateur **** doit exécuter la commande SQL suivante :
```
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2
  ADD ACCOUNTS = $provider_account_data_sharing_id;
```
Copy
où $provider_account_data_sharing_id est l’identificateur de compte de partage de données du fournisseur <label-account_name_data_sharing>
Le fournisseur doit exécuter la procédure suivante :
```
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);
```
Copy
où $consumer_account_data_sharing_id est l’identificateur de compte de partage de données du consommateur.

1. Fournisseur

Créez la clean room de la manière habituelle.

Créez des liens entre les ensembles de données. Le fournisseur doit également établir un lien entre la table samooha_by_snowflake_local_db.library.temp_public_key et la clean room.

Paramétrez la politique de jonction de la manière habituelle.

Choisissez un modèle standard Snowflake pris en charge, ou ajoutez un modèle d’activation personnalisé vers la salle blanche. Si cette salle blanche doit être utilisée dans l’UI des salles blanches, vous devez fournir un formulaire Web avec les champs d’activation appropriés.

To specify which provider columns can be activated, set the activation policy in the clean room for that template by calling provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs, définissez la directive de version par défaut et publiez la clean room, comme d’habitude. (Si le programme d’installation de l’UI de clean room n’est pas installé, appelez provider.setup_provider_activation_share_mount_task après avoir ajouté des consommateurs)

2. Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction, comme pour une clean room standard.

Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling consumer.set_activation_policy.

Exécutez l’activation en appelant consumer.run_activation, avec le dernier argument fixé à FALSE pour indiquer une activation de fournisseur.

Note

Une version chiffrée des données activées est stockée sur le compte du consommateur pendant 28 jours dans la table. SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY. Les données datant de plus de 28 jours sont effacées du compte du consommateur.

3. Fournisseur

La première fois qu’un consommateur active des données sur votre compte, vous devez vous connecter aux UI de clean room pour ce compte pendant environ 30 minutes après l’activation des données par le consommateur. Ensuite, les données apparaîtront dans votre compte. Cette opération n’est effectuée qu’une seule fois par clean room et par compte consommateur. Les activations ultérieures par le même consommateur dans la même clean room ne nécessitent pas cette étape.

Les résultats doivent être déchiffrés avant d’être enregistrés sur votre compte, ce qui peut prendre un certain temps. La tâche de déchiffrement s’arrête au bout de 60 minutes ; dans ce cas, appelez provider.update_activation_warehouse pour augmenter la taille de l’entrepôt utilisé pour le déchiffrement.

Visualisez les résultats, comme décrit ci-dessous.

Exemples

:télécharger :Code d'exemple fournisseur </samples/clean-rooms/c-run-p-activation-p.sql>
:télécharger :Code d'exemple consommateurs </samples/clean-rooms/c-run-p-activation-c.sql>

Voici comment un fournisseur peut pousser les résultats de son propre compte Snowflake. Il s’agit d’une combinaison de plusieurs techniques, notamment les modèles personnalisés, l’analyse effectuée par le fournisseur et l’activation du fournisseur, ce qui implique plusieurs cycles de requête et d’approbation entre le fournisseur et le consommateur.

1. Fournisseur

Créez la clean room, liez les ensembles de données et définissez les politiques de jonction, comme pour une clean room standard, à une exception près : vous devez établir un lien dans la table samooha_by_snowflake_local_db.library.temp_public_key. Les données du fournisseur sont chiffrées, ce qui permet le chiffrement et le déchiffrement des résultats.

Choisissez un modèle standard Snowflake supporté par <label-dcr_activation_supported_templates>, ou ajoutez un modèle d’activation personnalisé <label-dcr_custom_templates_activation> à la clean room. Si cette clean room doit être utilisée dans l’UI, vous devez fournir une forme web avec les champs appropriés pour permettre l’activation, comme décrit dans la documentation du modèle.

Set the activation policy in the clean room for that template to specify which provider columns can be activated by calling provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs de la manière habituelle. Si l’UI de clean room n’est pas installée, vous devez appeler provider.setup_provider_activation_share_mount_task après avoir ajouté des utilisateurs.

Autorisez les analyses effectuées par le fournisseur dans la clean room en appelant provider.enable_provider_run_analysis. Cela doit être fait après l’ajout de collaborateurs mais avant l’installation de la clean roompar les collaborateurs. Si vous modifiez ce paramètre après l’installation de la clean room par un consommateur, ce dernier doit réinstaller la clean room pour que la modification prenne effet.

Paramétrez la directive de version par défaut et publiez la clean room, comme d’habitude.

2. Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction comme dans une clean room standard.

Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling consumer.set_activation_policy.

3. Fournisseur

Demandez l’autorisation au consommateur d’exécuter votre modèle d’activation en appelant provider.request_provider_activation_consent.

4. Consommateur

Accordez au fournisseur l’autorisation d’exécuter un modèle donné dans cette clean room en appelant consumer.enable_templates_for_provider_run.

Accordez au fournisseur l’autorisation d’activer les résultats d’un modèle donné dans cette clean room en appelant consumer.approve_provider_activation_consent.

5. Fournisseur

Autorisez le partage des données des consommateurs lors de l’activation d’un fournisseur en appelant provider.mount_request_logs_for_all_consumers.

Exécutez le modèle d’activation en appelant provider.submit_analysis_request). Il faut plusieurs minutes pour que la requête apparaisse dans les connecteurs ; vérifiez le statut en appelant provider.check_analysis_status. Notez que même lorsque le statut est signalé comme SUCCESS, un délai supplémentaire est nécessaire pour que les résultats soient déchiffrés et enregistrés dans la table Snowflake du fournisseur. Toutes les données déchiffrées sont ajoutées en une seule fois à la table des résultats. Consultez périodiquement la table des résultats de votre ID d’activité ou segment. La tâche de déchiffrement s’arrête au bout de 60 minutes ; dans ce cas, appelez provider.update_activation_warehouse pour augmenter la taille de l’entrepôt utilisé pour le déchiffrement.

Note

Pour modifier un modèle après son approbation par le consommateur, vous devez suivre les étapes suivantes, sinon provider.submit_analysis_request continuera à exécuter la dernière version approuvée du modèle.

Le fournisseur met à jour le modèle en appelant provider.add_custom_sql_template. Inutile de rappeler create_or_update_cleanroom_listing.

Le consommateur appelle consumer.enable_templates_for_provider_run.

Le consommateur appelle consumer.approve_provider_activation_consent.

Le modèle mis à jour est maintenant prêt à être activé par le fournisseur.

Erreurs courantes

Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized - La table temporaire des résultats n’a pas pu être générée pour une raison quelconque. Il peut s’agir d’une erreur SQL dans le modèle, ou bien votre modèle n’a pas explicitement généré une table ; consultez les détails de l’erreur.
Query validation checks failed - Certaines colonnes utilisées dans le modèle ne figuraient pas dans les politiques d’activation.

Exemples

:télécharger :Code d'exemple fournisseur </samples/clean-rooms/p-run-p-activation-p.sql>
:télécharger :Code d'exemple consommateurs </samples/clean-rooms/p-run-p-activation-c.sql>

Vue des résultats de l’activation des fournisseurs et des consommateurs¶

Emplacement et format des résultats de l’activation¶

All activation results are appended to a clean room designated table in the provider’s or consumer’s account. Each row in the table maps to a row in the query result. Results from each run are appended to the table (the table is not cleared before each run). You can distinguish between different runs by the ACTIVATION_ID column, which is unique per activation, or the SEGMENT column, which can be specified by the caller for each activation run.

Note

Provider activation results are written in encrypted format to a temporary table in the consumer’s localDB. The results are then copied over to the provider’s account and decrypted before saving. This extra move and decryption step can cause delays with large result sets.

Les résultats de l’activation du fournisseur sont stockés dans SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY dans le compte du fournisseur.
Les résultats de l’activation du consommateur sont stockés dans SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY dans le compte du consommateur.

Ces tables contiennent les colonnes suivantes :

USER_ID:: Une ligne de résultats, au format JSON, où les clés sont les noms des colonnes et les valeurs la valeur de cette colonne dans cette ligne. L’objet contient également une colonne pour chaque argument transmis au modèle.
ACTIVATION_ID:: Un ID unique pour chaque requête. L’ID est renvoyé lorsque la requête d’activation a abouti. Vous pouvez filtrer par cette colonne pour obtenir tous les résultats de la même activité, ou par SEGMENT si vous réutilisez le même nom de segment dans plusieurs activités. C’est la même chose que l’ID de requête renvoyé par submit_analysis_request ou run_activation.
CLEANROOM_NAME:: Nom de la clean room où la requête a été exécutée.
CONSUMER:: (Activation du fournisseur uniquement) Le consommateur qui a approuvé cette activation.
PROVIDER:: (Activation du consommateur uniquement) Le fournisseur qui a approuvé cette activation.
SEGMENT:: Une valeur de chaîne arbitraire que vous attribuez lorsque vous exécutez l’activation. Cette colonne vous permet de joindre les résultats de plusieurs requêtes.
TIMESTAMP:: Quand l’activité a été exécutée.

Exemple d’activation du fournisseur

SELECT * FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY WHERE segment = 'my_segment';

                             USER_ID                          |   CLEANROOM_NAME |   SEGMENT  | CONSUMER |          TIMESTAMP      |  ACTIVATION_ID
"{""AGE_BAND"":55,""ITEM_COUNT"":2328,""STATUS"":""MEMBER""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":20,""ITEM_COUNT"":88,""STATUS"":""PLATINUM""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":80,""ITEM_COUNT"":18,""STATUS"":""GOLD""}"     |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
...

Lecture des résultats de l’activation du fournisseur ou du consommateur¶

Exécutez la commande SQL appropriée pour voir les résultats activés sur votre compte Snowflake :

Voir les résultats de l’activation fournisseur

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Voir les résultats de l’activation consommateur

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Chaque ligne de données est combinée en un objet dans la colonne USER_ID. Vous pouvez aplatir les résultats à l’aide d’une requête comme la suivante :

-- Assuming columns AGE_BAND, STATUS, and ITEM_COUNT
SELECT
  item:"AGE_BAND",
  item:"STATUS",
  item:"ITEM_COUNT"
FROM (SELECT parse_json(user_id)
      AS item
      FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
      WHERE segment = $segment_name)
ORDER BY item:"AGE_BAND", item:"STATUS" ASC
LIMIT 20 ;

Copy

Voir les 10 dernières lignes de résultats dans Snowsight :

Connectez-vous à Snowsight.

Dans le menu de navigation, sélectionnez Catalog » Database Explorer.

**Pour l’activation du fournisseur **, naviguez jusqu’à SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY.

Pour l’activation du consommateur, naviguez jusqu’à SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Sélectionnez Data Preview.

Activation par un tiers¶

L’activation par un tiers dépose les résultats de la requête sur le compte d’un tiers approuvé par Snowflake à l’aide d’un connecteur d’activation par un tiers.

L’activation par un tiers n’est possible que dans les UI de clean rooms, et non à l’aide de modèles personnalisés.

L’activation lors de l’utilisation des UI de clean rooms n’est possible que si le compte des clean rooms permet l’activation.

L’administrateur de la clean room doit configurer l’environnement pour qu’il prenne en charge les connecteurs d’activation tiers, sélectionner les connecteurs autorisés et les configurer, avant qu’ils ne puissent être utilisés dans une clean room.

L’activation par un tiers soutient les analyses gérées par les consommateurs et les fournisseurs.

Modèles pris en charge¶

Les modèles suivants prennent en charge l’activation par un tiers :

Audience Overlap & Segmentation

Mise en œuvre de l’activation par un tiers¶

Créez ou rejoignez la clean room : lors de la création ou de l’adhésion à la clean room, à l’étape Configure Analysis & Query, sous Activation Settings, indiquez quelles colonnes doivent être ajoutées aux résultats activés sur votre compte.
Activer les résultats :
1. Exécutez votre analyse.
2. Après avoir exécuté une analyse, sélectionnez Results » Activate.
3. Sous Activation Hub, sélectionnez le nom du fournisseur tiers à activer.
4. Fournissez des informations spécifiques au fournisseur. Il peut s’agir de fournir des noms descriptifs ou de sélectionner les colonnes à activer. Les infobulles de la page devraient fournir des informations supplémentaires pour ce fournisseur.
5. Sélectionnez Push Data.