Activating query results¶
アクティベーションの概要¶
プロバイダーまたはコンシューマーは、 アクティベーション と呼ばれるプロセスで、clean roomの外部にテンプレート結果を送信することができます。Snowflakeは3タイプのアクティビティをサポートしています：
プロバイダーアクティベーション、結果がプロバイダーのSnowflakeアカウントのテーブルにプッシュされます。
コンシューマーアクティベーション、結果がコンシューマーのSnowflakeアカウントのテーブルにプッシュされます。
サードパーティアクティベーション、プロバイダーまたはコンシューマーは、 アクティベーションコネクタ を介して、結果をLiveRamp やMeta Ads ManagerなどのSnowflakeが承認したサードパーティにプッシュします。
いずれの場合でも、テンプレートはアクティベーションをサポートする必要があり、当事者は、アクティベーションされる自身のデータの列について、アクティベーションを承認する必要があります。データプロバイダーは、アクティベーションポリシーを設定することで、データのどの列をアクティベーションするかを指定します。クリーンルームのポリシーの詳細については、 clean roomテーブルのポリシーを理解する をご参照ください。
アクティベーションは差分プライバシーを（有効であれば）サポートし、差分プライバシーのルールとバジェットに従います。
重要
コンシューマーとプロバイダーが異なるクラウドリージョンにある場合は、両方のアカウントと両方のクリーンルームで クロスクラウドの自動フルフィルメント を有効にする必要があります。
プロバイダーとコンシューマーのアクティベーション¶
clean roomを構成すると、プロバイダーまたはコンシューマーのSnowflakeアカウントにテンプレートの結果を保存できます。プロバイダーとコンシューマーの双方が、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.
サポートされるテンプレート¶
以下のテンプレートはプロバイダーとコンシューマーのアクティベーションをサポートしています：
Audience Overlap & Segmentation
サポートされる組み合わせ¶
Activation can be run either by the provider or the consumer. (Learn more about provider-run analyses.)
以下の組み合わせをサポートしています：
プロバイダーのアクティベーション |
コンシューマーアクティベーション |
サードパーティアクティベーション |
|
|---|---|---|---|
プロバイダーが実行 |
✅ |
❌ |
UI のみ |
コンシューマーが実行 |
✅ |
✅ |
UI のみ |
結果¶
プロバイダーのアクティベーション結果 は、 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY テーブルのプロバイダーアカウントに保存されます。
コンシューマーのアクティベーション結果 は、 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY テーブルのコンシューマーのアカウントに保存されます。
データの読み方については、 結果の表示 をご参照ください。
プロバイダーまたはコンシューマーアクティベーションを実装する¶
設定
clean roomの UI 使用時にアクティベーションするには、clean roomのアカウントが アクティベーションを許可 している必要があります。
アクティベーションをプロバイダーが実行するには、clean roomは プロバイダーが実行する分析をサポートするよう構成 されている必要があります。
1.clean roomの作成または参加
clean roomを作成または参加する際、 Configure Analysis & Query ステップの Activation Settings で、どの列を自分のアカウントにアクティベートされた結果に追加するかを指定します。
2.テンプレートの実行と結果のアクティベート
分析に関連付けたアクティビティを実行するには、以下の手順に従ってください：
分析を実行します。
分析の実行後、Results » Activate を選択します。
Activation Hub で、アクティベートするプロバイダーまたはコンシューマーアカウントの名前を選択します。
セグメンテーションのわかりやすい名前を入力する、アクティベーションの列を選択するなど、アクティベーションテンプレートに固有の情報を入力します。
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.
Push Data を選択します。
アクティブ化された結果を表示する方法については、 プロバイダーとコンシューマーのアクティベーション結果を表示する をご参照ください。
アクティベーションのパフォーマンスは、誰が実行するかによっても、コンシューマーとプロバイダーのどちらのアクティベーションかによっても異なります。
重要
コンシューマーが初めてclean roomのプロバイダーアカウントに対してデータをアクティベートする場合、プロバイダーはそのアカウントのclean room UI にサインインし、最大30分間サインインし続けることで、データパイプラインを確立する必要があります。この作業は、1コンシューマーの1つのclean roomにつき1回のみ行う必要があります。それが完了するまでは、アクティベーションが成功しても、データはプロバイダーのアカウントに表示されません。
コンシューマーが自分のSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。
プロバイダー
標準的なclean roomとして、clean roomを作成し、データセットをリンク付けして、結合ポリシーを設定します。
サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をclean roomに追加します。このclean roomを UI で使用する場合は、テンプレートのドキュメントに記載されているように、適切なアクティベーションフィールドを持つウェブフォームを提供する必要があります。
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.コンシューマーコラボレーターを追加し、デフォルトのリリースディレクティブをセットして、clean roomを公開します。
コンシューマー
clean roomをインストールし、データセットをリンクさせて、標準的なclean roomに対する結合ポリシーを設定します。
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.最後のパラメーターに、コンシューマーアクティベーションを示す TRUE をセットし、
consumer.run_activationを呼び出してアクティベーションを実行します。下記のように結果を表示します。
例
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.
コンシューマーがプロバイダーのSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。
重要
コンシューマーとプロバイダーの どちらにも clean room UI がインストールされおらず、コンシューマーがプロバイダーをアクティベートしている場合：
コンシューマー は以下の SQL コマンドを実行する必要があります：
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2 ADD ACCOUNTS = $provider_account_data_sharing_id;
$provider_account_data_sharing_idがプロバイダーの データ共有アカウント識別子 である場合プロバイダー は以下のプロシージャを実行する必要があります：
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share( $consumer_account_data_sharing_id, TRUE, FALSE);
$consumer_account_data_sharing_idがコンシューマーの データ共有アカウント識別子 である場合
1.プロバイダー
標準的な方法でclean roomを作成します。
Link datasets. The provider must also link the SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.TEMP_PUBLIC_KEY table into the clean room.
標準的な方法で結合ポリシーを設定します。
サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をクリーンルームに追加します。このクリーンルームをクリーンルーム UI 内で使用する場合は、適切なアクティベーションフィールドを備えた Webフォームを提供 する必要があります。
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.コンシューマーコラボレーターを追加し、デフォルトのリリースディレクティブをセットして、clean roomを公開します。(clean room UI がインストールされていない場合は、コンシューマーを追加した後に、
provider.setup_provider_activation_share_mount_taskを呼び出します。)
2.コンシューマー
clean roomをインストールし、データセットをリンクさせて、標準的なclean roomに対する結合ポリシーを設定します。
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.最後の引数にプロバイダーアクティベーションを示す FALSE をセットし、
consumer.run_activationを呼び出して、アクティベーションを実行します。注釈
有効化されたデータの暗号化されたバージョンは、コンシューマーのアカウントの SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY テーブルに28日間格納されます。28日より古いデータはコンシューマーのアカウントから削除されます。
3.プロバイダー
コンシューマーが初めて自分のアカウントに対してデータをアクティベートする場合、コンシューマーがデータをアクティベートした後、そのアカウントのclean room UI におよそ30分間サインインする必要があります。その後、データが自分のアカウントに表示されます。これは、1コンシューマーアカウントの1つのclean roomにつき1回のみ行われます。同じclean roomで同じコンシューマーが後でアクティベーションを行う場合、このステップは必要ありません。
結果をアカウントに保存する前に復号化する必要がありますが、それには時間がかかる場合があります。復号化タスクは60分後にタイムアウトします。タイムアウトした場合は、 provider.update_activation_warehouse を呼び出して、復号化に使用するウェアハウスのサイズを増やします。
下記のように結果を表示します。
例
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.
プロバイダーが自分のSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。これは、カスタムテンプレート、プロバイダーが実行する分析、プロバイダーアクティベーションなど、いくつかのテクニックを組み合わせたもので、プロバイダーとコンシューマーの間でリクエストと承認が何度も繰り返されます。
1.プロバイダー
標準的なclean roomとして、clean roomを作成し、データセットをリンク付けして、結合ポリシーを設定しますが、 例外として、テーブル
samooha_by_snowflake_local_db.library.temp_public_keyでリンクさせる必要があります。プロバイダーが実行するデータは暗号化されており、結果の暗号化と復号化を可能にしています。サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をclean roomに追加します。このclean roomを UI で使用する場合は、テンプレートのドキュメントに記載されているように、適切なフィールドを持ちアクティベーションをサポートするウェブフォームを指定する必要があります。
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.標準的な方法でコンシューマーコラボレーターを追加します。clean room UI がインストールされていない場合は、ユーザーを追加した後に
provider.setup_provider_activation_share_mount_taskを呼び出す必要があります。
provider.enable_provider_run_analysisを呼び出すことで、プロバイダーが実行する分析をclean roomで有効にします。これは、コラボレーターを追加した 後 で、かつコラボレーターがclean roomをインストールする 前 に行う必要があります。コンシューマーがclean roomをインストールした後にこの設定を変更する場合、コンシューマーはこの変更を適用するためにclean roomを再びインストールする必要があります。デフォルトのリリースディレクティブを設定し、通常どおりclean roomを公開します。
2.コンシューマー
標準的なclean roomとして、clean roomをインストールし、データセットをリンク付けして、結合ポリシーを設定します。
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.プロバイダー
provider.request_provider_activation_consentを呼び出して、アクティベーションテンプレートを実行するための許可をコンシューマーにリクエストしてください。
4.コンシューマー
consumer.enable_templates_for_provider_runを呼び出し、このclean roomで指定されたテンプレートを実行するための許可をプロバイダーに付与します。
consumer.approve_provider_activation_consentを呼び出し、このclean roomで指定されたテンプレートから結果をアクティベートするための許可をプロバイダーに付与します。
5.プロバイダー
provider.mount_request_logs_for_all_consumersを呼び出し、プロバイダーアクティベーションでのコンシューマーデータの共有を有効にします。
provider.submit_analysis_requestを呼び出して、アクティベーションテンプレートを実行します。リクエストがログに表示されるまで数分かかります。provider.check_analysis_statusを呼び出してステータスをチェックしてください。ステータスが SUCCESS と報告された後でも、結果が復号化されてプロバイダーのSnowflakeテーブルに書き込まれるまで、さらに時間がかかります。復号化されたすべてのデータが、結果テーブルに一度に追加されます。セグメントやアクティベーション ID の結果テーブルを定期的にチェックしてください。復号化タスクは60分後にタイムアウトします。タイムアウトした場合は、 provider.update_activation_warehouse を呼び出して、復号化に使用するウェアハウスのサイズを増やします。注釈
コンシューマーが承認した後にテンプレートを変更するには、以下の手順を実行する必要があります。実行しない場合、
provider.submit_analysis_requestは最後に承認されたバージョンのテンプレートを実行し続けます。
プロバイダーは、
provider.add_custom_sql_templateを呼び出してテンプレートを更新します。create_or_update_cleanroom_listingを再度呼び出す必要はありません。コンシューマーが
consumer.enable_templates_for_provider_runを呼び出します。コンシューマーが
consumer.approve_provider_activation_consentを呼び出します。テンプレートが更新され、プロバイダーアクティベーションが可能になります。
よくあるエラー
Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized- 何らかの理由で仮結果テーブルを生成できませんでした。テンプレートの SQL エラーか、テンプレートが明示的にテーブルを生成していない可能性があります。エラーの詳細をご覧ください。Query validation checks failed- アクティベーション・ポリシーにない列がテンプレートで使用されています。
例
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.
プロバイダーとコンシューマーのアクティベーション結果を表示する¶
アクティベーション結果の場所と形式¶
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.
注釈
プロバイダーのアクティベーション結果は、暗号化された形式でコンシューマーの localDB の仮テーブルに書き込まれます。結果はその後、プロバイダーのアカウントにコピーされ、復号化されてから保存されます。この余分な移動と復号化のステップにより、結果セットが大きい場合は遅延が発生する可能性があります。
プロバイダーのアクティベーション結果 は、プロバイダーのアカウントの SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY に保存されます。
コンシューマーのアクティベーション結果 は、コンシューマーのアカウントの SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY に保存されます。
これらのテーブルには以下の列があります：
- USER_ID:
JSON 形式の1行の結果。キーが列名、値がその行のその列の値。このオブジェクトはまた、テンプレートに渡される各引数の列を含みます。
- ACTIVATION_ID:
リクエストごとに一意な ID 。ID は、アクティベーションリクエストに成功した場合に返されます。この列でフィルターをかけると、同じアクティベーションのすべての結果を取得できます。また、複数の実行で同じセグメント名を再利用する場合は、 SEGMENT でフィルターをかけることができます。これは、
submit_analysis_requestまたはrun_activationが返すクエリリクエスト ID と同じです。- CLEANROOM_NAME:
クエリが実行されたclean roomの名前。
- CONSUMER:
(プロバイダーアクティベーションのみ) このアクティベーションを承認したコンシューマー。
- PROVIDER:
(コンシューマーアクティベーションのみ) このアクティベーションを承認したプロバイダー。
- SEGMENT:
アクティベーション実行時に割り当てる任意の文字列値。この列を使用すると、複数のクエリを実行した結果を結合できます。
- TIMESTAMP:
アクティビティが実行されたとき。
プロバイダーアクティベーションの例
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
...
プロバイダーまたはコンシューマーのアクティベーション結果を読み取る¶
適切な SQL コマンドを実行して、Snowflake アカウントにアクティベートされた結果を表示します：
プロバイダーアクティベーションの結果を表示
SELECT *
FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
[WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];
コンシューマーアクティベーションの結果を表示
SELECT *
FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
[WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];
各行のデータは、 USER_ID 列のオブジェクトに結合されます。次のようなクエリを使用して結果をフラット化できます：
-- 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 ;
最新の結果10行をSnowsightに表示する:
Snowsight にサインインします。
ナビゲーションメニューで Catalog » Database Explorer を選択します。
プロバイダーアクティベーションの場合
SAMOOHA_BY_SNOWFLAKE_LOCAL_DB»PUBLIC»Tables»PROVIDER_ACTIVATION_SUMMARYに移動します。コンシューマーアクティベーションの場合
SAMOOHA_BY_SNOWFLAKE_LOCAL_DB»PUBLIC»Tables»CONSUMER_DIRECT_ACTIVATION_SUMMARYに移動します。Data Preview を選択します。
サードパーティアクティベーション¶
サードパーティアクティベーションは、 サードパーティアクティベーションコネクタ を使用して、Snowflakeが承認したサードパーティのアカウントにクエリ結果をデポジットします。
サードパーティアクティベーションは、clean room UI でのみサポートされ、カスタムテンプレートは使用できません。
clean room UI 使用中のアクティベーションは、clean roomのアカウント がアクティベーション を許可する場合のみサポートされます。
clean room管理者は、サードパーティのアクティビティコネクタをサポートするように環境を構成し、許可されたコネクタを選択して、それらを構成してから、clean roomで使用する必要があります。
サードパーティアクティベーションは、コンシューマーとプロバイダーの両方が実行する分析をサポートします。
サポートされるテンプレート¶
以下のテンプレートは、サードパーティアクティベーションをサポートしています：
Audience Overlap & Segmentation
サードパーティアクティベーションを実装する¶
clean roomを作成または結合する: clean roomを作成または結合する際、 Configure Analysis & Query ステップの Activation Settings で、どの列を自分のアカウントにアクティベートされた結果に追加するかを指定します。
結果をのアクティベート
分析を実行します。
分析の実行後、Results » Activate を選択します。
Activation Hub で、アクティベートするサードパーティプロバイダーの名前を選択します。
プロバイダー固有の情報を入力します。たとえば、わかりやすい名前を指定したり、アクティベートする列を選択したりします。ページのツールチップには、そのプロバイダーの追加情報が表示されます。
Push Data を選択します。