Snowflake Data Clean Room：提供商 API 参考指南¶

本页描述了 Clean Room API 使用者管理其 Clean Room 时使用的程序。有关编码设置的说明，请参阅编码设置。

创建、配置和删除 Clean Room¶

provider.view_cleanrooms¶

描述： 列出此提供商账户创建的所有现有 Clean Room。

实参： 无

返回： （表） 此提供商账户创建的 Clean Room 列表。Clean Room 无需与使用者共享、由使用者安装或使用。已删除的 Clean Room 将从数据库中清除，并且不显示在此列表中。

示例：

call samooha_by_snowflake_local_db.provider.view_cleanrooms();

Copy

provider.describe_cleanroom¶

描述： 获取有关 Clean Room 的信息摘要，如模板、联接策略、列策略和使用者。

实参：

cleanroom_name（字符串） – 要获取信息的 Clean Room 的名称。

返回： （字符串） Clean Room 元数据摘要。

示例：

call samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

Copy

provider.cleanroom_init¶

描述： 在账户中创建指定名称的 Clean Room。此过程可能需要一分钟或更长时间才能运行。在您调用 create_or_update_cleanroom_listing 后，Clean Room 才会在 Web 应用程序中或对协作者可见。

实参：

cleanroom_name（字符串） – Clean Room 名称，最多 80 个字符。名称包括 [A‑Z,a‑z,0‑9, ,_]。
distribution（字符串，可选） – 以下值之一：
- INTERNAL（默认）– Clean Room 仅对同一组织内的用户可见，并且在更改默认版本之前不会触发安全扫描。
- EXTERNAL - Clean Room 可随时投入生产，并可与组织外共享。在更改默认版本之前，Clean Room 会触发安全扫描。如果要在创建 Clean Room 后更改分发，请调用 修改包，如下所示：
  alter application package samooha_cleanroom_<CLEANROOM_ID> SET DISTRIBUTION = EXTERNAL;
  Copy

返回： （字符串） 成功或失败消息。

示例：

-- Create an internal clean room
call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Copy

provider.set_default_release_directive¶

描述： 指定协作者在 Web 应用程序中启动新的浏览器会话或从 API 访问 Clean Room 时加载的 Clean Room 的版本和补丁。必须在与使用者共享 Clean Room 之前调用。

无论何时上传或更改 Python 代码，Clean Room 应用程序都会创建一个新版本的 Clean Room。如果您希望为用户提供最新版本的服务，请使用新的版本号调用此过程。要查看可用版本并了解当前默认版本，请运行：

show versions in application package samooha_cleanroom_<CLEANROOM_ID>;

Copy

创建的所有 Clean Room 都有以下版本号和补丁号：

版本：V1_0
补丁：0

备注

如果 Clean Room 分布设置为 EXTERNAL，则只有在 Clean Room 安全扫描进入 APPROVED 状态后，才能调用此过程。要查看安全状态，请调用 view_cleanrooom_scan_status。

实参：

cleanroom_name（字符串） – Clean Room 名称。
version（字符串） – 版本。必须始终为“V1_0”。
patch（字符串） – 使用者加载的补丁号。补丁号从 0 开始，每当有新的 Clean Room 版本可用时，都应该递增。您可以看到如上所述的可用版本。

返回： （字符串） 成功或失败消息。

示例：

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

Copy

provider.drop_cleanroom¶

描述： 删除 Clean Room。安装了 Clean Room 的协作者将无法再访问或使用。下次刷新浏览器时，Clean Room 将不再显示在 Web 应用程序中。

实参：

cleanroom_name（字符串） – 要删除的 Clean Room 的名称。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Copy

provider.enable_consumer_run_analysis¶

描述： 让使用者能够在 Clean Room 运行分析。此功能默认在所有新的 Clean Room 中启用，因此，仅当您明确禁用了 Clean Room 的使用者运行分析时，才需要运行此过程。

实参：

cleanroom_name（字符串） – 允许使用者运行分析的 Clean Room 的名称。
consumer_accounts（字符串数组） – 要为之启用此功能的所有使用者的账户定位器。NOTE： 这些使用者必须已经添加到 Clean Room。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.enable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR_1>']); 

Copy

provider.disable_consumer_run_analysis¶

描述： 防止指定使用者在指定 Clean Room 运行分析。默认情况下，允许所有使用者在 Clean Room 内运行分析。

实参：

cleanroom_name（字符串） – 正在禁用使用者运行分析的 Clean Room。
consumer_accounts（字符串数组） – 无法在此 Clean Room 中运行分析的使用者的账户定位器。NOTE： 这些使用者必须已经添加到 Clean Room。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR_1>']); 

Copy

library.is_consumer_run_enabled¶

描述： 检查此 Clean Room 是否允许使用者运行分析。

实参：

cleanroom_name（字符串） – 要检查的 Clean Room 的名称。

返回： （字符串） 此 Clean Room 是否允许使用者运行分析。

示例：

call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)

Copy

provider.create_or_update_cleanroom_listing¶

描述： 发布新 Clean Room 或更新现有 Clean Room。每当对 Clean Room 进行更改时，您都应该调用此方法，以确保将更改传播给使用者。

首次发布 Clean Room 时，可能需要一段时间才能在 Web 应用程序中看到 Clean Room（最多 15 分钟）。

如果您之后不调用此方法而对 Clean Room 进行更新，则不能保证这些更改会传播给使用者。

您可以在单个账户中创建的 Clean Room + 协作者数量是有限的。如果您创建的测试 Clean Room 过多，则可能需要删除一些才能创建新的 Clean Room。如果您需要的 Clean Room 数量超出账户容量，请联系 Snowflake 支持部门。

备注

在调用此过程之前，必须至少设置一次发布指令。有关更多信息，请参阅 provider.set_default_release_directive。

实参：

cleanroom_name（字符串） – 要发布或更新的 Clean Room 的名称。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing($cleanroom_name);

Copy

注册和取消注册数据¶

使用以下命令注册和取消注册数据库、架构和对象。必须先注册表和视图，然后才能将其链接到 Clean Room。如果您注册了一个数据库或架构，则还需注册该数据库或架构中的所有对象。

了解有关注册数据的详细信息。

provider.register_db¶

描述： 使数据库及其中的所有对象能够链接到此 Clean Room 环境中的单个 Clean Room。此过程将数据库的 USAGE 和 SELECT 权限授予 SAMOOHA_APP_ROLE，Clean Room 环境使用该角色访问数据。

您必须具有对数据库的 MANAGE GRANTS 访问权限才能调用此过程。然后，此 Clean Room 环境中的其他提供商可以将这些对象链接到自己的 Clean Room，而无需其 SELECT 权限。

了解有关注册数据的详细信息。

重要

此过程不会注册调用后创建的任何对象。如果向数据库中添加了新对象，并且您也希望注册这些对象，则必须再次调用此过程。

实参：

db_name（字符串） – 要注册的数据库的名称。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.provider.register_db('SAMOOHA_SAMPLE_DATABASE');

Copy

library.register_schema¶

描述： 与 register_db 类似，但在架构级运行。您必须具有对架构的 MANAGE GRANTS 权限才能调用此过程。

此过程将架构的 USAGE 和 SELECT 权限授予 SAMOOHA_APP_ROLE，Clean Room 环境使用该角色访问数据。

如果要注册托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构），请改用 library.register_managed_access_schema。

重要

此过程不会注册调用后创建的任何对象。如果向数据库中添加了新对象，并且您也希望注册这些对象，则必须再次调用此过程。

实参：

schema_name（字符串数组） – 要注册的一个或多个完全限定架构名称的数组。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

Copy

library.register_managed_access_schema¶

描述： 类似于 register_schema，但注册了使用 WITH MANAGED ACCESS 参数创建的架构。您必须具有架构的 MANAGE GRANTS 权限才能调用此过程。

此过程将托管架构使用权限授予 SAMOOHA_APP_ROLE，Clean Room 环境使用该角色访问数据。

重要

此过程不会注册调用后创建的任何对象。如果向数据库中添加了新对象，并且您也希望注册这些对象，则必须再次调用此过程。

实参：

schema_name（字符串数组） – 一个或多个完全限定架构名称的数组。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

Copy

library.register_objects¶

描述： 授予 Clean Room 访问所有类型的表和视图的权限，使其可以通过调用 provider.link_datasets 链接到 Clean Room。您可以通过调用 library.register_schema、library.register_managed_access_schema 或 provider.register_db 注册更广泛的对象组。

此过程将对象使用权限授予 SAMOOHA_APP_ROLE，Clean Room 环境使用该角色访问数据。

您必须具有对对象的 MANAGE GRANTS 权限才能调用此过程。此过程不能用于注册数据库。

如果注册基于其他数据库中对象的视图，则还必须授予原生应用程序访问源对象的权限。

实参：

object_names（数组） – 完全限定的对象名称数组。然后可以将这些对象链接到 clean room。

返回： （字符串） 成功或失败消息。

示例

要注册表和视图：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

Copy

library.enable_external_tables_on_account¶

描述： 允许在此账户的所有 Clean Room 中使用 Iceberg 表或外部表。必须同时由提供商和使用者账户中的 ACCOUNTADMIN 调用，以允许通过任一账户链接 Iceberg 表或外部表。要将此功能限制在此账户中的特定 Clean Room，请改为调用 enable_external_tables_for_cleanroom。

如果成功且所有安全扫描都通过，则会生成 Clean Room 的一个新补丁版本。

实参： 无

返回： （字符串） 成功或失败消息。如果成功，它将触发安全扫描，并提供安全扫描成功后生成的补丁编号。

示例：

USE ROLE ACCOUNTADMIN;

CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();

Copy

provider.enable_external_tables_for_cleanroom¶

描述： 使提供商能够将 Iceberg 表或外部表链接到此账户中的指定 Clean Room。要允许该账户中的所有 Clean Room 使用 Iceberg 表和外部表，请改为调用 enable_external_tables_on_account。

如果成功，将生成 Clean Room 的一个新补丁版本。

实参：

cleanroom_name（字符串） - Clean Room 名称，提供商可将 Iceberg 表或外部表链接至该 Clean Room。

返回： （字符串） 成功或失败消息。如果成功，它将触发安全扫描，并提供安全扫描成功后生成的补丁编号。

示例：

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
    $cleanroom_name);

Copy

library.unregister_db¶

描述： 颠倒 register_db 过程，并移除向 SAMOOHA_APP_ROLE 角色和 Snowflake Data Clean Room 本地应用程序授予的数据库级权限。这样还会从 Web 应用程序中的选择器中删除任何数据库。

实参：

db_name（字符串） – 要取消注册的数据库的名称。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');

Copy

library.unregister_schema¶

描述： 取消注册一个架构，以防止用户将其表和视图链接到 Clean Room。

如果要取消注册托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构），请改用 library.unregister_managed_access_schema。

实参：

schema_name（数组） – 要取消注册的架构。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

Copy

library.unregister_managed_access_schema¶

描述： 类似于 unregister_schema，但取消注册了使用 WITH MANAGED ACCESS 参数创建的架构。

实参：

schema_name（数组） – 要取消注册的托管架构。

返回： （字符串） 成功或失败消息。

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

Copy

library.unregister_objects¶

描述： 撤销 Clean Room 对所有类型的表和视图的访问权限。此账户管理的所有 clean room 中的任何用户将无法再使用这些对象。

实参：

object_names（数组） – 应该撤销访问权限的完全限定对象名称数组。

返回： （字符串） 成功或失败消息。

示例

要取消注册表和视图：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

Copy

链接数据和表¶

使用以下命令在 Clean Room 中添加或删除表和视图。

provider.link_datasets¶

描述： 将 Snowflake 表或视图链接到 Clean Room。该过程在 Clean Room 内创建表的安全视图，自动使 Clean Room 可以访问表，从而无需制作表副本。该表仍与其源相关联，因此源中的更新将反映在 Clean Room 内的安全版本中。

这里链接的任何项目必须首先在数据库、架构或对象级别注册。

实参：

cleanroom_name（字符串） – 可以访问对象的 Clean Room 的名称。
tables_list（字符串数组） – 要链接到 Clean Room 的表或视图列表。必须先注册对象，然后才能链接对象。
consumer_list（字符串数组，可选） – 如果存在，则只允许此处列出的使用者访问这些对象。如果缺失，则允许任何有权访问 Clean Room 的人访问这些数据。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.link_datasets(
  $cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MYDB.MYSCH.EXPOSURES']);

Copy

备注

如果将某个视图链接到 Clean Room，并且该视图基于其他数据库中的表，则必须同时注册该视图和该视图的源

provider.unlink_datasets¶

描述： 删除所有用户对指定 clean room 中指定表的访问权限。提供商必须已链接指定的表。

实参：

cleanroom_name（字符串） – 链接到这些数据组的 Clean Room 的名称。
tables_list（数组） – 要从 Clean Room 取消链接的表或视图的名称的数组。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.unlink_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MYDB.MYSCH.EXPOSURES']);

Copy

provider.view_provider_datasets¶

描述： 查看此账户中任何提供商链接到指定 Clean Room 的所有表和视图。

实参：

cleanroom_name（字符串） – Clean Room 的名称。

返回： 链接到指定 Clean Room 的对象表，以及每个对象的 Clean Room 内部视图名称。

示例：

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Copy

provider.restrict_table_options_to_consumers¶

描述： 控制特定使用者是否可以访问 Clean Room 中的表。此过程只能替换，即完全覆盖前一次调用中设置的任何值。

如果在调用此方法时没有指定，通过 provider.link_datasets、provider.restrict_table_options_to_consumers 或任何其他方法获授访问权限的使用者将失去对表的访问权限。

实参：

cleanroom_name（字符串） – 要限制的 Clean Room 的名称。
*access_details（对象） - JSON 对象，其中每个字段名称都是表或视图的完全限定名称，字段值是可以访问该表或视图的用户的账户定位器数组。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.restrict_table_options_to_consumers(
    $cleanroom_name,
    {
        'DB.SCHEMA.TABLE1': ['CONSUMER_1_LOCATOR'],
        'DB.SCHEMA.TABLE2': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
    }
);

Copy

管理策略¶

Data Clean Room 中的联接策略与 Snowflake 全域联接策略不同。仅使用此过程设置 Clean Room 的联接策略；Clean Room 会忽略在 Clean Room 之外的表上设置的联接策略。

详细了解 Clean Room 中的表策略。

provider.view_join_policy¶

说明： 显示当前应用于 Clean Room 的联接策略。

实参：

cleanroom_name（字符串） – 要查询的 Clean Room 的名称。

返回： （表） Clean Room 中所有表或视图的可联接行列表。

示例：

call samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Copy

provider.set_join_policy¶

描述： 指定在此 Clean Room 内运行模板时，使用者可以联接哪些列。注意，联接策略是 仅替换，因此如果再次调用过程，新的联接策略会完全替换之前设置的联接策略。

重要

只有当模板应用 join_policy 或 join_and_column_policy JinjaSQL 筛选器来联接行时，才会强制实施联接策略。

备注

实参：

cleanroom_name（字符串） – 应强制实施联接策略的 Clean Room 的名称。
table_and_col_names（字符串数组） – 完全限定的列名，格式为 database_name.schema_name.table_or_view_name:column_name。** 注意正确使用 . versus : 标记**

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, 
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL', 'MYDB.MYSCH.EXPOSURES:HASHED_EMAIL']);

Copy

管理提供商模板¶

使用以下命令添加此 Clean Room 支持的模板/分析。

provider.view_added_templates¶

描述： 查看 Clean Room 中提供商添加的模板。没有为此提供商列出所有 Clean Room 中所有模板的方法。

实参：

cleanroom_name（字符串） – 要查询的 Clean Room。

返回： （表） – 指定 Clean Room 中可用的模板列表，含每个模板的详细信息。

示例：

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Copy

provider.view_template_definition¶

描述： 显示有关特定模板的信息。查看提供商模板的使用者应使用 consumer.view_template_Definition。

实参：

cleanroom_name（字符串） – 具有此模板的 Clean Room 的名称。
template_name（字符串） – 要请求相关信息的模板的名称。

返回： 模板定义（字符串）

示例：

call samooha_by_snowflake_local_db.provider.view_template_definition($cleanroom_name, 'prod_overlap_analysis');

Copy

provider.add_templates¶

**描述：**向 Clean Room 添加模板列表。这不会取代现有的模板列表。

实参：

cleanroom_name（字符串） – 要添加模板的 Clean Room 的名称。
template_names（字符串数组） – 要添加的模板的名称。这些只是 Snowflake 提供的模板。要添加自定义模板，请调用 add_custom_sql_template。Snowflake 提供的模板名称包括“prod_overlap_analysis”和“prod_provider_data_analysis”。

返回： （字符串） 成功或失败消息。

示例：

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

Copy

provider.clear_template¶

描述： 从 Clean Room 中移除指定模板。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
template_name（字符串） – 要从 Clean Room 中移除的模板的名称。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.clear_template($cleanroom_name, 'prod_custom_template');

Copy

provider.clear_all_templates¶

描述： 移除已添加到 Clean Room 的所有模板。

实参：

cleanroom_name（字符串） – 要从中移除所有模板的 Clean Room 的名称。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.clear_all_templates($cleanroom_name);

Copy

provider.set_column_policy¶

描述： 将数据中的哪些列设置为作为非联接行对 Clean Room 中的指定模板可用。必须在此处或者在 set_join_policy 中声明列后，才能在 Clean Room 中使用。此处列出的列可用于模板中的任何位置，但用作联接列除外。列不能同时列在列策略和联接策略中。

默认情况下，表的列策略为空，这意味着在结果中看不到任何列。

此过程是 完全替换 行为，因此每次调用时，都会完全覆盖前面的列列表。

请注意，进行列策略检查的方式是解析为查找任何未经授权的列而要对数据运行的 SQL 查询。使用这些检查可能无法找出含有通配符的查询，因此，设计分析模板时应慎重。如果某些列确实不应该被查询，可以考虑为源表创建一个视图来消除这些敏感列，并改为在该视图中建立链接。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
analysis_and_table_and_cols（字符串数组） – 模板可以使用的列数组。格式为：template_name:full_table_name:column_name

返回： （字符串） 成功或失败消息。

示例：

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

 -- Same example, but using a variable name for the template.
call samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name,
[$template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 $template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 $template_name || ':SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE']);

Copy

provider.view_column_policy¶

描述： 列出当前在 Clean Room 中激活的列策略。列策略说明哪些表列可以在哪些模板中显示。

实参： cleanroom_name（字符串）

返回： （表） 哪些列可用于哪些模板。

示例：

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Copy

provider.add_custom_sql_template¶

描述： 将自定义 JinjaSQL 模板添加到 Clean Room。这样，使用者就可以调用模板。了解如何创建自定义模板。

您可以多次调用该 API 将多个自定义模板添加到 Clean Room。该过程会覆盖此 Clean Room 中之前的同名模板。

如果使用者使用模板将结果返回给提供商，则命令必须满足以下要求：

自定义模板的名称必须以字符串 activation 开头。例如，activation_custom_template。
模板必须创建以 cleanroom.activation_data_ 开头的表。例如，CREATE TABLE cleanroom.activation_data_analysis_results AS ...。
模板必须返回在定义（即追加到 cleanroom.activation_data_ 的字符串）中创建的表名的唯一部分。例如，return 'data_analysis_results'。

实参：

cleanroom_name（字符串） – 适用此模板的 Clean Room 的名称。
template_name（字符串） – 模板的名称。必须全部是小写字母、数字、空格或下划线。激活模板的名称必须以“activation”开头。
模板（字符串） – JinjaSQL 模板。
sensitivity（浮点数，可选） – 如果为该 Clean Room 启用了差分隐私，则它会控制应用于该模板返回的数据的差分隐私噪声量。必须是大于 0 的数字。默认值为 1.0。差分隐私任务必须在此 Clean Room 中运行，此实参才能生效。
consumer_locators（字符串数组，可选） – 一个或多个账户定位器的数组。如果存在，此模板将仅添加到这些账户的 Clean Room。您可以稍后通过调用 provider.restrict_template_options_to_consumers 来修改此列表。如果不指定使用者列表，则所有使用者都可以在指定的 Clean Room 中使用自定义模板。
is_obfuscated（布尔，可选） - 若为 TRUE，则可防止使用者查看模板正文。请注意，您必须使用 Snowflake Enterprise Edition 或更高版本才能运行混淆模板。如果此模板用于提供商运行分析，则在更改 is_obfuscated 状态时，使用者必须重新批准分析请求。is_obfuscated 不能与 敏感性 一起使用。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name, 'prod_custom_template', 
    $$
select 
    identifier({{ dimensions[0] | column_policy }}) 
from 
    identifier({{ my_table[0] }}) c 
    inner join 
    identifier({{ source_table[0] }}) p 
    on 
        c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }}) 
    {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
    $$);

Copy

provider.add_ui_form_customizations¶

描述： 在 Web 应用程序中运行 Clean Room 时，定义 Clean Room 中模板的自定义表单。这在允许使用者选择表或列等模板参数时非常有用。至少，必须在 template_information 实参中为 display_name、description 和 methodology 指定值。

建议将表选择元素置于列选择元素之前，尤其是当列选择器根据表选择进行填充时。

调用此函数后必须更新 Clean Room。 如果在更新 UI 后未调用 provider.create_or_update_cleanroom_listing，则协作者将看不到任何更新。

实参：

cleanroom_name（字符串）：包含此模板的 Clean Room 名称。提交的表仅适用于指定 Clean Room 中的指定模板。
template_name（字符串）：该 UI 适用的模板的名称。这不是使用 template_information.display_name 字段指定的用户可见的标题。
template_information（字典）：UI 中向用户显示的信息。包含以下字段：
- display_name（必填）：显示 Web 应用程序中模板的名称。
- description（必填）：模板的描述。
- methodology（必填）：说明使用者应如何使用表单执行分析。
- warehouse_hints （对象）：建议使用哪种类型的仓库来运行分析。这是一个具有以下字段的对象：
  - warehouse_size：请参阅 CREATE WAREHOUSE 中的 warehouse_size，了解有效值。
  - snowpark_optimized （布尔）：是否使用 Snowpark 优化型仓库来处理查询。对于大多数机器学习用例，Snowflake 建议设置为 TRUE。
- render_table_dropdowns （对象）：是否显示默认下拉列表，让用户选择在查询中使用哪个提供商和/或使用者表。这是一个具有以下字段的对象：
  - render_consumer_table_dropdown （布尔，默认 = TRUE） 如果为 TRUE，则显示默认使用者表选择器。如果为 FALSE，则隐藏使用者表选择器。模板可以使用 my_table 模板变量以列表形式访问所选值。
  - render_provider_table_dropdown：（布尔，默认 = TRUE） 如果为 TRUE，则显示默认提供商表选择器。如果为 FALSE，则隐藏提供商表选择器。模板可以使用 source_table 模板变量以列表形式访问所选值。
- activation_template_name：（字符串） 此 Clean Room 中激活模板的名称。使用不带任何 cleanroom 前缀的模板名称。了解激活模板相关信息。
- enabled_activations：（字符串） 启用了哪种激活。可能的值：consumer、provider。没有默认值；如果指定了 activation_template_name，则必须提供此实参。
details（字典）：定义用户可配置的输入字段，将值传递给模板。这是一个键/对象对的字典，每对表示一个用户可配置的 UI 元素。键是 JinjaSQL 模板中的变量名称。值是定义 UI 元素的对象。每个对象可以有以下字段：
```
<field_name>: {
  ['display_name': <string>,]
  ['order': <number>,]
  ['description': <string>,]
  ['type': <enum>,]
  ['default': <value>,]
  ['choices': <string array>,]
  ['infoMessage': <string>,]
  ['size': <enum>,]
  ['required': <bool>,]
  ['group': <string>,]
  ['references': <array of string>,]
  ['provider_parent_table_field':  <string>,]
  ['consumer_parent_table_field': <string>]
}
```
Copy
- display_name：在 UI 表单中为此项添加标签文本。
- order：此元素在表单中应按从 1 开始的顺序显示。如果未指定，则该元素将按照其在对象中出现的顺序呈现。
- description：元素用途的描述，显示在标签下方。请在此处提供简短的帮助说明或示例。如果未提供，则不会显示任何内容。
- type：UI 元素的类型。如果为该输入字段指定了引用，则省略此条目（系统会自动确定其类型）。支持的值：
  - any （默认）：常规文本输入字段
  - boolean：真/假选择器
  - integer：使用箭头更改数字
  - multiselect：从下拉列表中选择多个项目
  - dropdown：从下拉列表中选择一个项目
  - date：日期选择器
- default：该元素的默认值
- choices：（字符串数组） 下拉列表和多选元素选项列表
- infoMessage：元素旁显示的信息悬停文本。如果未提供，则不显示任何工具提示。
- size：元素大小。支持的值：XS、S、M、L、XL
- required：用户是否需要某个值。指定 TRUE 或 FALSE。
- group：组名，用于对 UI 中的项目进行分组。对 UI 中应分组在一起的项目使用相同的组名。如果隐藏默认下拉列表，则可以使用自定义模板中的 {{ source_table }} 和 {{ my_table}} 特殊实参，然后定义自己的下拉列表，其中包含所需的表。有关在定义自定义模板时使用这些特殊变量的详细信息，请参阅 provider.add_custom_sql_template。
- references：创建一个下拉列表，其中包含 Clean Room 中可用的表或列，而无需提前了解这些表或列或单独列出这些表或列。如果使用，类型必须是“multiselect”或“dropdown”。支持以下字符串值：
  - PROVIDER_TABLES：列出用户可访问的 Clean Room 中的所有提供商表的下拉列表。
  - PROVIDER_JOIN_POLICY：从 provider_parent_table_field 指定的提供商表中可以联接的所有列的下拉列表。
  - PROVIDER_COLUMN_POLICY：所有列的下拉列表，其中包含 provider_parent_table_field 指定的提供商表中的列策略。
  - PROVIDER_ACTIVATION_POLICY：提供商激活策略中所有列的下拉列表。
  - CONSUMER_TABLES：列出用户可访问的 Clean Room 中的所有使用者表的下拉列表。
  - CONSUMER_COLUMNS：列出 consumer_parent_table_field 指定的使用者表中用户可以访问的所有列的下拉列表。您不应该在提供商运行的模板中使用使用者列引用，因为使用者可能会应用联接和列策略，这可能会导致在未遵守列的策略时查询失败。
  - CONSUMER_JOIN_POLICY：可以从 consumer_parent_table_field 指定的使用者表联接的所有列的下拉列表。
  - CONSUMER_COLUMN_POLICY：具有 consumer_parent_table_field 指定的使用者表中的列策略的所有列的下拉列表。
- provider_parent_table_field：指定用户选择提供商表的 UI 元素的名称（此处不提供表名本身）。仅当 references 设置为 PROVIDER_COLUMN_POLICY 或 PROVIDER_JOIN_POLICY 时才使用。
- consumer_parent_table_field：指定用户选择使用者表的 UI 元素的名称（此处不提供表名本身）。仅当 references 设置为 CONSUMER_COLUMNS、CONSUMER_JOIN_POLICY 或 CONSUMER_COLUMN_POLICY 时才使用。
output_config（字典） 定义如何在 Web 应用程序中以图形方式显示模板结果。如果未提供，则不以图形显示结果，仅以表格显示结果。如果不需要图形，请为此实参提供一个空对象 {}。允许的字段：
- measure_columns：包含要在 Web 应用程序生成的图形中使用的度量值和维度的列的名称。
- default_output_type：显示结果的默认格式。如果数据格式正确，则用户通常可以更改 UI 中的显示格式。支持的类型：
  - TABLE：（默认） 表格格式
  - BAR：条形图，适合比较不同类别的数据。
  - LINE：折线图，适合显示随时间变化的趋势或连续数据。
  - PIE：饼状图，适合显示比例或百分比。

返回： （字符串） 成功或失败消息。

示例：

-- Specify the display name, description, and warehouse, and hide the default table dropdown lists. 
-- Define the following two fields in the UI:
--   A provider table selector that shows all provider tables. Chosen tables can be accessed by the template with the variable 'a_provider_table'
--     (This dropdown list is equivalent to setting `render_table_dropdowns.render_provider_table_dropdown: True`)
--   A column selector for the tables chosen in 'a_provider_table'. Chosen columns can be accessed by the template with the variable 'a_provider_col'

call samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_custom_template',
    {
        'display_name': 'Custom Analysis Template',
        'description': 'Use custom template to run a customized analysis.',
        'methodology': 'This custom template dynamically renders a form for you to fill out, which are then used to generate a customized analysis fitting your request.',
        'warehouse_hints': {
            'warehouse_size': 'xsmall',
            'snowpark_optimized': FALSE
        },
        'render_table_dropdowns': {
            'render_consumer_table_dropdown': false,
            'render_provider_table_dropdown': false
        },
        'activation_template_name': 'activation_my_template',
        'enabled_activations': ['consumer', 'provider']  
    },    
    {
        'a_provider_table': {
            'display_name': 'Provider table',
            'order': 3,
            'description': 'Provider table selection',
            'size': 'S',
            'group': 'Seed Audience Selection',
            'references': ['PROVIDER_TABLES'],
            'type': 'dropdown'
        },
        'a_provider_col': {
            'display_name': 'Provider column',
            'order': 4,
            'description': 'Which col do you want to count on',
            'size': 'S',
            'group': 'Seed Audience Selection',
            'references': ['PROVIDER_COLUMN_POLICY'],
            'provider_parent_table_field': 'a_provider_table',
            'type': 'dropdown'
        }
    },
    {
        'measure_columns': ['col1', 'col2'],
        'default_output_type': 'PIE'
    }
);

Copy

provider.restrict_template_options_to_consumers¶

描述： 控制哪些用户可以访问给定 Clean Room 中的给定模板。此过程将覆盖之前由任何其他过程为 Clean Room/模板对指定的任何访问列表。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
access_details（JSON 对象） – 模板的名称以及可以在该 Clean Room 中访问该模板的用户。如果指定了模板，则只有此处列出的用户才能在该 Clean Room 中访问该模板。这是一个对象，每个模板有一个子对象，格式如下：{'template_name': ['user1_locator','user2_locator','userN_locator']}

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.restrict_template_options_to_consumers(
    $cleanroom_name,
    {
        'prod_template_1': ['CONSUMER_1_LOCATOR', 'CONSUMER_2_LOCATOR']
    }
);

Copy

使用者自定义模板¶

以下 APIs 让您可以批准或拒绝使用者为 Clean Room 添加模板的请求。仅当提供商批准使用者添加模板的请求时，才会将使用者定义的模板添加到 Clean Room。有关更多信息，请参阅使用开发者 API 添加使用者定义的模板。

provider.list_pending_template_requests¶

描述： 列出想要将使用者定义的模板添加到 Clean Room 的使用者提出的所有未经批准的请求。其中包括待处理、已批准和已拒绝的请求。使用此过程可检查待处理的请求，并对其进行批准 (provider.approve_template_request) 或拒绝 (provider.reject_template_request)。

实参：

cleanroom_name（字符串） – 查看使用者要求向此 Clean Room 添加模板的请求。

返回： 包含以下值的表：

request_id（字符串） – 请求的 ID，接受或拒绝请求时需要使用此项。consumer_locator（字符串） – 请求提出者的账户定位器。template_name（字符串） – 使用者提供的模板的名称。template_definition（字符串） – 使用者建议的模板的完整定义。

示例：

call samooha_by_snowflake_local_db.provider.list_pending_template_requests($template_name);

Copy

provider.list_template_requests¶

描述： 列出所有想要将使用者定义的模板添加到 Clean Room 的使用者的请求。其中包括待处理、已批准和已拒绝的请求。使用此选项可检查待处理请求并审批 (provider.approve_template_request) 或拒绝 (provider.reject_template_request)。

实参：

cleanroom_name（字符串） – 查看使用者要求向此 Clean Room 添加模板的请求。

返回： 包含以下值的表：

request_id（字符串） – 请求的 ID，接受或拒绝请求需要使用。consumer_identifier（字符串） – 提出请求者的账户定位器。template_name（字符串） – 使用者提供的模板的名称。template_definition（字符串） – 使用者建议的模板的完整定义。status（字符串） – 请求的状态：PENDING、APPROVED、REJECTED。

示例：

call samooha_by_snowflake_local_db.provider.list_template_requests($template_name);

Copy

provider.approve_template_request¶

描述： 批准为 Clean Room 添加模板的请求。

实参：

cleanroom_name（字符串） – 用户要添加模板的 Clean Room 的名称。
request_id（字符串） – 要批准的请求的 ID。调用 provider.list_template_requests 查看请求 IDs。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.approve_template_request($cleanroom_name, 
    '815324e5-54f2-4039-b5fb-bb0613846a5b');

Copy

provider.approve_multiple_template_requests¶

描述： 批准多个使用者向 Clean Room 添加模板的请求。所有请求必须针对一个 Clean Room。

实参：

cleanroom_name（字符串） - 此请求适用的 Clean Room 名称。
request_ids（字符串数组） - 要批准的所有模板请求的 IDs。要获取请求 ID，请调用 provider.list_template_requests。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.approve_multiple_template_requests($cleanroom_name, 
    ['cfd538e2-3a17-48e3-9773-14275e7d2cc9','2982fb0a-02b7-496b-b1c1-56e6578f5eac']);

Copy

provider.reject_template_request¶

描述：拒绝为 Clean Room 添加模板的请求。

实参：

cleanroom_name（字符串） – 用户要添加模板的 Clean Room 的名称。
request_id（字符串） – 要拒绝的请求的 ID。调用 provider.list_template_requests 查看请求 IDs。
reason_for_rejection（字符串） – 拒绝请求的原因。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.reject_template_request('dcr_cleanroom',
  'cfd538e2-3a17-48e3-9773-14275e7d2cc9',
  'Failed security assessment');

Copy

provider.reject_multiple_template_requests¶

描述： 拒绝多个使用者向 Clean Room 添加模板的请求。所有请求必须针对同一个 Clean Room。

实参：

cleanroom_name（字符串） - 此请求适用的 Clean Room 名称。
rejected_templates（对象数组） - 包含以下字段的对象数组，每次拒绝一个：
- request_id（字符串） – 要拒绝的请求的 ID。要获取请求 ID，请调用 provider.list_template_requests。
- reason_for_rejection（字符串） - 自由文本描述，说明拒绝请求的原因。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.reject_multiple_template_requests($cleanroom_name,
  [OBJECT_CONSTRUCT('request_id', '815324e5-54f2-4039-b5fb-bb0613846a5b', 'reason_for_rejection', 'Failed security assessment'),
   OBJECT_CONSTRUCT('request_id', '2982fb0a-02b7-496b-b1c1-56e6578f5eac', 'reason_for_rejection', 'Some other reason')
  ]);

Copy

模板链¶

使用以下命令创建和管理模板链。

provider.add_template_chain¶

描述： 创建新的模板链。模板在添加到模板链之前必须存在。创建模板链后，将无法修改，但您可以创建一个同名的新模板链以覆盖旧模板链。

实参：

cleanroom_name（字符串） – 应添加模板链的 Clean Room 的名称。
template_chain_name（字符串） – 模板链的名称。
templates（对象数组） - 对象数组，每个模板一个。该对象可包含以下字段：
- template_name（字符串）– 指定要添加到模板链的模板。模板必须已经通过调用 provider.add_template_chain 添加到 Clean Room。
- cache_results（布尔）– 确定模板的结果是否临时保存，以便模板链中的其他模板可以访问这些结果。要缓存结果，请指定 TRUE。
- output_table_name（字符串）– 如果 cache_results = TRUE，则指定存储模板结果的 Snowflake 表的名称。
- jinja_output_table_param（字符串）– 如果 cache_results = TRUE，则指定其他模板必须包括的 Jinja 参数的名称，以接受 output_table_name 中存储的结果。
- cache_expiration_hours（整型）– 如果 cache_results = TRUE，则指定删除缓存中结果之前的小时数。当缓存过期时，那么下次执行模板链时，缓存会使用模板的结果刷新。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.add_template_chain(
  $cleanroom_name,
  'my_chain',
  [
    {
      'template_name': 'crosswalk',
      'cache_results': True,
      'output_table_name': 'crosswalk',
      'jinja_output_table_param': 'crosswalk_table_name',
      'cache_expiration_hours': 2190
    },
    {
      'template_name': 'transaction_insights',
      'cache_results': False
    }
  ]
);

Copy

provider.view_added_template_chains¶

描述： 列出指定 Clean Room 中的模板链。

实参：

cleanroom_name（字符串） – Clean Room 的名称。

返回： （表） 添加到此 Clean Room 的所有模板链的描述。

示例：

call samooha_by_snowflake_local_db.provider.view_added_template_chains($cleanroom_name);

Copy

provider.view_template_chain_definition¶

描述： 返回模板链的定义。

实参：

cleanroom_name（字符串） – 与此模板链关联的 Clean Room 的名称。
template_chain_name（字符串） – 与此 Clean Room 关联的模板链的名称。

返回： （表） 指定模板链的描述。

示例：

call samooha_by_snowflake_local_db.provider.view_template_chain_definition($cleanroom_name, 'my_chain');

Copy

provider.clear_template_chain¶

**描述：**从指定的 Clean Room 删除指定的模板链。链不会存储在任何位置，因此如果要重新创建链，则必须从头开始重新创建。

实参：

*cleanroom_name（字符串） – 分配给此模板链的 Clean Room。
template_chain_name（字符串） – 要从此 Clean Room 移除的模板链。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.clear_template_chain($cleanroom_name, 'my_chain');

Copy

多提供商分析¶

这些过程支持多提供商分析。

provider.enable_multiprovider_computation¶

描述： 在指定用户提出请求时，此过程允许将您的 Clean Room 中的表与指定模板结合使用，也可以与指定 Clean Room 中的表结合使用。此过程让使用者能够对多个 Clean Room 中的数据运行查询。此过程不会自动批准这些请求，但通过将请求记录到此 Clean Room 的多提供商请求日志，可以开始对指定用户和 Clean Room 进行手动或自动批准流程。

即使在为此 Clean Room 调用 enable_multiprovider_computation 之前，任何使用 consumer.prepare_multiprovider_flow 对此 Clean Room 进行的调用都将保存并可见。

要让使用者能够访问您账户中的多个 Clean Room，请在 cleanroom_name 实参中指定一个 Clean Room，并在 approved_other_cleanrooms 实参中指定其他 Clean Room。

此过程要求在 Clean Room 中设置联接策略。

记录请求后，将根据给定用户和查询的请求流程进行批准。

请求记录启动后无法将其禁用，但是您可以暂停对给定用户的自动批准（如果您通过调用 provider.suspend_multiprovider_tasks 授予了权限），然后不再批准任何其他请求。

实参：

cleanroom_name（字符串） – 您拥有的 Clean Room 的名称。该 Clean Room 中的所有数据均可通过 consumer_account 在多提供商请求中与 approved_other_cleanrooms 中列出的 Clean Room 共享。
consumer_account（字符串） – 可以提出请求的使用者的账户定位器，如果获得批准，则结合 approved_other_cleanroom 中列出的任何 Clean Room 的数据，针对此 Clean Room 中的任何表运行查询。
approved_other_cleanrooms（字符串数组） – 完全限定 Clean Room 名称数组，此 Clean Room 的数据可以与之组合。每个条目的格式为 provider_org_name.provider_account_name.cleanroom_name。重要事项： 在每个 Clean Room 描述中提供 账户名称，而不是 账户定位器。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.enable_multiprovider_computation(
  $cleanroom_name,
  $consumer_account_locator,
  <org_name>.<account_locator>.<cleanroom_name>);

Copy

provider.view_multiprovider_requests¶

描述： 显示来自给定账户和 Clean Room 的所有多提供商分析请求。其中包括批准和拒绝的请求。提供商可以使用此过程来轮询请求，以便通过调用 provider.process_multiprovider_request 手动批准这些请求，也可以作为在给定 Clean Room 中查看来自给定使用者的所有请求的一种方式。

您必须为此 Clean Room 和使用者账户调用 enable_multiprovider_computation，然后才能调用 view_multiprovider_requests。

实参：

cleanroom_name（字符串） – 显示此 Clean Room 中来自指定使用者的请求。
consumer_account（字符串） – 显示此指定 Clean Room 中来自此使用者账户定位器的请求。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.view_multiprovider_requests($cleanroom_name, $consumer_locator);

Copy

provider.process_multiprovider_request¶

描述： 如果所有检查均通过，则批准执行指定的多提供商查询。检查内容包括请求的期限，以及提供商在之前调用 provider.enable_multiprovider_computation 时是否批准了该请求。使用者仍必须调用 consumer.execute_multiprovider_flow 才能运行该查询。如果未获批准，请求将在四小时后删除。

默认情况下，必须使用此过程处理所有多提供商请求。如果您希望该使用者在此 Clean Room 中提出的所有请求都自动获得批准，请为 request_id 指定 -1。如果您希望所有使用者在此 Clean Room 中提出的所有请求获得批准，请调用 provider.resume_multiprovider_tasks。了解如何撤销先前批准的请求。

评估请求后，将请求和评估状态写入到此 Clean Room 的日志表。

实参：

*cleanroom_name（字符串） – 使用者要求将其包含在多提供商分析中的 Clean Room 的名称。
consumer_account（字符串） – 请求多提供商分析的用户的使用者账户定位器。此定位器必须已获批准用于此 Clean Room 和在调用 provider.enable_multiprovider_computation 的请求中列出的其他 Clean Room。
request_id（字符串） – 要批准的请求 ID，来自 provider.view_multiprovider_requests。传入 -1 以批准此 Clean Room 中此使用者的所有请求。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.process_multiprovider_request($cleanroom_name_1, $consumer_account_locator, $request_id);

Copy

provider.suspend_multiprovider_tasks¶

描述： 停止在指定 Clean Room 的多提供商查询中的自动审核和批准（针对符合条件的查询）。 Clean Room 仍启用了多提供商查询，但现在每个请求都必须通过调用 provider.process_multiprovider_request 得到提供商的明确批准。

所有 Clean Room 的默认状态为禁用多提供商自动批准。要启用它，请调用 provider.resume_multiprovider_tasks。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
consumer_account（字符串） – 使用者的账户定位器，应对此 Clean Room 中的所有模板暂停该使用者的多提供商请求。此用户在此 Clean Room 中提出的请求稍后将删除。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.suspend_multiprovider_tasks($cleanroom_name, $consumer_locator);

Copy

provider.resume_multiprovider_tasks¶

描述： 支持在给定 Clean Room 中自动审查和批准（符合条件的查询）给定用户的多提供商分析。默认情况下，Clean Room 的自动审查处于禁用状态。

要停止自动批准，请调用 provider.suspend_multiprovider_tasks。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
consumer_account（字符串） – 使用者的账户定位器，在此 Clean Room 中该使用者的多供应商请求现在将排队等待。

返回： （字符串） 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.provider.resume_multiprovider_tasks('my_cleanroom', $consumer_locator);

Copy

激活¶

激活意味着将结果导出到提供商、使用者或第三方。阅读更多关于激活的信息。。

provider.set_activation_policy¶

描述： 定义哪些提供商列可以在激活模板中使用。只有激活策略中列出的列才能从提供商的数据集中激活。不设置激活策略会阻止任何提供商数据被激活。

调用此过程会清除提供商先前设置的任何激活策略。

实参：

cleanroom_name（字符串） – 应允许激活的 Clean Room 的名称。
columns（字符串数组） – 只有此处列出的列才能用于此 Clean Room 的激活模板。列名称格式为 template_name:fully_qualified_table_name:column_name。注意正确使用点 . 和冒号 : 标记。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [ 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',  
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);

Copy

provider.update_activation_warehouse¶

描述： 指定在提供商激活中将结果解密到输出表时应使用的仓库大小。用于解密的仓库是 DCR_ACTIVATION_WAREHOUSE。提供商为此仓库付款。

实参：

size（字符串） – 仓库大小。从 CREATE WAREHOUSE 命令中选择其中一个 WAREHOUSE_SIZE 值。

返回： （字符串） 成功消息。

示例：

CALL samooha_by_snowflake_local_db.provider.update_activation_warehouse('LARGE');

Copy

以提供商身份运行分析¶

了解如何运行提供商分析。

provider.enable_provider_run_analysis¶

描述： 使提供商（Clean Room 创建者）能够在指定的 Clean Room 中运行分析。默认处于禁用状态。然后，使用者必须调用 consumer.enable_templates_for_provider_run 来启用 Clean Room 中特定模板的提供商运行分析。之后，提供商可通过调用 provider.submit_analysis_request 运行分析。

了解更多有关提供商运行分析的信息。

重要

此过程必须在 provider.add_consumers 之后、使用者安装 Clean Room 之前调用。如果使用者在安装 Clean Room 后更改了此配置，则必须重新安装 Clean Room 以反映新的配置。

实参：

*cleanroom_name（字符串） – 应启用提供商运行分析的 Clean Room 的名称。
consumer_accounts（字符串数组） – 所有向此 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 中运行分析（默认已禁用）。

重要

此过程必须在 provider.add_consumers 之后、使用者安装 Clean Room 之前调用。如果用户在安装 Clean Room 后更改了此配置，则需要重新安装 Clean Room 以反映新的配置。

实参：

*cleanroom_name（字符串） – 应禁用提供商运行分析的 Clean Room 的名称。
consumer_account_locator（字符串） – 传递给 provider.enable_provider_run_analysis 的相同使用者账户名称列表。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.disable_provider_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);

Copy

library.is_provider_run_enabled¶

描述： 检查此 Clean Room 是否允许提供商运行分析。

实参：

cleanroom_name（字符串） – 要检查的 Clean Room 的名称。

返回： （字符串） 此 Clean Room 是否允许提供商运行分析。

示例：

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

Copy

provider.view_warehouse_sizes_for_template¶

描述： 使用给定模板查看提供商运行分析中可用的仓库大小和类型列表。使用者必须先在调用 consumer.enable_templates_for_provider_run 时填充列表。

实参：

consumer_account（字符串） – 将批准提供商运行请求的使用者的账户定位器。
cleanroom_name（字符串） – Clean Room 的名称。
template_name（字符串） – 提供商想要运行的模板的名称。
consumer_account（字符串） – 将批准提供商运行请求的使用者的账户定位器。

返回： 允许的仓库大小和类型的表。支持的仓库类型和大小字符串是 CREATE WAREHOUSE 命令中 WAREHOUSE_TYPE 和 WAREHOUSE_SIZE 属性使用的仓库类型和大小字符串。

示例：

CALL samooha_by_snowflake_local_db.PROVIDER.VIEW_WAREHOUSE_SIZES_FOR_TEMPLATE($cleanroom_name, $template_name, $consumer_account_loc);

Copy

provider.submit_analysis_request¶

描述： 提交分析，以便在 Clean Room 中运行。调用此过程之前，必须满足以下所有条件：

提供者必须在此 Clean Room 中具有启用的提供商运行分析。
使用者必须拥有指定模板的已批准提供商运行分析。
必须遵守使用者数据和模板上的所有联接和列策略。

模板在 Clean Room 内运行，结果安全地存储在 Clean Room 内。结果已加密，因此只有提供商可以看到结果。

实参：

cleanroom_name（字符串） – 应在其中运行模板的 Clean Room 的名称。
consumer_account_locator（字符串） – 此 Clean Room 中允许通过调用 consumer.enable_templates_for_provider_run 进行提供商运行分析的使用者的账户定位器。
template_name（字符串） – 要运行的模板的名称。
provider_tables（数组） – 要提供给模板的提供商表列表。此列表将填充 source_table 数组变量。
consumer_tables（数组） – 要提供给模板的使用者表列表。此列表将填充 my_table 数组变量。
analysis_arguments（对象） – JSON 对象，其中每个键都是您创建的模板中使用的实参名称。如果您想使用特定的仓库类型和大小，请选择 provider.view_warehouse_sizes_for_template 列出的类型和大小，然后使用以下字段指定它们：
- warehouse_type（字符串）– 仓库类型，使用者支持将其用于通过指定模板进行的提供商运行分析。
- warehouse_size（字符串）– 仓库大小，使用者支持将其用于通过指定模板进行的提供商运行分析。

返回： （字符串） 用于检查请求状态以及访问结果的请求 ID。保存此 ID，因为您将需要使用它来查看分析结果。

示例：

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'],
      'warehouse_type', 'STANDARD',        -- If this type and size pair were not listed by view_warehouse_sizes_for_template,
      'warehouse_size', 'LARGE'            -- the request will automatically fail.
    ));

Copy

provider.check_analysis_status¶

描述： 提供商调用此过程以检查提供商分析请求的状态。在开始查看请求状态之前，可能会有相当长的延迟。当分析标记为完成后，调用 provider.get_analysis_result 可查看结果。

实参：

cleanroom_name（字符串） – 在其中提出请求的 Clean Room 的名称。
request_id（字符串） – 由 provider.submit_analysis_request 返回的请求的 ID。
consumer_account_locator（字符串） – 向其发送请求的使用者的账户定位器。

返回： （字符串） 请求的状态，其中 COMPLETED 表示成功完成分析。可能的状态：

IN-PROGRESS：正在进行分析。
FAILED：分析执行过程中出现问题。
COMPLETED：分析已完成。
NOT FOUND：提供的实参没有产生任何结果（例如，错误的请求 ID）。

示例：

-- It can take up to 2 minutes for this to pick up the request ID after the initial request
call samooha_by_snowflake_local_db.provider.check_analysis_status(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT>'
);

Copy

provider.get_analysis_result¶

描述： 获取提供商运行分析的结果。您必须等到分析状态列为 COMPLETED 后才能得到结果。结果在 Clean Room 无限期存在。

实参：

cleanroom_name（字符串） – 向其发送请求的 Clean Room 的名称。
request_id（字符串） – 由 submit_analysis_request 返回的请求的 ID。
consumer_account_locator（字符串） – 传递到 submit_analysis_request 中的使用者的账户定位器。

返回： （表） 查询结果。

示例：

call samooha_by_snowflake_local_db.provider.get_analysis_result(
    $cleanroom_name, 
    $request_id, 
    $locator
);

Copy

管理 Clean Room 共享¶

使用以下命令，管理与使用者共享 Clean Room。

provider.view_consumers¶

描述： 列出获准访问 Clean Room 的使用者。它不会显示使用者是否已安装 Clean Room。

实参：

cleanroom_name（字符串） – 关注的 Clean Room。

返回： （表） – 可以访问 Clean Room 的使用者账户列表。

示例：

call samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Copy

provider.add_consumers¶

描述： 授予指定用户访问指定 Clean Room 的权限。Clean Room 可以通过 Web 应用程序和 API 访问。此操作不会覆盖以前调用的使用者列表。Clean Room 访问权限授予特定用户，而不是整个账户。请注意，使用者账户必须与提供商位于同一 Snowflake 区域，才能访问 Clean Room。您可以通过调用 select current_region(); 来检查您所在的区域

您可以通过调用 provider.view_consumers 来查看当前的使用者列表。

实参：

cleanroom_name（字符串） - 与指定用户共享的 Clean Room 名称。用户可以使用 API 或 Web 应用程序安装 Clean Room。
consumer_account_locators（字符串） – 由 CURRENT_ACCOUNT 返回的，以逗号分隔的使用者账户定位器列表。此列表应包含与 consumer_account_names 中数量相同、顺序相同的条目。
consumer_account_names（字符串） – 可通过调用 CURRENT_ORGANIZATION_NAME 检索的，格式为 {org_name}.{account_name} Org name，以逗号分隔的使用者数据共享账户 IDs 列表。通过调用 CURRENT_ACCOUNT_NAME 可检索 账户名称。此列表应包含与 consumer_account_locators 中列出的数量相同、顺序相同的条目。
enable_diffineral_privacy_tasks（布尔，可选） – 如果为 TRUE，则在此 Clean Room 中列出的用户提出的所有查询中强制执行差分隐私。这是一种使用默认值为列出的用户启用差分隐私的简单方法。要指定高级设置，请改为提供 privacy_settings 实参。差分隐私任务必须在此 Clean Room 中运行，才能启用差分隐私。默认值为 FALSE。
privacy_settings（字符串，可选） – 如果存在，则在 consumer_account_names 中的任何用户使用自定义模板时，将隐私设置应用于自定义模板。这是对象的字符串版本，其中包含一个 NULL 键和一个用于指定各种隐私设置的值。不要同时指定 enable_differential_privacy_tasks 和 privacy_settings。差分隐私任务必须在此 Clean Room 中运行，才能启用差分隐私。请参阅此对象的可用字段。

返回： 成功消息。请注意，该过程不会验证用户定位器或账户名称，因此成功仅表示提交的定位器已添加到此 Clean Room 的数据库。

示例：

-- Add consumer without differential privacy.
call samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
  'LOCATOR1,LOCATOR2',
  'ORG1.NAME1,ORG2.NAME2');

-- Add consumer and turn on differential privacy for all their queries.
CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name,
  'LOCATOR1',
  'ORGNAME.ACCOUNTNAME',
  '{
      "null": {
          "threshold_value": 5000,
          "differential": 1,
          "privacy_budget": 10,
          "epsilon": 0.1,
          "noise_mechanism": "Laplace"
      }}');

Copy

provider.remove_consumers¶

描述： 撤销指定 Clean Room 的账户访问权限。这种方法会阻止所提供账户中所有用户的访问。

您可以通过调用 provider.view_consumers 来查看当前的使用者列表。

实参：

cleanroom_name（字符串） – Clean Room 的 ID（不容易记住的名称）。
cleanroom_account_locators（字符串） – 以逗号分隔的用户账户定位器列表。账户中的所有用户都将无法访问 Clean Room。

返回： （字符串） – 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.remove_consumers($cleanroom_name, 'locator1,locator2,locator3');

Copy

provider.set_cleanroom_ui_accessibility¶

描述： 向所有登录此提供商账户登录的用户显示或隐藏 Web 应用程序中的 Clean Room。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
visibility_status（字符串） – 以下区分大小写的值之一：
- HIDDEN – 对当前提供商账户中的所有用户隐藏 Web 应用程序中的 Clean Room。Clean Room 仍可通过 API 调用访问。
- EDITABLE – 让 clean room 在 Web 应用程序中可见。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');

Copy

跨云协作¶

允许与其他云区域的使用者共享 Clean Room。了解详情。

library.enable_laf_on_account¶

描述： 在当前账户上启用 Cross-Cloud Auto-Fulfillment。需要 ACCOUNTADMIN 角色。

实参： 无

返回：（字符串）成功消息。

示例：

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.library.enable_laf_on_account();

Copy

library.is_laf_enabled_on_account¶

描述： 返回是否为此账户启用 Cross-Cloud Auto-Fulfillment。

返回： 如果为此账户启用了 Cross-Cloud Auto-Fulfillment，则为 TRUE，否则为 FALSE。

示例：

call samooha_by_snowflake_local_db.library.is_laf_enabled_on_account();

Copy

provider.enable_laf_for_cleanroom（已弃用）¶

此函数现已弃用，其功能现在由 provider.create_or_update_cleanroom_listing 处理。

描述： 启用 Cross-Cloud Auto-Fulfillment，允许您在协作者的 Snowflake 账户与提供商的账户位于不同区域时与协作者共享 Clean Room。Cross-Cloud Auto-Fulfillment 也称为 Listing Auto-Fulfillment (LAF)。

默认情况下，对于新 Clean Room，Cross-Cloud Auto-Fulfillment 是关闭的，即使该环境已启用。

重要

在执行此命令之前，必须由具有 ACCOUNTADMIN 角色的 Snowflake 管理员在您的 Snowflake 账户中启用 Cross-Cloud Auto-Fulfillment。有关在 Snowflake 账户中启用 Cross-Cloud Auto-Fulfillment 的说明，请参阅与不同区域的账户协作。

与其他区域的使用者协作会产生额外费用。有关这些费用的更多信息，请参阅 Cross-Cloud Auto-Fulfillment 费用。

实参：

*cleanroom_name（字符串） – 应跨区域共享的 Clean Room 的名称。管理员必须为账户启用 Cross-Cloud Auto-Fulfillment，然后才能共享单个 Clean Room。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);

Copy

provider.request_laf_cleanroom_requests¶

描述： 在提供商端为给定使用者设置跨云请求共享。账户管理员必须首先启用 Cross-Cloud Auto-Fulfillment，并且使用者必须调用了 consumer.setup_cleanroom_request_share_for_laf。

对于使用者定义的模板（其中提供商和使用者位于不同的云区域），此过程是必需的。

您可以反复调用此过程来检查请求的状态。当状态达到 FULFILLED 时，可以调用 provider.mount_laf_cleanroom_requests_share。状态可能需要 10 分钟才能达到 FULFILLED。

实参：

cleanroom_name（字符串） – 用于启用跨云请求共享的 Clean Room 的名称。
consumer_locator（字符串） – 要为其启用跨云请求共享的使用者的账户定位器。

返回： （字符串） 请求的状态消息：已创建、待处理或已履行。

示例：

CALL samooha_by_snowflake_local_db.provider.request_laf_cleanroom_requests(
  $cleanroom_name, $consumer_locator);

Copy

在 Clean Room 中使用 Python¶

provider.load_python_into_cleanroom¶

描述： 将自定义 Python 函数加载到 Clean Room。使用此过程加载到 Clean Room 的代码都对使用者不可见。Jinja 模板可以调用上传的代码。

了解如何在 Clean Room 中上传和使用 Python 代码。

此过程会递增 Clean Room 的补丁号并触发安全扫描。您必须等待扫描状态变为 APPROVED，然后才能与协作者共享最新版本。

此过程重载，并且具有两个签名，该签名与第五个实参的数据类型不同，它们决定了是内联上传代码还是从暂存区上的文件加载代码：

签名¶

内联 UDF 上传：

(cleanroom_name String, function_name String, arguments Array, packages Array, rettype String, handler String, code String)

Copy

从暂存区上传 UDF：

(cleanroom_name String, function_name String, arguments Array, packages Array, imports Array, rettype String, handler String)

Copy

实参：

cleanroom_name（字符串） – 应在其中加载脚本的 Clean Room 的名称。
function_name（字符串） – 此包的名称。在自定义模板中使用此名称可以使用实参描述的任何实参调用 处理程序 指定的函数。
arguments（字符串对数组） – 函数 function_name 所需的实参数组。每个实参都是一对以空格分隔的字符串，带有实参名称和其 SQL 数据类型。此条目用于用户文档，不会进行验证。例如：“size integer”、“month string”、“data variant”。
packages（字符串数组） – 代码使用的 Python 包名称列表。这些必须是标准 Python 包；您的 UDFs 不能调用其他上传的 UDFs。
imports（具有单个元素的字符串数组） – 仅在从暂存区上传 UDF 时存在。这是一个具有单个元素的字符串数组：相对于您上传代码的暂存区的暂存区地址。根暂存区路径可通过调用 provider.get_stage_for_python_files 获得。
ret_type（字符串） – 函数 处理程序 返回的值的 SQL 数据类型。例如：“整型”、“变体”。
handler（字符串） – 当模板调用 function_name 时应调用的代码中的入口点函数。
- 对于内联 UDF，这是函数的名称，例如：main。
- 对于从暂存区上传的代码，这是源文件名限定的函数名称，例如：myscript.main 。
code（字符串） – 仅在以内联代码形式上传 UDF 时存在。这应该是一个 Python UDF。

返回： （字符串） 成功或失败消息。

示例：

-- Inline UDF

call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name, 
    'assign_group',                      # Name of the UDF
    ['data variant', 'index integer'],   # Arguments of the UDF, along with their type
    ['pandas', 'numpy'],                 # Packages UDF will use
    'integer',                           # Return type of UDF
    'main',                              # Handler
    $$
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    $$
);

Copy

-- Upload from stage

call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'myfunc',                            # Name of the UDF
    ['data variant', 'index integer'],   # Arguments of the UDF
    ['numpy', 'pandas'],                 # Packages UDF will use
    ['/test_folder/assign_group.py'],    # Python file to import from a stage
    'integer',                           # Return type of UDF
    'assign_group.main'                  # Handler scoped to file name
);

Copy

provider.get_stage_for_python_files¶

描述： 如果您计划使用上传到暂存区的代码文件而不是内联代码定义来定义 Clean Room 中的自定义 Python 代码，则返回应将 Python 文件上传到的暂存区路径。在通过调用 provider.load_python_into_cleanroom 上传文件之前，该暂存区不存在，无法检查。

了解如何在 Clean Room 中上传和使用 Python 代码。

实参：

cleanroom_name（字符串） – 要向其中上传文件的 Clean Room 的名称。

返回： （字符串） 您应该上传代码文件的路径。将其用于 provider.load_python_into_cleanroom 中的 imports 实参。

示例：

call samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

Copy

provider.view_cleanrooom_scan_status¶

描述： 报告 DISTRIBUTION 设置为 EXTERNAL 的 Clean Room 的威胁扫描状态。扫描需要标记为“APPROVED”，然后才能设置或更改默认发布指令。扫描状态只需要用 EXTERNAL Clean Room 检查。

实参：

cleanroom_name（字符串） – 要检查状态的 Clean Room 的名称。

返回： （字符串） 扫描状态。

示例：

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Copy

Clean Room 元数据 getter 命令¶

使用以下命令可显示 Clean Room 的相关属性。

library.view_external_activation_history¶

描述： 查看当前账户的激活请求历史记录。

实参： 无

返回： 包含激活请求的详细信息和状态的表。

示例：

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.view_external_activation_history();

Copy

provider.mount_request_logs_for_all_consumers¶

描述： 允许提供商访问 Clean Room 的使用者向提供商返回的信息。如 API 参考中所述，必须在各种情况下调用此过程，才能开始获取或共享使用者信息。

实参：

cleanroom_name（字符串） – 要挂载请求日志的 Clean Room 的名称。

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);

Copy

provider.view_request_logs¶

描述： 查看此 Clean Room 的使用者发送的请求日志。首次调用前，必须调用 mount_request_logs_for_all_consumers。

实参：

cleanroom_name（字符串） – 要查看请求日志的 Clean Room 的名称。

返回： 针对 Clean Room 运行的查询的一系列日志（表）

示例：

call samooha_by_snowflake_local_db.provider.view_request_logs($cleanroom_name);

Copy

差分隐私¶

这些命令控制用户级别或提供商账户级别的差分隐私。详细了解差分隐私。

provider.set_privacy_settings¶

描述： 设置（或重置）指定使用者运行自定义模板时强制执行的隐私设置。这会替换该使用者的所有现有设置。

实参：

cleanroom_name（字符串） – Clean Room 的名称。
consumer_account_locator（字符串） – 以逗号分隔的列表形式显示一个或多个使用者的账户定位器。
privacy_settings（对象） – 为一个或多个模板指定差异隐私设置的 JSON 对象。设置适用于指定使用者运行的所有模板。请参阅此对象的可用字段。

返回： 成功消息。

示例：

-- Enforce differential privacy on queries by this consumer
-- with the settings provided.
CALL samooha_by_snowflake_local_db.provider.set_privacy_settings(
  $cleanroom_name, 
  $consumer_locator,
  { 'differential': 1,
    'epsilon': 0.1,
    'privacy_budget': 3 });

Copy

provider.is_dp_enabled_on_account¶

描述： 描述是否为此账户启用了差分隐私。

实参： 无

返回： 如果对此账户启用了差分隐私，则为 TRUE，否则为 FALSE。

示例：

call samooha_by_snowflake_local_db.provider.is_dp_enabled_on_account();

Copy

provider.suspend_account_dp_task¶

描述： 禁用监控和强制执行差分隐私预算的任务。此函数用于控制账户中与差分隐私相关的成本。如果禁用差分隐私任务，则指定差分隐私的用户、模板或 Clean Room 执行的查询中仍会增加噪音，但不会强制执行预算限制，也不会因差分隐私而产生费用。了解有关管理差分隐私的更多信息。

实参： 无

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.suspend_account_dp_task();

Copy

provider.resume_account_dp_task¶

描述： 恢复当前账户中的差分隐私任务监听器，并将强制执行差分隐私预算。之前设置的任何差分隐私值（如敏感度或关联用户）都将保留。

实参： 无

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.resume_account_dp_task();

Copy

Snowpark Container Services 命令¶

这些过程使您能够在 Clean Room 内使用 Snowpark Container Services。

provider.load_service_into_cleanroom¶

描述： 在 Clean Room 中创建或更新容器服务。调用此过程会更新 Clean Room 补丁号，因此必须在调用此过程之后调用 provider.set_default_release_directive。每次创建或更新服务时必须调用此过程。然后，客户端必须调用 consumer.start_or_update_service 才能查看更新。

参考:: 了解如何在 Clean Room 中使用 Snowpark Container Services。<label-cleanrooms_using_spcs>

实参：

cleanroom_name（字符串） – Clean Room 的名称。
service_spec（字符串） – 基于 spec 元素的服务的 YAML 规范。
service_config（字符串） – 服务的 YAML 格式配置。支持以下属性：
- default_service_options – 服务级别默认值的可选数组。使用者在创建服务时可以替换这些值。支持以下子属性：
  - min_instances （整数，可选）
  - max_instances （整数，可选）
  - allow_monitoring （布尔，可选） – 如果为 TRUE，则允许使用者查看服务日志。默认值为 FALSE。
- functions – 服务公开的函数数组。每个函数定义都映射到 SPCS 服务函数定义。请参阅该文档以了解每个元素的详细信息。支持以下子属性：
  - name
  - args
  - returns
  - endpoint
  - path
  - max_batch_rows（可选）
  - context_headers（可选）

返回：（字符串）如果成功，则返回成功消息。如果不成功，则会引发错误。

示例：

CALL samooha_by_snowflake_local_db.provider.load_service_into_cleanroom(
    $cleanroom_name,
    $$
    spec:
      containers:
      - name: lal
        image: /dcr_spcs/repos/lal_example/lal_service_image:latest
        env:
          SERVER_PORT: 8000
        readinessProbe:
          port: 8000
          path: /healthcheck
      endpoints:
      - name: lalendpoint
        port: 8000
        public: false
    $$,
    $$
    default_service_options:
      min_instances: 1
      max_instances: 1
      allow_monitoring: true
    
    functions:
      - name: train
        args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY, FILTER VARCHAR
        returns: VARCHAR
        endpoint: lalendpoint
        path: /train
      - name: score
        args: PROVIDER_TABLE VARCHAR, PROVIDER_JOIN_COL VARCHAR, CONSUMER_TABLE VARCHAR, CONSUMER_JOIN_COL VARCHAR, DIMENSIONS ARRAY
        returns: VARCHAR
        endpoint: lalendpoint
        path: /score
      - name: score_batch
        args: ID VARCHAR, FEATURES ARRAY
        returns: VARIANT
        max_batch_rows: 1000
        endpoint: lalendpoint
        path: /scorebatch
$$);

Copy

常规 helper 命令¶

使用以下命令一般有助于充分利用 Clean Room 功能和支持流程。

library.enable_local_db_auto_upgrades¶

描述： 启用任务 samooha_by_snowflake_local_db.admin.expected_version_task，该任务会在新版本发布时自动升级 Snowflake Data Clean Rooms Native App。虽然禁用该任务可能会降低成本，但我们建议让它继续运行，以确保您的系统上有最新版本的 Clean Room 原生应用程序。

实参： 无

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

Copy

library.disable_local_db_auto_upgrades¶

描述：禁用任务 samooha_by_snowflake_local_db.admin.expected_version_task，该任务会在新版本发布时自动升级 Snowflake Data Clean Rooms Native App。

实参： 无

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();

Copy

已弃用的过程¶

下列过程已弃用，在此处列出仅为保障列表完整性。如果指明了替换过程，请使用较新的过程。

provider.view_ui_registration_request_log -- DEPRECATED¶

注意

此命令现已弃用。 您不再需要手动注册 Clean Room 模板以在 Web 应用程序中使用。

描述： 查看从账户提出的将 Clean Room 注册到 Web 应用程序的请求的列表。每个请求都有关联的 ID，可与 view_ui_registration_log 程序结合使用，以查看请求的状态。请求共享到后端，在此处处理请求，并将 Clean Room 添加到 Clean Room。

实参：

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.view_ui_registration_request_log();

Copy

library.register_table_or_view – 已弃用¶

注意

此命令现已弃用。 改用 library.register_objects。

描述： 注册所有类型的表和视图。

实参： object_names（数组）、is_view（布尔）、is_iceberg（布尔）、is_external（布尔）、is_under_managed_access_schema（布尔）

返回： （字符串） 成功或失败消息。

示例

要注册表：

call samooha_by_snowflake_local_db.library.register_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);

Copy

要注册 Iceberg 表：

call samooha_by_snowflake_local_db.library.register_table_or_view(
        ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], 
        false, 
        true,
        false,
        false);

Copy

library.register_table – 已弃用¶

注意

此命令现已弃用。 改用 library.register_objects。

描述： 与 register_db 类似，但在表级运行。将此表的 SELECT 权限授予 SAMOOHA_APP_ROLE 角色，使用户能够将表链接到 Clean Room。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册表，请改用 library.register_managed_access_table。

实参： table_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.register_managed_access_table – 已弃用¶

注意

此命令现已弃用。 改用 library.register_objects。

描述：类似于 register_table，但在使用 WITH MANAGED ACCESS 参数创建的架构中注册表。可以传入表示完全限定表名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将表链接到 clean room 中。

实参： table_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.register_view – 已弃用¶

注意

此命令现已弃用。 改用 library.register_objects。

描述： 与 register_db 类似，但在视图级运行。可以传入表示完全限定视图名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将视图链接到 clean room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册视图，请改用 library.register_managed_access_view。

实参： view_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.register_managed_access_view – 已弃用¶

注意

此命令现已弃用。 改用 library.register_objects。

描述： 类似于 register_view，但在使用 WITH MANAGED ACCESS 参数创建的架构中注册视图。可以传入表示完全限定视图名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将视图链接到 clean room 中。

实参： view_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.unregister_table_or_view – 已弃用¶

注意

此命令现已弃用。 改用 library.unregister_objects。

描述： 取消注册所有类型的表和视图。

实参： object_names（数组）、is_view（布尔）、is_iceberg（布尔）、is_external（布尔）、is_under_managed_access_schema（布尔）

返回： （字符串） 成功或失败消息。

示例

要取消注册表：

call samooha_by_snowflake_local_db.library.unregister_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);

Copy

library.unregister_table – 已弃用¶

注意

此命令现已弃用。 改用 library.unregister_objects。

描述： 与 unregister_db 类似，但在表级运行。可以传入表示完全限定表名称的数组或字符串来取消注册表。用户无法将取消注册的表链接到 Clean Room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中取消注册表，请改用 library.unregister_managed_access_table。

实参： table_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.unregister_managed_access_table – 已弃用¶

注意

此命令现已弃用。 改用 library.unregister_objects。

描述：类似于 unregister_table，但在托管访问架构（即使用 WITH MANAGED ACCESS 创建的架构）中取消注册表。

实参： table_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.unregister_view – 已弃用¶

注意

此命令现已弃用。 改用 library.unregister_objects。

描述： 与 unregister_db 类似，但在视图级运行。可以传入表示完全限定视图名称的数组或字符串来取消注册视图。用户无法将取消注册的视图链接到 Clean Room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册视图，请改用 library.unregister_managed_access_view。

实参： view_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

library.unregister_managed_access_view – 已弃用¶

注意

此命令现已弃用。 改用 library.unregister_objects。

描述：类似于 unregister_view，但在托管访问架构（即使用 WITH MANAGED ACCESS 创建的架构）中取消注册视图。

实参： view_name（数组）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Copy

provider.create_cleanroom_listing – 已弃用¶

注意

此命令现已弃用。 改用 provider.create_or_update_cleanroom_listing。

描述： 配置 Clean Room 后，在 Snowflake Marketplace 上创建该 Clean Room 的专用列表，并与指定的协作者共享。

您可以使用账户 URL 的 orgname.account_name 格式来识别协作者。使用者可以按照查找账户的组织和账户名称 (https://user-guide/admin-account-identifier#finding-the-organization-and-account-name-for-an-account) 中的说明查找此字符串。

备注

要使用此程序，您需要设置发布指令。有关更多信息，请参阅 provider.set_default_release_directive。

实参： cleanroom_name（字符串）、consumer_account_name（字符串）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, <consumerorg.consumeracct>);

Copy

provider.register_cleanroom_in_ui -- DEPRECATED¶

注意

此命令现已弃用。 您不再需要手动注册 Clean Room 模板以在 Web 应用程序中使用。

描述： 注册 Clean Room，供使用者在 Web 应用程序中使用。Clean Room 由提供商使用开发者 APIs 创建和配置。然后，该命令会将其注册到 Web 应用程序中，供使用者安装、添加表并运行您添加的任何自定义分析，而无需使用开发者 APIs。他们完全通过 Web 应用程序的用户界面使用 Clean Room。

您可以多次调用该 API，将多个自定义模板添加到 Web 应用程序中。

实参： cleanroom_name（字符串）、template name（字符串）、consumer_account_locator（字符串）、user_email（字符串）

返回： （字符串） 成功或失败消息。

示例：

call samooha_by_snowflake_local_db.provider.register_cleanroom_in_ui($cleanroom_name, 'prod_custom_template', <CONSUMER ACCOUNT LOCATOR>, <USER_EMAIL>)

Copy

Snowflake Data Clean Room：提供商 API 参考指南¶

创建、配置和删除 Clean Room¶

provider.view_cleanrooms¶

provider.describe_cleanroom¶

provider.cleanroom_init¶

provider.set_default_release_directive¶

provider.drop_cleanroom¶

provider.enable_consumer_run_analysis¶

provider.disable_consumer_run_analysis¶

library.is_consumer_run_enabled¶

provider.create_or_update_cleanroom_listing¶

注册和取消注册数据¶

provider.register_db¶

library.register_schema¶

library.register_managed_access_schema¶

library.register_objects¶

library.enable_external_tables_on_account¶

provider.enable_external_tables_for_cleanroom¶

library.unregister_db¶

library.unregister_schema¶

library.unregister_managed_access_schema¶

library.unregister_objects¶

链接数据和表¶

provider.link_datasets¶

provider.unlink_datasets¶

provider.view_provider_datasets¶

provider.restrict_table_options_to_consumers¶

管理策略¶

provider.view_join_policy¶

provider.set_join_policy¶

管理提供商模板¶

provider.view_added_templates¶

provider.view_template_definition¶

provider.add_templates¶

provider.clear_template¶

provider.clear_all_templates¶

provider.set_column_policy¶

provider.view_column_policy¶

provider.add_custom_sql_template¶

provider.add_ui_form_customizations¶

provider.restrict_template_options_to_consumers¶

使用者自定义模板¶

provider.list_pending_template_requests¶

provider.list_template_requests¶

provider.approve_template_request¶

provider.approve_multiple_template_requests¶

provider.reject_template_request¶

provider.reject_multiple_template_requests¶

模板链¶

provider.add_template_chain¶

provider.view_added_template_chains¶

provider.view_template_chain_definition¶

provider.clear_template_chain¶

多提供商分析¶

provider.enable_multiprovider_computation¶

provider.view_multiprovider_requests¶

provider.process_multiprovider_request¶

provider.suspend_multiprovider_tasks¶

provider.resume_multiprovider_tasks¶

激活¶

provider.set_activation_policy¶

provider.request_provider_activation_consent¶

provider.update_activation_warehouse¶

provider.setup_provider_activation_share_mount_task¶

以提供商身份运行分析¶

provider.enable_provider_run_analysis¶

provider.disable_provider_run_analysis¶

library.is_provider_run_enabled¶

provider.view_warehouse_sizes_for_template¶

provider.submit_analysis_request¶

provider.check_analysis_status¶

provider.get_analysis_result¶

管理 Clean Room 共享¶

provider.view_consumers¶

provider.add_consumers¶

provider.remove_consumers¶

provider.set_cleanroom_ui_accessibility¶

跨云协作¶

library.enable_laf_on_account¶

library.is_laf_enabled_on_account¶