Snowflake Data Clean Rooms 开发者指南¶

本页为想要以编程方式在 Snowflake 中创建或管理 Clean Room 或模板的用户提供了一些指南。

Snowflake 公开存储过程，使您能够开发应用程序，从而创建或控制 Clean Room。这些存储过程可在任何可以访问与您的 Clean Room 环境关联的 Snowflake 账户的界面中运行，包括 Snowsight 笔记本或工作表以及 Snowflake CLI。可以用 Snowflake 界面支持的 SQL 或任何语言来调用这些过程。

设置您的环境¶

开发工具¶

以下是 Clean Room 的主要开发者工具：

编码环境： 任何可以在您的 Snowflake 账户中运行存储过程的编码环境都可以运行。大多数开发者使用 Snowsight 中的工作表（基于浏览器的工具）或 Snowflake CLI。
** Clean Room UI：** 使用 Clean Room UI 配置、管理或创建 Clean Room。大多数 Clean Room 分析师使用的是 UI 而不是代码，因此在 UI 中查看和测试 Clean Room 的体验可能会很有用。此外，还有一些功能仅可在 Clean Room UI 中使用。
Snowsight 可用于浏览数据库和其他对象以及搜索对象。

编码设置¶

所需角色和仓库¶

Clean Room API 需要 SAMOOHA_APP_ROLE 角色才能完全访问 API。请您的 Clean Room 管理员授予您完整的 API 访问权限。

Clean Room 还支持创建可以访问 API 过程子集的角色。

您必须使用仓库中 SAMOOHA_APP_ROLE 可以使用的 Clean Room API。app_wh 是众多可以访问 API 的仓库之一。根据您的需求选择合适的仓库。

-- Set up environment.
USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

-- Call your clean rooms API functions.
...

Copy

如果您使用任何其他仓库，请务必授予该仓库的 SAMOOHA_APP_ROLE 使用权：

GRANT USAGE ON WAREHOUSE <your warehouse> TO SAMOOHA_APP_ROLE;`

Copy

关于 Clean Room API¶

Snowflake Data Clean Rooms 公开了一组允许提供商创建、配置和共享 Clean Room 的存储过程。支持 Snowflake 过程的任何命令行环境都可以访问这些过程，包括笔记本、工作簿和 Snowflake CLI。您可以使用任何支持存储过程的语言使用 Clean Room API。这里的文档显示了 SQL 用法，但您也可以使用 Python 或任何其他支持的语言。

过程存在于以下架构中：

samooha_by_snowflake_local_db.provider – 特定于提供商的过程。这些过程只能在当前账户中创建的 Clean Room 上调用。
samooha_by_snowflake_local_db.consumer – 特定于使用者的过程。这些过程只能在当前账户受邀作为使用者的 Clean Room 上调用。
samooha_by_snowflake_local_db.library – Clean Room 创建者（提供商）或 Clean Room 协作者（使用者）调用的一般过程。（这些都记录在提供商和使用者参考页面中。）

有些过程既有提供者版本，也有使用者版本。结果符合架构：例如，provider.view_cleanrooms 列出了您作为提供商的当前账户中的所有 Clean Room，而 consumer.view_cleanrooms 列出了您作为使用者的当前账户中的所有 Clean Room。

关于 API 过程中的 Clean Room 名称¶

许多 Clean Room API 过程都需要 cleanroom_name 实参。

如果 Clean Room 是 使用 API 创建的，则使用 Clean Room 名称。如果用作包名称的一部分，请将空格替换为下划线：

-- Spaces work here:
CALL samooha_by_snowflake_local_db.provider.describe_cleanroom('my code created clean room');

-- Underscores required here:
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_my_code_created_clean_room;

Copy

如果 Clean Room 是 使用 Clean Room UI 创建的，则使用 Clean Room ID。

您可以通过调用 describe_cleanroom 或 view_cleanrooms 查看 Clean Room 名称和 ID。

设置账户、用户和角色¶

You aren't required to use the clean rooms UI to develop clean rooms: most clean room functionality is available using stored procedures. However, a few features are available only in the UI, and some are faster to perform in the UI. And because many users use the UI exclusively, it's important to see how your clean room behaves in the UI, especially if you create a user configuration web form for a clean room that you create. Therefore, you should ask a clean room administrator to add you as a clean room manager or higher in the appropriate clean room accounts.

Depending on your use case, you might also want to set up an additional Snowflake account in different web hosting regions to test cross-cloud behavior.

对测试的 Snowflake 账户进行有意义的命名，以表明其典型用法：例如，“使用者账户”、“提供商账户”和“跨云账户”。当您有多个测试账户并且需要知道要登录哪个账户时，这会有所帮助。

Internal testing clean rooms¶

您可以使用相同的 Snowflake 账户，同时作为提供商和使用者，从而测试 Clean Room 的开发。这称为 内部测试 Clean Room。要创建内部测试 Clean Room，只需将提供商账户作为唯一使用者传递给 provider.add_consumers 即可。使用同一个账户同时担任提供商和使用者可以方便地进行快速功能测试，但请注意内部测试 Clean Room 的以下限制：

与提供商的账户共享 Clean Room 后，不能与任何其他账户共享，并且该 Clean Room 将始终是内部测试 Clean Room。
内部测试 Clean Room 不支持以下功能：
- consumer.view_cleanrooms 未显示任何内部测试 Clean Room。
- 提供商激活
- 提供商运行分析
- 装载或查看请求日志（provider.mount_request_logs_for_all_consumers 或 provider.view_request_logs）
- 使用者自定义模板
- 多提供商分析
- 自定义模板（提供商或使用者）
- 差分隐私
如果您想测试内部测试 Clean Room 不支持的功能，则必须设置单独的提供商和使用者 Snowflake 账户，以测试 Clean Room 的双方操作。

下载 示例工作簿，演示如何在同一个账户中同时作为提供商和使用者使用 Clean Room。

准则和建议¶

确认您在 Clean Room UI 和代码中使用相同的账户¶

您经常需要为同一 Snowflake 账户打开编码环境和 Clean Room UI（例如，在代码中创建 Clean Room 时），然后检查其在 Clean Room UI 中的外观。请务必确认您在每个 Clean Room 中使用相同的 Snowflake 账户。

Snowsight 没有为同一个账户打开 Clean Room UI 的快捷方式，反之亦然，因此您必须确保 Clean Room UI 和 Snowsight 都在同一个账户中打开。

Clean Room 名称与 Clean Room ID 的对比¶

使用 API 时，对于需要 cleanroom_name 实参的过程，按如下方式确定是使用 Clean Room 名称还是 Clean Room ID：

如果 Clean Room 是使用 API 创建的，则使用 Clean Room 名称。
如果 Clean Room 是在 Clean Room UI 中创建的，请使用 Clean Room ID。您可以通过调用 provider.view_cleanrooms 或 provider.describe_cleanroom 来查看 Clean Room 名称和 ID。

无论何时进行更改，都要更新您的 Clean Room¶

要更改任何 Clean Room 设置，包括模板、权限或策略，请调用 provider.create_or_update_cleanroom_listing 以启用更改。在某些情况下，更改可能在调用此过程之前可见，但更改要等到您调用 provider.create_or_update_cleanroom_listing 之后才能正常生效。

在代码或 UI 中创建的 Clean Room 之间的互操作性¶

在 API 中创建 Clean Room 时，Clean Room UI 中的某些功能不可修改。例如，您不能在 UI 创建的 Clean Room 的代码中添加其他模板，甚至是库存 Snowflake 模板。您也无法更改差分隐私设置。

Clean Room 对象的描述¶

Snowflake Data Clean Room 在安装时会创建许多本地数据库。您可以在 Snowflake Data Clean Rooms：安装的对象中找到有关使用 Clean Room 软件包运行或安装的任务和对象的详细信息。

SAMOOHA_BY_SNOWFLAKE.TEMPLATES.TEMPLATES：: 保存此账户中可用于 Clean Room 的所有库存 Snowflake 模板的清单和定义。

故障排除¶

Consumer can't set join policies or perform other basic actions on a joined clean room¶

确认您已使用正确角色安装 Clean Room (SAMOOHA_APP_ROLE)。如果您在安装 Clean Room 时没有使用 SAMOOHA_APP_ROLE，则会遇到很多问题，常见的是权限错误。如果是这种情况，即使是 consumer.uninstall_cleanroom 也会失败，您必须采取额外步骤卸载 Clean Room，然后使用正确的角色重新安装。

-- Who owns the clean room?
SHOW SHARES LIKE 'SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>';

-- If the owner role is not SAMOOHA_APP_ROLE, you must drop the share, then
-- uninstall the clean room.
DROP SHARE SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
USE ROLE samooha_app_role;
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<provider_locator>');

Copy

找不到您创建的 Clean Room¶

如果您在一个账户中创建了 Clean Room，但在协作者账户中看不到它，可能的原因有以下几个：

Clean Room 是在不同的云托管区域创建的，并且您尚未启用 Cross-Cloud Auto-Fulfillment。
您没有通过调用 provider.create_or_update_cleanroom_listing 发布您的 Clean Room。
您是在调用 consumer.view_cleanrooms() 而不是 ``provider.view_cleanrooms()``（或相反）。
您没有共享 Clean Room，使用错误账户共享 Clean Room，或者您在 Snowsight/Clean Room UI/CLI 中打开了错误的协作者账户。确认您希望看到 Clean Room 的账户是您共享 Clean Room 的账户，并且您已登录该共享账户。
从发布 Clean Room 到协作者可以看到它之间会有很小的延迟。

未知函数¶

If you call a procedure and get an error something like the following snippet:

Unknown user-defined function SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.<procedure name>

以下是一些可能的原因：

您输入了错误的命名空间。

请务必调用您过程的正确 provider 版本或 consumer 版本。许多过程都有提供商和使用者版本。

You mistyped the name of the function.

查看参考指南以获取正确的命名。

您已获授具有有限访问权限的运行角色，且您调用的函数不在该角色允许范围内。

通过运行以下 SQL 代码对此进行测试：

USE DATABASE samooha_by_snowflake_local_db;
CALL IS_DATABASE_ROLE_IN_SESSION('samooha_run_role');

Copy

若代码片段返回 TRUE，则说明您对 Clean Room API 具有访问受限的运行角色权限。如果您需要更大的访问权限，请向 Clean Room 管理员申请完全访问权限。请参阅 consumer.grant_run_on_cleanrooms_to_role 文档中允许的运行角色过程列表。

您没有 SAMOOHA_APP_ROLE

To see if you can use the SAMOOHA_APP_ROLE, run the following command:

-- Get current user name.
SELECT current_user();

-- Add current user name in place as indicated.
SHOW GRANTS TO USER <current_user_name> ->> select * from $1 where "role" = 'SAMOOHA_APP_ROLE';

Copy

如果您未得到任何结果，请管理员授予您对 Clean Room 的 API 访问权限。

查看用户是否已安装 Clean Room¶

您可以通过运行以下 SQL 代码来检查给定用户是否已安装给定的 Clean Room。将 $consumer_locator 和 $cleanroom_name 替换为相应的使用者定位器和 Clean Room 名称。

SELECT * FROM snowflake.data_sharing_usage.application_state
  WHERE consumer_account_locator = $consumer_locator
    AND CONTAINS(package_name, UPPER(REPLACE($cleanroom_name, ' ', '_')));

Copy

Check your query or analysis history¶

You can see your query history for analyses run in the UI or in code. These histories are stored and checked separately.

UI analysis history¶

Clean Room UI 会在 Analyses & Queries 页面中显示此账户先前的所有分析列表。这些结果仅适用于在 UI 中运行的查询。

如果您修改或删除 Clean Room，则除非报告使用以下模板之一，否则该 Clean Room UI 中的分析报告将被删除：

Audience Overlap & Segmentation
SQL Query
自定义模板。

即使修改或删除了 Clean Room，上面列出的模板的查询历史记录也会得到保留。

API 查询历史记录¶

To see the account history of all calls run using the API, including template analyses, do the following:

登录 Snowsight。
选择 Monitoring » Query History。
Use the filters to find the query associated with the analysis, and select the query or analysis.

扩展示例¶

为了帮助您了解如何使用开发者 APIs 的各种功能，您可以参考 Clean Room 文档 Use cases 部分中的示例。