Activating query results¶

アクティベーションの概要¶

プロバイダーまたはコンシューマーは、 アクティベーション と呼ばれるプロセスで、clean roomの外部にテンプレート結果を送信することができます。Snowflakeは3タイプのアクティビティをサポートしています：

プロバイダーアクティベーション、結果がプロバイダーのSnowflakeアカウントのテーブルにプッシュされます。
コンシューマーアクティベーション、結果がコンシューマーのSnowflakeアカウントのテーブルにプッシュされます。
サードパーティアクティベーション、プロバイダーまたはコンシューマーは、アクティベーションコネクタを介して、結果をLiveRamp やMeta Ads ManagerなどのSnowflakeが承認したサードパーティにプッシュします。

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 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 only
コンシューマーが実行	✅	✅	UI only

結果¶

プロバイダーのアクティベーション結果 は、 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 を選択します。
To learn how to view activated results, see プロバイダーとコンシューマーのアクティベーション結果を表示する.

アクティベーションのパフォーマンスは、誰が実行するかによっても、コンシューマーとプロバイダーのどちらのアクティベーションかによっても異なります。

重要

コンシューマーが初めて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;
```
Copy
$provider_account_data_sharing_id がプロバイダーのデータ共有アカウント識別子である場合
プロバイダー は以下のプロシージャを実行する必要があります：
```
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);
```
Copy
$consumer_account_data_sharing_id がコンシューマーのデータ共有アカウント識別子である場合

1.プロバイダー

標準的な方法でclean roomを作成します。

データセットをリンク付けします。また、プロバイダーは samooha_by_snowflake_local_db.library.temp_public_key テーブルを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 を呼び出して、復号化に使用するウェアハウスのサイズを増やします。

下記のように結果を表示します。

例

プロバイダーが自分の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 - アクティベーション・ポリシーにない列がテンプレートで使用されています。

例

プロバイダーとコンシューマーのアクティベーション結果を表示する¶

アクティベーション結果の場所と形式¶

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.

注釈

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.

プロバイダーのアクティベーション結果 は、プロバイダーのアカウントの 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>];

Copy

コンシューマーアクティベーションの結果を表示

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

Copy

各行のデータは、 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 ;

Copy

最新の結果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 で、どの列を自分のアカウントにアクティベートされた結果に追加するかを指定します。
結果をのアクティベート
1. 分析を実行します。
2. 分析の実行後、Results » Activate を選択します。
3. Activation Hub で、アクティベートするサードパーティプロバイダーの名前を選択します。
4. プロバイダー固有の情報を入力します。たとえば、わかりやすい名前を指定したり、アクティベートする列を選択したりします。ページのツールチップには、そのプロバイダーの追加情報が表示されます。
5. Push Data を選択します。