Snowflake Data Clean Rooms 开发者指南

本主题为希望以编程方式创建或管理 Snowflake Data Clean Room 的用户提供指南。

Snowflake 提供了一组用于创建和控制 Clean Room 的存储过程 API。这些存储过程可在任何可以访问与您的 Clean Room 环境关联的 Snowflake 账户的界面中运行，包括 Snowsight 笔记本和工作表以及 Snowflake CLI。可以用 Snowflake 环境支持的 SQL 或任何语言来调用这些过程。

设置您的环境

以下是有效使用 Clean Room API 来设置编码环境的一些技巧。

开发工具

以下是 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： API文档分为 提供商 和 使用者 主题页面。

编码设置

以下是为 Clean Room 设置编码环境的方法：

所需角色和仓库

Clean Room API 需要 SAMOOHA_APP_ROLE 角色才能完全访问 API。请您的 Clean Room 管理员 授予您完整的 API 访问权限。Clean Room 还支持 创建可以访问 API 过程子集的角色。

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

我们建议您使用 XS 仓库来执行 Clean Room 的常规编辑、创建或删除命令。在运行机器学习工作负载等大型分析时，请考虑使用更大的仓库或 Snowpark-Optimized Warehouses。

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

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

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

GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;`

关于 Clean Room API

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

过程存在于以下架构中：

  • 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;

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

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

通过 API 创建的 Clean Room，在 Clean Room UI 界面中会被标记为 Supported with Developer APIs。

设置账户、用户和角色

您无需使用 Clean Room UI 来开发 Clean Room：大多数 Clean Room 功能都可通过调用 API 来实现。但是，有一些功能 仅在 UI 中可用，有些功能在 UI 中执行速度更快。并且由于许多用户专门使用 UI，因此了解您的 Clean Room 在 UI 中的行为表现非常重要。因此，您应该要求 Clean Room 管理员在相应的 Clean Room 账户中将您添加为 Clean Room 管理员或更高级别的角色。

根据您的用例，您可能还需要在不同的 Web 托管区域设置一个额外的 Snowflake 账户，以测试 :doc:`跨云行为 </user-guide/cleanrooms/v1/enabling-laf> `。

对测试的 Snowflake 账户进行有意义的命名，以表明其典型用法：例如，“使用者账户”、“提供商账户”和“跨云账户”。当您有多个测试账户，并且必须在 Clean Room 登录页面上选择一个账户时，这会有所帮助。

内部测试 Clean Room

您可以在开发期间通过与自己共享 Clean Room 来测试 Clean Room。这样的 Clean Room 称为 内部测试 Clean Room。提供商和使用者使用同一个账户，便于快速进行功能测试。

要创建内部测试 Clean Room，只需将提供商账户信息作为唯一使用者传递给 provider.add_consumers 即可。

内部测试 Clean Room 有以下限制：

  • 内部测试 Clean Room 以后不能与其他账户共享。 内部测试 Clean Room 始终是内部测试 Clean Room。

  • 内部测试 Clean Room 不支持以下功能：

    • 提供商激活

    • 提供商运行分析

    • 装载或查看请求日志（provider.mount_request_logs_for_all_consumers 或 provider.view_request_logs）

    • 使用者自定义模板

    • 多提供商分析

    • 差分隐私

    如果您想测试内部测试 Clean Room 不支持的功能，则必须设置单独的提供商和使用者 Snowflake 账户，以测试 Clean Room 的双方操作。

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

查看 Clean Room 环境中安装的内容

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

示例数据

Clean Room 环境安装了您可以使用的 一些示例数据集。

您还可以使用 Snowflake 生成合成测试数据。

准则和建议

以下是在使用 Clean Room 时避免出现问题的一些准则：

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

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

Snowsight 没有提供快捷方式在同一账户中打开 Clean Room UI，反之亦然，因此您必须确保在每个环境中都登录到同一个账户。

Clean Room 名称与 Clean Room ID 的对比

使用 API 时，对于接受 Clean Room 名称实参的存储过程，请按以下方式判断应使用 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。

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

当您更改任何影响 UI 的 Clean Room 属性时，调用 provider.create_or_update_cleanroom_listing 以传播变更。

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

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

故障排除

以下是一些常见的故障排除提示：

使用者无法在联接的 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>');

找不到您创建的 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 到协作者可以看到它之间会有很小的延迟。

未知函数

如果您调用一个过程并收到类似以下代码片段的错误：

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

以下是一些可能的原因：

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

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

您输入了错误的函数名称。

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

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

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

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

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

您没有 SAMOOHA_APP_ROLE

要查看是否可以使用 SAMOOHA_APP_ROLE，请运行以下命令：

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

如果您未得到任何结果，请管理员授予您对 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, ' ', '_')));

查看您的查询或分析历史记录

您可以查看在 UI 或代码中运行的分析的查询历史记录。这些历史记录需要单独存储和检查。

UI 分析历史记录

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

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

  • Audience Overlap & Segmentation

  • SQL Query

  • 自定义模板。

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

API 查询历史记录

要查看所有使用 API 运行的调用（包括模板分析）的账户历史记录，请执行以下操作：

  1. 登录 Snowsight。

  2. 在导航菜单中，选择 Monitoring » Query History。

  3. 使用筛选器查找与分析关联的查询，然后选择查询或分析。

扩展示例

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