Snowflake Data Clean Room：以提供商身份运行分析

本主题提供了一个示例，说明提供商创建和共享 Clean Room，然后在使用者链接其数据后在 Clean Room 中运行分析。提供商在 Clean Room 中执行分析的过程通常称为“provider-run analysis”。

重要

如果使用者允许提供商对模板运行分析，则由使用者而不是提供商为提供商分析所消耗的 credit 付费。在使用者允许提供商运行分析后，使用者必须卸载 Clean Room 以停止产生费用。

如果使用者想要获取提供商在特定时间段内使用的 credit 数量估值，他们可以执行以下查询，其中 -5 返回提供商过去 5 天的计算使用量估值：

SELECT * FROM table(samooha_by_snowflake_local_db_dev.public.udtf(-5));
Copy

此示例的流程在提供商执行的操作和使用者执行的操作之间切换。此流程包括以下操作：

  1. 提供商：

    a. 为重叠研究创建 Clean Room。

    b. 将数据集链接到 Clean Room。

    c. 添加策略，管理哪些列可以联接并在分析中使用。

    d. 启用预定义的重叠分析模板。

    e. 与使用者共享 Clean Room。

    f. 配置 Clean Room 以允许自己运行分析。

    g.配置 Clean Room 以防止使用者运行分析。在此示例中，使用者仅充当数据提供商。

    h. 与已安装 Clean Room 的使用者运行重叠研究。

  2. 使用者：

    a. 安装提供商共享的 Clean Room。

    b. 将数据集链接到 Clean Room。

    c. 对数据集设置安全策略。

    d. 批准提供商在 Clean Room 中运行分析。

先决条件

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

提供商

使用提供商账户中的 Snowflake 工作表执行本节中的命令。

设置环境

在使用 Developer APIs 之前，您需要承担 SAMOOHA_APP_ROLE 角色，并指定用来执行 APIs 的仓库。如果您没有 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 名称不能包含特殊字符。

首先，执行以下命令，为示例 Clean Room 设置 Clean Room 名称：

SET cleanroom_name = 'Provider Run Analysis Overlap';
Copy

如果已存在具有指定名称的 Clean Room，则此过程将失败。

运行此过程所需时间可能较长，通常约为半分钟。

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_or_update_cleanroom_listing 步骤之前返回此处。

要设置发布指令，请执行以下命令：

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

设置数据集的联接策略

要确定可以将哪些列用作联接策略，您可以查看数据集以确定 PII 列。例如，要查看表的前 10 行，请执行以下查询：

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;
Copy

然后，指定使用者在 Clean Room 内运行模板时可以联接哪些列。应对身份列（如电子邮件）调用此过程。如果再次设置联接策略，则之前设置的联接策略将被新策略完全取代。

CALL samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);
Copy

如果要查看已添加到 Clean Room 的联接策略，请执行以下命令：

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);
Copy

将分析模板添加到 Clean Room

模板确定可在 Clean Room 中执行的分析类型。在此示例中，您使用预定义的模板，该模板允许协作者对提供商的数据集和使用者的数据集之间的重叠运行分析。

请注意，此模板以原生方式实现差分隐私提供的额外安全保证。

CALL samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_overlap_analysis']);
Copy

对每个表设置列策略

在对表设置列策略之前，请执行查询以显示表的列。例如，要查看前 10 行，请执行以下命令：

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;
Copy

对于每个表和模板组合，设置分析者可以在分析中使用的列，例如可以分组或汇总的列。这提供了灵活性，使同一个表可以根据基础模板允许不同的列选择。等到添加模板之后，再在表上设置列策略。

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

不应将列策略用于 email、HEM 或 RampID 等身份列，因为您不希望分析者能够按这些列进行分组。在生产环境中，Snowflake 会推理 PII 列并阻止此操作，但在沙盒环境中无法进行此推理。它应该只用于您希望使用者能够汇总和分组的列，例如 Status、Age Band、Region Code 或 Days Active。

要为模板/表组合设置列策略，请执行以下命令：

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS', 
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE', 
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE']);
Copy

如果要查看已添加到 Clean Room 的列策略，请执行以下命令：

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);
Copy

与使用者共享

最后，通过添加数据使用者的 Snowflake 账户定位器和账户名称，将数据使用者添加到 Clean Room，如下所示。Snowflake 账户名称的格式必须为 <ORGANIZATION>.<ACCOUNT_NAME>。

备注

在执行以下命令之前，请确保您已使用 provider.set_default_release_directive 设置发布指令。您可以通过执行以下命令来查看新的可用版本和补丁：

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_Provider_Run_Analysis_Overlap;
Copy

要与使用者共享 Clean Room，请执行以下命令：

CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing($cleanroom_name);
Copy

对于多个使用者账户定位器，可以用逗号分隔的字符串形式传递到 provider.add_consumers 函数中，也可以分别调用 provider.add_consumers。

如果要查看已添加到 Clean Room 的使用者，请执行以下命令：

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);
Copy

配置分析运行者

备注

您必须在您与使用者共享 Clean Room 之后，但在使用者安装 之前，使用本部分中的 APIs。如果您在使用者已安装 Clean Room 后更改 Clean Room 的配置，则使用者必须重新安装 Clean Room。

在此示例中，您将配置 Clean Room，以便提供商可以运行分析，但使用者不能。这意味着使用者只能添加数据集并设置安全策略。

要配置 Clean Room，以便提供商可以运行分析，请执行以下命令：

CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);
Copy

备注

尽管未用于此示例，但提供商可以执行 provider.disable_provider_run_analysis 命令，以颠倒配置并防止自己运行分析。

默认情况下，用户可以在 Clean Room 中运行分析。要配置 Clean Room 以防止使用者运行分析，请执行以下命令：

CAll samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);
Copy

备注

尽管未用于此示例，但提供商可以执行 provider.enable_consumer_run_analysis 命令，以颠倒配置并允许使用者运行分析。

使用者

您现在正转为担任 Clean Room 的使用者。使用使用者账户中的 Snowflake 工作表执行本节中的命令。

设置环境

在使用 Developer APIs 之前，您需要承担 SAMOOHA_APP_ROLE 角色，并指定用来执行 APIs 的仓库。如果您没有 SAMOOHA_APP_ROLE 角色，请联系账户管理员。

执行以下命令以设置您的环境：

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;
Copy

安装 Clean Room

在安装提供商与您共享的 Clean Room 前，为 Clean Room 命名。

SET cleanroom_name = 'Provider Run Analysis Overlap';
Copy

以下命令将在使用者账户中安装 Clean Room：

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

关联数据集

现在，您可以将一些数据集链接到 Clean Room。提供商在 Clean Room 中运行分析时将使用此数据。

CALL samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

备注

如果即使表存在此步骤也不起作用，则包含该表的数据库可能未注册。要注册数据库，请作为具有 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.consumer.view_consumer_datasets($cleanroom_name);
Copy

为数据集设置安全联接策略（可选）

在本部分中，您将指定在 Clean Room 中执行分析时允许提供商连接哪些列。您应该对 email 等身份列执行以下命令。联接策略是“仅替换”，因此如果再次调用函数，新的联接策略会完全替换之前设置的联接策略。如果不想为使用者表设置联接策略，则不需要这样做。

CALL samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);
Copy

为数据集设置列策略（可选）

对于每个表和模板组合，设置提供商可以在分析中使用的列，例如可以分组或汇总的列。这提供了灵活性，使同一个表可以根据基础模板允许不同的列选择。等到添加模板后，才能为表设置列策略。如果您不想为使用者表设置列策略，则不需要这样做。

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

不应将列策略用于 email、HEM 或 RampID 等身份列，因为您不希望提供商能够按这些列进行分组。在生产环境中，Snowflake 会推理 PII 列并阻止此操作，但在沙盒环境中无法进行此推理。它应该只用于您希望提供商能够汇总和分组的列，例如 Status、Age Band、Region Code 或 Days Active。

要为模板/表组合设置列策略，请执行以下命令：

CALL samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name, [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE', 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE'
]);
Copy

允许提供商运行分析

使用者需要明确批准提供商逐个模板运行分析。如果没有此批准，则即使提供商配置了 Clean Room 以便运行分析，他们也无法运行分析。

首先，您可以检查提供商是否已配置 Clean Room，以便他们可以执行分析。

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
Copy

接下来，您可以执行以下命令以允许提供商运行分析。您必须为您希望提供商能够使用的每个模板执行该命令。您应该在设置联接和列策略 之后 给予批准，以防止提供商对未受保护的数据运行分析。

CALL samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis']);
Copy

提供商

现在，您正在切换回提供商账户，以便在 Clean Room 中运行分析。使用提供商账户中的 Snowflake 工作表执行本节中的命令。

访问来自使用者的信息

以提供商身份运行分析会处理使用者账户中的数据。要检索分析结果，提供商需要访问从使用者返回到提供商的信息。执行以下命令以访问来自使用者的信息：

CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);
Copy

运行分析

提供商在要运行分析时执行 provider.submit_analysis_request 命令。

CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
    $cleanroom_name, 
    '<CONSUMER_ACCOUNT>',
    'prod_overlap_analysis', 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    object_construct(       
      'dimensions', ['c.REGION_CODE'],        
      'measure_type', ['AVG'],           
      'measure_column', ['c.DAYS_ACTIVE'],
      'where_clause', 'p.hem=c.hem'                                         
    ));
Copy

provider.submit_analysis_request 命令返回请求标识符。您 必须保存此标识符，以便检查分析请求的状态并检索分析结果。例如，您可以执行以下操作，将标识符保存到局部变量中：

SET request_id = '<REQUEST_ID>';
Copy

提交要执行分析的请求后，您可以通过执行以下命令来查看请求的状态。请注意，首次执行命令时可能会有延迟。

CALL samooha_by_snowflake_local_db.provider.check_analysis_status(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);
Copy

备注

如果此 API 失败，请确保您配置了 Clean Room，在您以使用者身份安装 Clean Room 之前 允许提供商运行分析。如果在使用者安装 Clean Room 后配置 Clean Room，则使用者必须重新安装 Clean Room。

当 provider.check_analysis_status 命令返回的状态为 COMPLETED 时，您可以通过执行以下命令来检索分析结果：

CALL samooha_by_snowflake_local_db.provider.get_analysis_result(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);
Copy
语言: 中文