Snowflake Data Clean Rooms 开发者指南¶

开发工具¶

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

• 编码环境： 任何可以在您的 Snowflake 账户中运行存储过程的编码环境都可以运行。大多数开发者使用 Snowsight 中的工作表（基于浏览器的工具）或 Snowflake CLI。

• The clean rooms UI: Use the clean rooms UI to configure, manage, or create clean rooms. Most clean room analysts use the UI rather than code, so it's important to see and test the experience of your clean rooms in the UI. Additionally, there are a handful of features that are available only in the clean rooms UI.

• Snowsight 可用于浏览数据库和其他对象以及搜索对象。

• Clean rooms API: API documentation is divided into provider and consumer topic pages.

编码设置¶

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

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

GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;`

设置账户、用户和角色¶

You aren't required to use the clean rooms UI to develop clean rooms: most clean room functionality is available by calling the API. 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. 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.

Name your test Snowflake accounts meaningfully to indicate their typical usage: for example, "Consumer account," "Provider account," and "Cross-cloud account." This can help when you have multiple test accounts and must choose an account on the clean rooms login page.

See what's installed with the clean rooms environment¶

Snowflake Data Clean Rooms creates many local databases upon installation. You can find details about tasks and objects that are run or installed with a clean room package in Snowflake Data Clean Rooms：安装的对象.

Sample data¶

The clean rooms environment installs a few sample datasets you can use.

You can also generate synthetic test data using Snowflake.

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

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

Snowsight does not have a shortcut to open the clean rooms UI for the same account, or the reverse, so you must be sure to log in to the same account in each environment.

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

When using the API, for procedures that take a clean room name argument, determine whether to use the clean room name or the clean room ID as follows:

• 如果 Clean Room 是使用 API 创建的，则使用 Clean Room 名称。

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

Update your clean room whenever you make UI changes¶

When you change any clean room properties that affect the UI, call provider.create_or_update_cleanroom_listing to propagate the changes.

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

When you create a clean room using the API, some features are not modifiable in the clean rooms UI. For example, you cannot add additional templates, even stock Snowflake templates, in code for a UI-created clean room. You also cannot change the differential privacy settings.

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

找不到您创建的 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>

Here are a few possible causes:

You typed the wrong namespace.

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

You mistyped the name of the function.

Check the reference guide for the proper naming.

You have been granted a limited-access run-role, and the function you called isn't allowed by your role.

Test this by running the following SQL code:

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

Copy

If the code snippet returns TRUE, you have limited-access run-role permissions on the clean room API. If you need greater access, ask a clean room administrator for full access. See the list of permitted run-role procedures in the consumer.grant_run_on_cleanrooms_to_role documentation.

You don't have 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

If you don't get any results, ask an administrator to give you API access to the clean room.

See if a user has installed a clean room¶

You can check if a given user has installed a given clean room by running the following SQL code. Replace $consumer_locator and $cleanroom_name with the consumer locator and clean room name.

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

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.