Snowflake Data Clean Room：使用者 API 参考指南¶
以下内容详细介绍了 Snowflake Data Clean Room 为使用者提供的所有开发者 APIs。所有函数都位于以下架构内：
samooha_by_snowflake_local_db.consumer
设置环境¶
在利用开发者 APIs 使用 Snowflake Data Clean Room 之前，请执行以下命令来设置 Snowflake 环境。如果您没有 SAMOOHA_APP_ROLE 角色，请联系账户管理员。
use role samooha_app_role;
use warehouse app_wh;
为提供商与您共享的 Clean Room 命名：
set cleanroom_name = 'Test Cleanroom 1';
安装 Clean Room¶
通过以下命令安装提供商共享的 Clean Room：
consumer.install_cleanroom¶
描述：将 Clean Room 安装到具有相关联提供商和所选 Clean Room 的使用者账户中。
输入： cleanroom_name（字符串）, provider_account_locator（字符串）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');
consumer.is_enabled¶
描述：Clean Room 安装完毕后，提供商只需约 1 分钟即可完成设置并自行启用它。此函数允许用户检查 Clean Room 的状态，并查看其是否已启用。安装 Clean Room 约一分钟后，标志通常会切换为 True。
输入： cleanroom_name（字符串）
输出： 已启用（布尔值）
示例：
call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
consumer.uninstall_cleanroom¶
描述：卸载使用者账户中的 Clean Room。卸载会移除与 Clean Room 相关联的所有数据库，包括共享的 Clean Room 数据库。请注意，始终可以使用 consumer.install_cleanroom 再次安装 Clean Room。
输入： cleanroom_name（字符串）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
设置 Provider Run Analysis¶
library.is_provider_run_enabled¶
描述：检查此 Clean Room 是否已启用 Provider Run Analysis。注意：仍需通过调用 consumer.enable_templates_for_provider_run 获得明确批准（见下文）。
输入： cleanroom_name（字符串）
输出： enabled message（字符串）
示例：
call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
library.is_consumer_run_enabled¶
描述：检查此 Clean Room 是否已启用 Consumer Run Analysis。此标志决定了 Clean Room 使用者（安装者）是否可以运行分析，或者作为数据贡献者参与协作。
输入： cleanroom_name（字符串）
输出： enabled message（字符串）
示例：
call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
consumer.enable_templates_for_provider_run¶
描述：如果 Clean Room 已启用 Provider Run Analysis（即 Clean Room 的提供商已将 Clean Room 标记为允许提供商运行分析），则使用者必须调用此程序以启用 Provider Run Analysis。必须通过此程序，逐个模板地给想要运行分析的提供商提供明确批准。
如果将最后一个布尔参数设置为 TRUE，使用者就可以对提供商的分析启用差分隐私。
输入： cleanroom_name（字符串）, template_names（数组）, enable_differential_privacy（布尔值）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
添加数据集¶
consumer.link_datasets¶
描述：用户可将 Snowflake 表链接到 Clean Room，并通过在 Clean Room 内创建表的安全视图来共享该表。
输入： cleanroom_name（字符串）, tables_list（数组）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS']);
为 Provider Run Analysis 设置安全策略¶
consumer.set_join_policy¶
描述：指定在使用 Provider Run Analysis 时，允许提供商在 Clean Room 内运行模板时对哪些列执行联接。请注意，列策略是 仅替换，因此如果再次调用该函数，先前设置的列策略将被当前策略完全替换。
请注意，进行检查的方式是解析为查找任何未经授权的列而要对数据运行的 SQL 查询。使用这些检查可能无法找出含有通配符的查询，因此，设计分析模板时仍应慎重。
输入： cleanroom_name（字符串）, table_and_col_names（数组）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.EXPOSURES:EMAIL']);
consumer.set_column_policy¶
描述：设置提供商可对数据中的哪些列进行操作。只有在添加模板后才可调用此函数。这也是模板的一个函数，因此输入的形式必须是 template_name:full_table_name:column_name。请注意，列策略是 仅替换，因此如果再次调用该函数，先前设置的列策略将被当前策略完全替换。
不应在电子邮件地址等标识列上调用列策略。它只能用于聚合列和分组依据列。
请注意，进行检查的方式是解析为查找任何未经授权的列而要对数据运行的 SQL 查询。使用这些检查可能无法找出含有通配符的查询，因此，设计分析模板时仍应慎重。
检查在名为 dimensions 或 measure_columns 的 SQL Jinja 实参上进行。请确保使用这两个标签来启用此检查。
输入： cleanroom_name（字符串）, analysis_and_table_and_columns（数组）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:STATUS',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:AGE_BAND',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS:DAYS_ACTIVE',
'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.EXPOSURES:CAMPAIGN']);
分析提供商模板¶
通过以下命令，用户可以运行在 Clean Room 中可用的分析模板。
consumer.view_template_definition¶
描述：Clean Room 模板定义可帮助确定哪些参数需要传递给模板。
备注
请注意，所有 Samooha 程序都已加密，默认情况下无法查看。不过，您添加的任何自定义模板对您来说都是可见的。
输入： cleanroom_name（字符串）, template_name（字符串）
输出： The template definition（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');
consumer.get_arguments_from_template¶
描述：定义应如何组织数据以及每个模板需要哪些数据，以确保输出易于理解。
输入： cleanroom_name（字符串）, template_name（字符串）
输出： 实参列表和规范（表）
示例：
call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');
运行分析¶
以下命令将执行特定分析：
consumer.run_analysis¶
描述：使用者可在使用者数据库中选定的表和输入集上运行提供商分析模板。使用者表和提供商表需要分别指定，而且如果不需要，某些输入可以为空。模板执行已经为特定分析配置的逻辑，并以表形式返回联接的数据。唯一可选的输入是“epsilon”值，即查询需要消耗多少不同的隐私预算。如果未指定，此输入的默认值为 0.1。
输入： cleanroom_name（字符串）, template_name（字符串）, consumer_tables（数组）, provider_tables（数组）, analysis_arguments（对象）
输出： 模板计算输出（表）
示例：
call samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name, -- cleanroom
'prod_overlap_analysis', -- template name
['SAMOOHA_SAMPLE_DATABASE_NAV2.MYDATA.CONVERSIONS'], -- Consumer tables
['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.EXPOSURES'], -- Provider tables
object_construct( -- Rest of the custom arguments needed for the template
'dimensions', ['p.CAMPAIGN'], -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
'measure_column', ['p.EXP_COST'],
'measure_type', ['COUNT'],
'where_clause', 'p.EMAIL=c.EMAIL'
)
);
Clean Room 元数据 getter 方法¶
以下方法显示了 Clean Room 的相关属性：
consumer.describe_cleanroom¶
描述：创建文本摘要，其中包含已添加到 Clean Room 的所有信息，包括模板、数据集、策略等。
输入： cleanroom_name（字符串）
输出： Clean Room 的详细描述字符串（表）
示例：
call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
consumer.view_provider_datasets¶
描述：查看提供商已添加到 Clean Room 的所有数据集。
输入： cleanroom_name（字符串）
输出： Clean Room 中的所有提供商数据集名称（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
consumer.view_join_policy¶
描述：概述用户可以在 Clean Room 内安全地联接哪些列，由使用者在使用者数据集上设置。
输入： cleanroom_name（字符串）
输出： 联接策略（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
consumer.view_provider_join_policy¶
描述：概述用户可以在 Clean Room 内安全地联接哪些列，由提供商在提供商数据集上设置。
输入： cleanroom_name（字符串）
输出： 联接策略（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
consumer.view_added_templates¶
描述：查看 Clean Room 中的所有活动模板。
输入： cleanroom_name（字符串）
输出： 添加的模板（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
consumer.view_column_policy¶
描述：查看使用者已应用于 Clean Room 的所有列策略。
输入： cleanroom_name（字符串）
输出： 列策略（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
consumer.view_provider_column_policy¶
描述：查看提供商已应用于 Clean Room 的所有列策略。
输入： cleanroom_name（字符串）
输出： 列策略（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
consumer.view_cleanrooms¶
描述：查看最近创建的所有 Clean Room（按创建日期排序）。
输入：
输出： 按创建日期排序的所有现有 Clean Room（表）
示例：
call samooha_by_snowflake_local_db.consumer.view_cleanrooms();
consumer.is_dp_enabled¶
描述：检查是否已在 Clean Room 中启用了差分隐私。
输入： cleanroom_name（字符串）
输出： Clean Room 是否启用了 DP（布尔值）
示例：
call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
consumer.view_remaining_privacy_budget¶
描述：查看可用于从 Clean Room 进行查询的剩余隐私预算。一旦耗尽，在重置预算之前，将不允许继续调用 run_analysis。预算每日重置。
未启用差分隐私时，隐私预算被任意设置为较高水平（如 10000），且不会耗尽。
输入： cleanroom_name（字符串）
输出： 剩余的隐私预算（浮点）
示例：
call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
常规 helper 方法¶
下面列出一系列 helper 方法，它们通常有助于利用 Clean Room 功能和支持的流程。
consumer.register_db¶
描述：将数据库添加到 Clean Room 后，您就可以链接数据库中的任何数据集。如果没有调用此函数，则必须单独向 samooha_app_role 授予权限。
输入： db_name（字符串）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
library.unregister_db¶
描述：允许您移除 register_db 进行的授予（即授予 samooha_app_role 对数据库的访问权限）。这也将从 UI 下拉菜单中移除任何数据库。
输入： db_name（字符串）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
library.register_table¶
描述：此命令与 register_db 类似，但在表级别运行。可以传入表示完全限定表名的数组或字符串，并通过运行 grant select 语句向 samooha_app_role 授予权限，使用户能够将表链接到 Clean Room 中。
输入： table_name（数组）
输出： success message（字符串）
示例：
call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE_NAV2.DEMO.CUSTOMERS']);