基本的使用者运行数据分析¶

设置环境¶

To use the API, you must use a warehouse that SAMOOHA_APP_ROLE has privileges in. app_wh is one of a number of warehouses with access to the API. Choose the warehouse that is appropriate for your needs. (You can also use your own warehouse, if you choose.)

需要 samooha_app_role 角色才能访问 API。

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

创建 Clean Room¶

下一步是创建一个新的 Clean Room。这可以通过一次 API 调用来完成，该调用需要指定 Clean Room 是供内部还是外部使用。内部 Clean Room 仅允许同一组织内的使用者访问；外部 Clean Room 可供组织外的使用者使用。对于这两种类型，使用者都必须被邀请才能访问 Clean Room。

当对外部 Clean Room 执行某些操作时，会触发额外的安全检查。发生这种情况时，您必须调用 provider.view_cleanroom_scan_status 查看安全扫描完成情况，然后才能继续进行下一步操作。

以下示例演示如何创建内部 Clean Room：

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

将数据链接到 Clean Room 中¶

提供商和使用者都可以将表、视图以及 其他受支持的数据对象 *链接*（导入）到 Clean Room 中。当您链接数据时，API 会在 Clean Room 内创建一个基于指定源对象的视图。但是，在所有 Clean Room 过程中，您应当通过源对象名称而非内部视图名称来引用已链接对象。

任何 Clean Room 协作者都不能直接访问链接到 Clean Room 的数据，只能通过 Clean Room 内的模板来访问。

在将对象链接到 Clean Room 之前，必须先 注册 该对象。注册对象会授予 SAMOOHA_APP_ROLE 对该对象的相应访问权限。您可以直接注册一个对象，也可以注册一个包含对象（如数据库或架构）以访问子对象。您可以在 UI 或 API 中注册对象，注册在账户级别进行，而非 Clean Room 级别。在 UI 中注册更易于执行和管理。注册对象后，该对象可供账户中的任何 Clean Room 链接使用。了解有关注册的更多信息。

下面的示例显示如何链接来自示例数据库 SAMOOHA_SAMPLE_DATABASE 中的 CUSTOMERS 表。当您在账户中安装 Clean Room 环境时，该数据库会自动注册，因此您无需再注册。您可以随时在 Clean Room 中链接或取消链接对象，操作结果会迅速同步给所有协作者。

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

设置联接策略¶

如果您向 Clean Room 添加允许使用者在数据上进行联接的模板，则应为数据设置 Clean Room 联接策略。Clean Room 联接策略指定在协作者运行的查询中哪些列 可以 用于联接。如果您未对数据设置任何联接策略，则默认所有列均可联接。受联接策略保护的列无法被投影。您自己的联接策略不会约束您自己的查询。

Clean Room 支持对已链接的数据设置 一些数据策略。这些策略类似于 Snowflake 的等效策略，但并不完全相同，并且仅应用于内部视图，不作用于源数据。在源数据上设置的任何 Snowflake 策略都会传播到您链接数据时创建的视图。Clean Room 策略仅设置在已链接的数据上，而不影响源数据。

您只能对自己链接的数据设置策略；不能对任何其他方的数据设置策略。

以下示例显示如何设置一个联接策略，使已链接表中的两列可用于联接：

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

了解有关联接策略的更多信息。

向 Clean Room 添加模板¶

Clean Room 模板是一个有效的 JinjaSQL 模板，它几乎总是评估为 SQL 查询。模板（有时也称为 分析）可以由调用者传入实参，并且可以访问已链接到 Clean Room 的任何数据。提供商和使用者都可以向 Clean Room 添加模板并运行它们。

Snowflake 提供了一些标准模板，但其中大多数仅可在 UI 中使用。因此，您很可能需要为使用者（或您自己）编写自定义模板，以便通过 API 运行。

默认情况下，只有使用者才能运行模板。如果 提供商想要运行模板，则必须征得使用者的许可。同样，如果 使用者想要上传模板，也必须征得提供商的许可。

有关创建自定义模板的更多信息，请阅读 向 Clean Room 添加自定义模板 和 自定义 Clean Room 模板参考。

以下示例显示如何将 Snowflake 提供的模板添加到 Clean Room 中：

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

设置列策略¶

Clean room 列策略指定在协作者运行的查询中，您表中的哪些列可以被投影。列策略同时与列和模板相关联，因此可以针对不同模板定义不同列为可投影。模板必须存在于 Clean Room 中，然后才能为该模板设置列策略。

列策略和所有策略一样，是 覆盖型的；这意味着设置列策略会完全覆盖该账户之前设置的任何列策略。提供商和使用者都可以在自己的数据上设置列策略。如果您没有为自己的数据指定列策略，则所有列均可投影。了解有关列策略的更多信息。

以下示例显示如何允许从之前链接的 Clean Room 示例数据库中投影四列：

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']);

与使用者共享¶

提供商定义哪些使用者可访问 Clean Room。指定的使用者在 Clean Room 发布之前无法访问。只有由提供商添加的账户才能访问 Clean Room。使用者不能与其他使用者共享 Clean Room。

以下示例显示两名使用者如何共享一个 Clean Room。该过程使用两组并行的、以逗号分隔的列表，即使用者账户定位器和 使用者数据共享账户 IDs。

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

设置默认版本¶

Clean Room 是版本控制的原生应用程序。某些操作（如向 Clean Room 添加代码）会生成应用程序的新补丁版本。使用者必须在其账户中安装 Clean Room。他们安装的版本基于您指定的默认版本号。如果您稍后发布了 Clean Room 的新版本并增加默认版本号，则使用者安装的所有版本都将自动更新，新安装的版本将默认使用新版本。阅读有关 Clean Room 版本控制的更多信息。

以下示例显示如何将 Clean Room 的默认版本设置为 V1.0.0，这是 Clean Room 的初始版本（如果您尚未上传任何代码）：

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

发布 Clean Room¶

按照以下示例发布或重新发布 Clean Room。首次调用此过程时，会使 Clean Room 对您已共享的所有使用者可见并可安装。每当您进行重大更改时，例如更新默认版本或对 Clean Room UI 进行特定更改时，都应调用此过程。

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

现在，使用者即可安装 Clean Room、链接数据、设置策略并运行模板，如下所述。

设置环境¶

与提供商一样，使用者也必须使用 SAMOOHA_APP_ROLE 可以访问的 仓库。但是，与提供商不同的是，使用者可以直接使用 SAMOOHA_APP_ROLE 角色获得完整的 API 访问权限，或者该账户中的 Clean Room 管理员可以授予一个更有限的角色，使使用者仅能运行部分 API。这种受限角色有时被统称为“运行角色”，由具备完整 Clean Room 权限的用户授予。阅读如何授予受限 API 访问权限。

运行角色不允许安装 Clean Room，因此您必须使用 SAMOOHA_APP_ROLE，如以下示例所示：

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

安装 Clean Room¶

以下代码片段显示了如何列出您已被邀请安装的所有 Clean Room：

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

安装提供商与您共享的 Clean Room，如以下示例所示。安装 Clean Room 时，必须指定提供商的账户定位器。

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

添加数据并设置策略¶

如果 Clean Room 模板允许使用者在查询中包含自己的数据，则使用者需要注册数据、链接数据并设置策略，方式与提供商类似。请务必使用 consumer 版本的这些过程，如以下示例所示：

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
$cleanroom_name,
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MY_DATABASE.PUBLIC.EXPOSURES']);

提供商的联接策略显示了哪些提供商列可以用于联接。此示例显示如何检查您可以联接的提供商列：

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

提供商需要得到使用者的批准才能在 Clean Room 中运行模板因此，大多数使用者不会费心为自己链接的表设置策略。

但是，我们仍建议您考虑添加策略，以防提供商日后需要请求才能运行模板，因为您可能会在那时忘记添加合适的策略。如果您未在自己的数据上设置联接或列属性，则所有列都是可联接和可投影的。

运行分析¶

在运行模板之前，您通常需要检查模板以查看其功能以及可接受的变量，然后检查 Clean Room 中有哪些提供商的表可用。

-- View the templates available in this clean room.
-- Also shows the template code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);