Activating query results¶

激活概述¶

提供商或使用者可以通过名为激活的流程将模板结果发送到 Clean Room 外。Snowflake 支持三种类型的激活：

提供商激活，结果将推送到提供商的 Snowflake 账户中的表中。
使用者激活，结果将推送到使用者的 Snowflake 账户中的表中。
第三方激活，即提供商或使用者通过激活连接器将结果推送给 Snowflake 批准的第三方，例如 LiveRamp 或 Meta Ads Manager。

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 中启用 Cross-Cloud Auto-Fulfillment。

提供商和使用者激活¶

您可以配置 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 时，在 Activation Settings 下的 Configure Analysis & Query 步骤中，指定应将哪些列添加到激活到您账户的结果中。

2.运行模板并激活结果

要运行与分析相关的激活，请完成以下步骤：

运行分析。
After running an analysis, select 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 分钟，从而建立数据管道。每位使用者每个 Clean Room 只需要执行此操作一次。在此之前，即使激活成功，数据也不会出现在提供商的账户中。

使用者可以通过以下方式将结果推送到自己的 Snowflake 账户。

提供商

按照标准 Clean Room 创建 Clean Room、链接数据集并设置联接策略。

选择支持的 Snowflake 标准模板，或向 Clean Room 添加自定义激活模板。如果要在 UI 中使用此 Clean Room，则必须提供一个包含正确激活字段的 Web 表单，如模板文档中所述。

通过调用 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.

通过调用 consumer.run_activation 运行激活，将最后一个参数设置为 TRUE 表示使用者激活。

查看结果，如下所述。

示例

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 标准模板，或向 Clean Room 添加自定义激活模板。如果要在 Clean Room UI 中使用此 Clean Room，则必须提供 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.

通过调用 consumer.run_activation 运行激活，将最后一个实参设置为 FALSE 表示提供商激活。

备注

激活数据的加密版本将在使用者账户的 SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY 表中存储 28 天。超过 28 天的数据将从使用者账户中删除。

3.提供商

使用者首次向您的账户激活数据时，您必须在使用者激活数据后约 30 分钟内登录该账户的 Clean Room UI。之后，数据将出现在您的账户中。每位使用者账户每个 Clean Room 只需要执行此操作一次。之后，同一使用者在同一 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 添加自定义激活模板。如果要在 UI 中使用此 Clean Room，则必须提供一个包含正确字段的 Web 表单以支持激活，如模板文档中所述。

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 格式的结果，其中，密钥是列名称，值是该行中该列的值。该对象还包含传递到模板的每个实参的列。
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

在 Snowsight 中查看最新 10 行结果：

Sign in to Snowsight.

In the navigation menu, select Catalog » Database Explorer.

For provider activation navigate to SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY.

For consumer activation navigate to SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY.

选择 Data Preview。

第三方激活¶

第三方激活存款查询会导致 Snowflake 批准的第三方的账户使用第三方激活连接器。

仅 Clean Room UI 支持第三方激活，不支持使用自定义模板。

仅当 Clean Room 账户允许激活时支持在使用 Clean Room UI 时激活。

Clean Room 管理员必须将环境配置为支持第三方激活连接器，选择允许的连接器并对其进行配置，然后才能在任何 Clean Room 中使用它们。

第三方激活支持使用者和提供商运行的分析。

支持的模板¶

以下模板支持第三方激活：

Audience Overlap & Segmentation

实施第三方激活¶

创建或联接 Clean Room： 创建或联接 Clean Room 时，在 Activation Settings 下的 Configure Analysis & Query 步骤中，指定应将哪些列添加到激活到您账户的结果中。
激活结果：
1. 运行分析。
2. After running an analysis, select Results » Activate.
3. 在 Activation Hub 下，选择要激活到的第三方提供商的名称。
4. 提供特定于提供商的信息。这可以提供描述性名称或选择要激活的列。页面上的工具提示应为该提供商提供更多信息。
5. 选择 Push Data。