Snowflake Data Clean Room：提供商数据分析¶

本主题描述了在 Clean Room 中以编程方式创建、共享和运行分析所需的提供商和使用者流程。提供商端的数据分析允许使用者查看有关提供商数据集的汇总见解，而无需联接其数据。

本主题中描述的流程包含以下任务：

提供商：
1. 创建新的 Clean Room。
2. 安全地将数据集关联到 Clean Room。
3. 添加策略，管理哪些列可以联接并在分析中使用。
4. 启用预定义的分析模板。
5. 与使用者共享。
使用者：
1. 安装由提供商共享的 Clean Room。
2. 检查 Clean Room 中提供的模板。
3. 使用该模板在 Clean Room 中运行分析。

先决条件¶

您需要两个独立的 Snowflake 账户才能完成此流程。使用第一个账户执行提供商的命令，然后切换到第二个账户执行使用者的命令。

提供商¶

备注

应在提供商账户的 Snowflake 工作表中运行以下命令。

设置环境¶

在利用开发者 APIs 使用 Snowflake Data Clean Room 之前，请执行以下命令来设置 Snowflake 环境。如果您没有 SAMOOHA_APP_ROLE 角色，请联系账户管理员。

use role samooha_app_role;
use warehouse app_wh;

Copy

创建 Clean Room¶

为 Clean Room 创建名称。输入新的 Clean Room 名称，避免与现有 Clean Room 名称冲突。请注意，Clean Room 名称只能是 字母数字。除空格和下划线外，Clean Room 名称不能包含特殊字符。

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

Copy

您可以使用上面设置的 Clean Room 名称创建新的 Clean Room。如果上面设置的 Clean Room 名称已经作为现有 Clean Room 存在，则此过程将失败。

运行此过程大约需要 45 秒。

provider.cleanroom_init 的第二个实参是 Clean Room 的分发。它可以是 INTERNAL 或 EXTERNAL。出于测试目的，如果您将 Clean Room 共享给同一组织中的账户，则可以使用 INTERNAL 绕过自动安全扫描，该扫描必须在将应用程序包发布给协作者前进行。但是，如果要将此 Clean Room 共享给其他组织中的账户，则必须使用 EXTERNAL Clean Room 分发。

call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Copy

要查看安全扫描的状态，请使用：

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Copy

创建 Clean Room 之后，必须先设置其发布指令，然后才能与协作者共享。但是，如果您的分发设置为 EXTERNAL，则必须先等待安全扫描完成，然后再设置发布指令。您可以在扫描运行时继续运行其余步骤，并在执行 provider.create_cleanroom_listing 步骤之前返回此处。

要设置发布指令，请调用：

call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Copy

关联数据集并设置数据集的联接策略¶

将 Snowflake 表关联到 Clean Room。浏览 Snowflake 账户中的表列表，并以数组形式输入完全限定的表名称 (Database.Schema.Table)。该过程在 Clean Room 内创建表的安全视图，自动使 Clean Room 可以访问表，从而无需制作表副本。

call samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS']);

Copy

备注

如果即使表存在，此步骤也不起作用，则很可能 SAMOOHA_APP_ROLE 角色还没有被授予访问该表的权限。如果是，请切换到 ACCOUNTADMIN 角色，对数据库调用以下过程，然后切换回来执行流程的剩余部分：

use role accountadmin;
call samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
use role samooha_app_role;

Copy

如果要查看已添加到 Clean Room 的数据集，请调用以下过程。

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Copy

您可以使用以下过程查看关联到 Clean Room 的数据集：

select * from SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS limit 10;

Copy

指定使用者在 Clean Room 内运行模板时可以联接哪些列。应对身份列（如电子邮件）调用此过程。联接策略是“仅替换”，因此如果再次调用函数，新的联接策略会完全替换之前设置的联接策略。

call samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:HEM']);

Copy

如果要查看已添加到 Clean Room 的联接策略，请调用以下过程。

call samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Copy

向 Clean Room 添加分析模板¶

使用预先指定模板的名称标识符添加预先指定的模板列表。在此流程中，您添加的是预定义模板，该模板允许您以安全且经过提供商批准的方式，在提供商批准的列上对提供商数据集进行数据分析。

call samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_provider_data_analysis']);

Copy

如果要查看 Clean Room 中当前有效的模板，请调用以下过程。

备注

请注意，所有系统定义的预设模板均已加密，默认情况下不可查看。但是，您添加的所有自定义模板均可见。

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Copy

如果需要，也可以将任何添加到 Clean Room 的模板清除。请参阅提供商 API 参考指南，了解更多详情。

对每个表设置列策略¶

显示关联的数据以查看表中存在的列。要查看前 10 行，请调用以下过程。

select * from SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS limit 10;

Copy

为每个表和模板组合设置使用者可以分组、汇总（例如 SUM 或 AVG）和通常用于分析的列。这提供了灵活性，使同一个表可以根据基础模板允许不同的列选择。只有在添加模板后才可调用此函数。

请注意，列策略是 仅替换，因此如果再次调用函数，新的列策略会完全替换之前设置的列策略。

不应将列策略用于 email、HEM 或 RampID 等身份列，因为您不希望使用者能够按这些列进行分组。在生产环境中，系统会智能推断 PII 列并阻止此操作，但在沙盒环境中此功能不可用。只应将其用于您希望使用者能够汇总和分组的列，如状态、年龄段、渠道或活动天数。

call samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:STATUS', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_provider_data_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:REGION_CODE']);

Copy

如果要查看已添加到 Clean Room 的列策略，请调用以下过程。

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Copy

使用者¶

备注

应在使用者账户的 Snowflake 工作表中运行以下命令。

设置环境¶

在利用开发者 APIs 使用 Snowflake Data Clean Room 之前，请执行以下命令来设置 Snowflake 环境。如果您没有 SAMOOHA_APP_ROLE 角色，请联系账户管理员。

use role samooha_app_role;
use warehouse app_wh;

Copy

安装 Clean Room¶

安装 Clean Room 共享后，可以使用以下命令查看可用的 Clean Room 列表。

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

Copy

为提供商与您共享的 Clean Room 命名。

set cleanroom_name = 'Provider Data Analysis Demo Clean room';

Copy

以下命令将 Clean Room 安装到具有相关提供商和所选 Clean Room 的使用者账户中。

运行此过程可能需要大约 45 秒。

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

Copy

安装了 Clean Room 后，提供商必须在启用前完成提供商侧的 Clean Room 设置。您可以通过以下函数查看 Clean Room 的状态。启用 Clean Room 后，您应该能够运行下面的“运行分析”命令。启用 Clean Room 通常需要大约 1 分钟。

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

Copy

运行分析¶

现在，Clean Room 已经安装完毕，您可以使用“run_analysis”命令运行由提供商提供给 Clean Room 的分析模板。您可以在以下各节中看到如何确定每个字段。

备注

在运行分析之前，您可以更改仓库规模；如果表较大，也可以使用新的、更大的仓库规模。

-- Example run analysis procedure with single provider dataset

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,                    -- cleanroom
  'prod_provider_data_analysis',      -- template name

  [],                                 -- consumer tables - this is empty since this template operates only on provider data
  
  ['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS'],    -- the provider table we want to carry out analysis on

  object_construct(                        -- The keyword arguments needed for the SQL Jinja template
      'dimensions', ['p.STATUS'],          -- Group by column

      'measure_type', ['COUNT'],           -- Aggregate function you want to perform like COUNT, AVG, etc.

      'measure_column', ['p.DAYS_ACTIVE'], -- The column that you want to perform aggregate function on

      'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Acts as a filter to consider only certain records
                                                      -- $$ is used to pass string literals
    )
);

Copy

对于需要在筛选“where_clause”、“dimensions”或“measure_columns”的数据集中引用的每一列，可以使用 p. 引用提供商表中的字段，使用 c. 引用使用者表中的字段。对多个提供商表，可以使用 p2、p3 等；对多个使用者表，可以使用 c2、c3 等。

请注意： 在此流程中，您可以看到 Clean Room 启用了提供商数据分析，这意味着您可以在 Clean Room 中对提供商数据集进行安全且专用的数据分析。您无需关联数据集。请参阅端到端：重叠分析流程，查看双方可以关联数据集进行联合分析的示例。

如何确定 run_analysis 的输入¶

要运行分析，需要向 run_analysis 函数传递一些参数。本节将向您展示如何确定要传入的参数。

模板名称

首先，您可以通过调用以下过程来查看支持的分析模板。

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

Copy

要使用模板运行分析，您尚不清楚此时要指定哪些实参以及需要哪些类型。因此，如果模板是自定义模板，您可以使用这些信息直观地查看模板。

备注

请注意，所有系统定义的预设模板均已加密，默认情况下不可查看。但是，您添加的所有自定义模板均可见。

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_provider_data_analysis');

Copy

这通常还可以包含大量不同的 SQL Jinja 参数。以下功能可解析 SQL Jinja 模板，并将需要在 run_analysis 中指定的实参提取到方便的列表中。

备注

请注意，所有系统定义的预设模板均已加密，因此，此函数不会获取这些模板的实参。但是，您可以检索自定义模板的参数。

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_provider_data_analysis');

Copy

数据集名称

如果要查看提供商已添加到 Clean Room 的数据集名称，请调用以下过程。请注意，由于 Clean Room 的安全属性，您无法查看提供商添加到 Clean Room 的数据集中的数据。

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

Copy

维度和度量列

在运行分析时，您可能希望对某些列进行筛选、分组和汇总。如果要查看提供商已添加到 Clean Room 的列策略，请调用以下过程。

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Copy

常见错误

如果运行分析后出现 Not approved: unauthorized columns used 错误，您可能需要再次查看提供商设置的联接策略和列策略。

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Copy

也有可能是您的隐私预算已耗尽，因此无法再执行任何查询。您可以使用以下命令查看剩余的隐私预算。预算会每天重置，Clean Room 提供商也可以将其重置。

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

Copy

您可以通过以下 API 检查 Clean Room 是否启用了差分隐私：

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);

Copy

Snowflake Data Clean Room：提供商数据分析¶

先决条件¶

提供商¶

设置环境¶

创建 Clean Room¶

跨区域共享¶

关联数据集并设置数据集的联接策略¶

向 Clean Room 添加分析模板¶

对每个表设置列策略¶

与使用者共享¶

使用者¶

设置环境¶

安装 Clean Room¶

运行分析¶

如何确定 run_analysis 的输入¶