Snowflake Data Clean Room：使用者 API 参考指南¶

完整访问示例：¶

USE ROLE SAMOOHA_APP_ROLE;

-- Call any clean room function here
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(...)

GRANT USAGE ON WAREHOUSE MY_WAREHOUSE TO SAMOOHA_APP_ROLE;

仅运行访问示例：¶

USE ROLE <ADMIN_ASSIGNED_ROLE>;

-- Call run-only consumer functions here
CALL samooha_by_snowflake_local_db.consumer.run_analysis(...)

consumer.grant_run_on_cleanrooms_to_role¶

描述： 授予指定角色在指定 Clean Room 上运行过程子集的权限。Clean Room 必须 安装 在此账户中，而非由此账户 创建。（也就是说，仅限于您是使用者的 Clean Room。）

要授予 Clean Room 有限的使用权限，请授予用户指定角色而非 SAMOOHA_APP_ROLE。了解有关角色访问权限的详情。

以下过程可使用此处指定的角色运行：

• CONSUMER.VIEW_ADDED_TEMPLATE_CHAINS

• CONSUMER.RUN_ANALYSIS

• CONSUMER.VIEW_ADDED_TEMPLATES

• CONSUMER.VIEW_REMAINING_PRIVACY_BUDGET

• CONSUMER.GET_ARGUMENTS_FROM_TEMPLATE

实参：

• cleanroom_names（字符串数组） – 要授予指定角色有限访问权限的所有 Clean Room 的名称。

• run_role_name（字符串） – 对指定 Clean Room 具有有限权限的角色的名称。必须在调用此过程之前创建角色。

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

示例：

CREATE ROLE MARKETING_ANALYST_ROLE;
CALL samooha_by_snowflake_local_db.consumer.grant_run_on_cleanrooms_to_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'MARKETING_ANALYST_ROLE'
);

consumer.revoke_run_on_cleanrooms_from_role¶

描述： 撤销指定角色在指定 Clean Room 上的权限。请注意，如果用户有权访问未撤销的角色，或者拥有 SAMOOHA_APP_ROLE，则他们仍然可以在指定 Clean Room 中运行 Clean Room 过程。

实参：

• cleanroom_names（字符串数组） – 此账户中一个或多个 Clean Room 的名称。

• run_role_name（字符串） – 对此账户中指定的 Clean Room 上不应再拥有有限权限的角色名称。

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

示例：

CALL samooha_by_snowflake_local_db.consumer.revoke_run_on_cleanrooms_from_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'TEMP_USERS_ROLE'
);

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

library.is_provider_run_enabled¶

描述：检查此 Clean Room 是否允许提供商运行分析。注意：在提供商可在此 Clean Room 中运行分析之前，仍然需要通过调用 consumer.enable_templates_for_provider_run 给予明确批准。

实参： cleanroom_name（字符串）

输出： enabled message（字符串）

示例：

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

consumer.enable_templates_for_provider_run¶

描述：授予提供商在所请求的 Clean Room 中运行分析的权限。在提供商调用 provider.enable_provider_run_analysis 以允许提供商在 Clean Room 上运行分析之后，调用此函数。consumer.enable_templates_for_provider_run 授予提供商权限，允许其在指定 Clean Room 内的指定模板中运行分析，次数不限。

实参：

• cleanroom_name（字符串） – 提供商可以运行分析的 Clean Room 的名称。

• template_names（字符串数组） – 提供商可以运行的 Clean Room 中一个或多个模板的名称数组。

• enable_differential_privacy（布尔） – 如果为 TRUE，则为 template_names 中列出的所有模板启用差分隐私。只有为 Clean Room 本身启用差分隐私时，才能为这些模板启用差分隐私。您可以通过调用 consumer.is_dp_enabled 检查 Clean Room 的差分隐私状态。

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

示例：

call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);

consumer.register_db¶

描述：将数据库添加到 Clean Room 后，您就可以链接数据库中的任何数据集。如果没有调用此函数，则必须单独向 samooha_app_role 授予权限。

实参： db_name（字符串）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');

library.register_schema¶

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

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

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

library.register_managed_access_schema¶

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

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

library.register_objects¶

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

实参：

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

返回： success message（字符串）

示例

要注册表和视图：

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

library.enable_external_tables_on_account¶

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

实参： 无

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

示例：

USE ROLE ACCOUNTADMIN;

CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();

consumer.enable_external_tables_for_cleanroom¶

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

实参：

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

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

示例：

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
    $cleanroom_name);

library.register_table_or_view – 已弃用¶

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

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

输出 success message（字符串）

示例

要注册表：

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

要注册 Iceberg 表：

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

library.register_table – 已弃用¶

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

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

实参： table_name（数组）

返回： success message（字符串）

示例：

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

library.register_managed_access_table – 已弃用¶

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

实参： table_name（数组）

返回： success message（字符串）

示例：

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

library.register_view – 已弃用¶

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

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

实参： view_name（数组）

返回： success message（字符串）

示例：

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

library.register_managed_access_view – 已弃用¶

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

实参： view_name（数组）

返回： success message（字符串）

示例：

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

library.unregister_db¶

描述：颠倒 register_db 过程，并移除向 SAMOOHA_APP_ROLE 角色和 Snowflake Data Clean Room 本地应用程序授予的数据库级权限。这样还会从 UI 下拉元素中移除所有数据库。

实参： db_name（字符串）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');

library.unregister_schema¶

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

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

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

library.unregister_managed_access_schema¶

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

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

library.unregister_objects¶

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

实参：

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

返回： success message（字符串）

示例

要取消注册表和视图：

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

library.unregister_table_or_view – 已弃用¶

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

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

输出 success message（字符串）

示例

要取消注册表：

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

library.unregister_table – 已弃用¶

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

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

实参： table_name（数组）

返回： success message（字符串）

示例：

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

library.unregister_managed_access_table – 已弃用¶

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

实参： table_name（数组）

返回： success message（字符串）

示例：

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

library.unregister_view – 已弃用¶

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

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

实参： view_name（数组）

返回： success message（字符串）

示例：

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

library.unregister_managed_access_view – 已弃用¶

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

实参： view_name（数组）

返回： success message（字符串）

示例：

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

consumer.link_datasets¶

描述：将表或视图链接到 Clean Room，根据您指定的任何联接和列策略，使该 Clean Room 内的模板可以访问该表。

实参：

• cleanroom_name（字符串） – Clean Room 的名称，用于授予权限。

• tables_list（字符串数组） – 要提供给 Clean Room 的完全限定表或视图名称的列表。这些对象必须首先用适当的 注册方法 注册（提供 Clean Room 环境）。

返回： success message（字符串）

示例：

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

consumer.unlink_datasets¶

描述：删除所有用户对指定 Clean Room 中指定表或视图的访问权限。这仅适用于使用者提供的数据。

实参：

• cleanroom_name（字符串） – 应删除访问权限 Clean Room 的名称。

• tables_list（字符串数组） – 应阻止访问权限的完全限定表或视图名称的列表。

返回： success message（字符串）

示例：

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

consumer.view_consumer_datasets¶

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

实参：

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

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

示例：

call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

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.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.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.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:CAMPAIGN']);

consumer.view_template_definition¶

描述：Clean Room 模板定义可帮助确定哪些参数需要传递给模板。

如果应用 is_mbscated 实参 隐藏了 模板，则无法看到模板定义。

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

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

示例：

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.view_added_template_chains¶

描述：查看 clean room 中当前激活的模板链。

实参： cleanroom_name（字符串）

返回： 添加的模板链（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);

consumer.view_template_chain_definition¶

描述：返回模板链的属性。

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

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

示例：

call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');

consumer.run_analysis¶

描述：使用模板或模板链执行分析并返回结果表。

如果启用了差分隐私，则在已达到此模板的预算限制时，查询可能会失败。

如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能运行模板。

实参：

• cleanroom_name（字符串） – 拥有要运行模板的 Clean Room 的名称。

• template_name（字符串） – 要在 Clean Room 中运行的模板或模板链的名称。

• consumer_tables（字符串数组） – 完全限定使用者表名称数组。它们被分配给 my_table 模板变量。这些表必须已经链接到 Clean Room。通过调用 consumer.view_consumer_datasets 查看可用表。例如，如果您传入['mytable1','mytable2','mytable3']，则模板可以分别以 {{my_table[0]}}、{{my_table[1]}} 和 {my_table[2]} 的形式访问这些值。

• provider_tables（字符串数组） – 完全限定提供商表名称数组。它们被分配给 source_table 模板变量。这些表必须已经链接到 Clean Room。通过调用 consumer.view_provider_datasets 查看可用表。例如，如果您传入 ['sourcetable1','sourcetable2','sourcetable3']，则模板可以分别以 {{source_table[0]}}、{{source_table[1]}} 和{{source_table[2]}} 的形式访问这些值。

• analysis_arguments（对象） – 具有传递给模板的键/值对的对象。模板可以通过键名访问变量。如果您传递 {'age': 20}，模板将以 {{age}} 的形式访问该值。如果不需要值，则传入空对象。要查看需要哪些值，请通过调用 consumer.view_template_definition 检查相关模板。如果提供列名，请检查模板以确定是否需要使用表名限定列名。如果表别名为 p 或 c，则为列名使用小写形式的 p 和 c 表别名。即使用 p.age_band，而非 P.age_band。此对象有一个可选的保留值：

  • epsilon （浮动，可选） – 如果对此 Clean Room 启用了差分隐私，则指定 差分隐私的 esilon 值 (link removed)。默认值为 0.1。

• use_cache（布尔，可选） – 是否对同一查询使用缓存结果。默认值为 FALSE。

返回： （表） 查询结果。

示例：

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'],      -- Provider tables
  object_construct(
    'max_age', 30
  )
);

library.view_external_activation_history¶

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

实参： 无

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

示例：

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.view_external_activation_history();

consumer.set_activation_policy¶

描述：定义哪些列可以在激活模板中使用。这可以确保只有使用者批准的列可以与激活模板一起使用。

输入：cleanroom_name（字符串）、columns（数组）

columns 实参以 <template_name>:<fully_qualified_table_name>:<column_name> 格式传递。

输出： 成功消息

示例：

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

consumer.approve_provider_activation_consent¶

描述：批准提供商的请求以允许提供商激活，即将结果推送到提供商的 Snowflake 账户的能力。假设提供商已经调用 provider.request_provider_activation_consent 以请求许可。

输入：cleanroom_name（字符串）、activation_template_name（字符串）

输出： 成功消息

示例：

call consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');

consumer.run_activation¶

描述：执行一个模板，将结果推送回 Snowflake 账户进行激活。

输入： cleanroom_name（字符串）、segment_name（字符串）、template_name（字符串）、consumer_tables（数组）、provider_tables（数组）activation_arguments（对象）、consumer_direct_activation（布尔）、application_id（字符串）

如果使用者将结果推送到自己的 Snowflake 账户进行激活，请将 consumer_direct_activation 实参设置为 TRUE。

将空字符串作为实参传递给 application_id。

返回： 成功消息

示例：

call samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  'my_activation_segment',
  'activation_custom_template',
  ['consumer_source_table'], 
  ['provider_source_table'],
  object_construct(                 -- 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.
    'where_clause', 'p.EMAIL=c.EMAIL'
  ));

consumer.create_template_request¶

描述：向 Clean Room 提供商发送请求，要求他们批准自定义模板，以便将其添加到 Clean Room。请参阅 使用开发者 API 添加使用者定义的模板。

实参：

• cleanroom_name（字符串） – 适用此模板的 Clean Room 的名称。

• template_name（字符串） – 模板的名称。必须全部是小写字母、数字、空格或下划线。激活模板的名称必须以“activation”开头。

• template_Definition（字符串） – JinjaSQL 模板。了解模板语法。

返回： success message（字符串）

示例：

  CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom', 
  'my_analysis', 
  $$
  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 %};
  $$);

consumer.get_sql_jinja¶

描述： 将 JinjaSQL 模板评估为有效的 SQL 语句。此过程只能处理标准 JinjaSQL (https://github.com/sripathikrishnan/jinjasql) 语句；不能处理 join_policy 或 column_policy 等 JinjaSQL Clean Room 扩展。

实参：

• template_string（字符串） – 待处理模板。仅支持标准 JinjaSQL。

• arguments（对象） – 一个对象，其中的字段名与模板中使用的变量相对应，值会插入到所生成查询中模板中相应的变量占位符中。

返回：（字符串）* 提交的模板生成的 SQL 语句，其中包含提供的变量值。

示例：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GET_SQL_JINJA(
$$
SELECT COUNT(*), IDENTIFIER({{ group_by_col }})
  FROM IDENTIFIER({{ my_table | sqlsafe }})
  INNER JOIN IDENTIFIER({{ source_table | sqlsafe }})
  ON IDENTIFIER({{ consumer_join_col }}) = IDENTIFIER({{ provider_join_col }})
  GROUP BY IDENTIFIER({{ group_by_col }});
$$,
object_construct(
'group_by_col', 'city',
'consumer_join_col', 'hashed_email',
'provider_join_col', 'hashed_email',
'my_table', 'mydb.mysch.t1',
'source_table', 'mydb.mysch.t2'));

响应：

SELECT COUNT(*), IDENTIFIER('city')
  FROM IDENTIFIER(mydb.mysch.t1)
  INNER JOIN IDENTIFIER(mydb.mysch.t2)
  ON IDENTIFIER('hashed_email') = IDENTIFIER('hashed_email')
  GROUP BY IDENTIFIER('city');

consumer.generate_python_request_template¶

描述：生成包含自定义 Python 代码的使用者 clean room 模板。生成的模板包含您的 Python 代码和 JinjaSQL 模板占位符。将最终模板传递给 consumer.list_template_requests。

了解有关使用者定义模板的更多信息。

实参：

• function_name（字符串） – SQL 模板应调用 Python 函数的名称来执行函数。

• arguments（字符串数组） – Python 函数的实参列表，其中每个实参都是空格分隔的字符串对，格式为“<argument_name> <argument_type>”。例如：['data variant', 'scale integer']。

• packages（字符串数组） – Python 代码所需的包名称数组。如果没有，请指定一个空数组。示例：['pandas','numpy']。

• imports（字符串数组） – Python 代码所需的任何自定义 Python 库。应该是零个或多个暂存区地址的数组。示例：['@db.schema.stage/my_python_sproc.py']

• rettype（字符串） – 函数的 SQL 返回类型。示例：'integer'、'varchar'。

• handler（字符串） – Python 代码中主处理程序函数的名称。这通常是 'main'。

• code（字符串） – 您的 Python 代码实施。如果您包含一个导入，并且您的指定处理程序是在导入中定义的，则可以是空字符串。

返回： 生成的 Python 模板（字符串）。将占位符替换为 SQL 代码。

示例：

使用一个简单的 Python 示例调用辅助函数。

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
  'my_func',                         // SQL should use this name to call your function
  ['data variant', 'index integer'], // Arguments and types for the function
  ['pandas', 'numpy'],               // Standard libraries used
  [],                                // No custom libraries needed.
  'integer',                         // Return type integer
  'main',                            // Standard main handler
// Python implementation as UDF  
  $$
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)
    $$
);

这是对之前调用的响应。如占位符所示插入您的 JinjaSQL，并将其传递到 consumer.create_template_request。

BEGIN

-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')

HANDLER = 'main'
AS '
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)
    ';
        

-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';

-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);

END;

consumer.list_template_requests¶

描述：列出消费者向 clean room 添加模板的请求。

实参： cleanroom_name（字符串）

返回： request_id（字符串）、provider_identifier（字符串）、template_name（字符串）、template_definition（字符串）、request_status（字符串）、reason（字符串）

示例：

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');

consumer.describe_cleanroom¶

描述：创建文本摘要，其中包含已添加到 Clean Room 的所有信息，包括模板、数据集、策略等。如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能查看模板名称。

实参： 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 中的所有活动模板。如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能查看模板。

实参： cleanroom_name（字符串）

返回： 添加的模板（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

library.is_consumer_run_enabled¶

描述：检查此 Clean Room 是否允许使用者运行分析。此标志确定 Clean Room 使用者（安装者）是否可在此 Clean Room 中运行分析。

实参： cleanroom_name（字符串）

输出： enabled message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($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。在结果表中：

• IS_ALREADY_INSTALLED：如果已联接 Clean Room，则为 True（Web 应用程序中的 已联接 选项卡）；如果您已被邀请联接 Clean Room，但尚未联接 Clean Room，则为 False（Web 应用程序中的 已邀请 选项卡）。

  已知问题： – 此方法有时无法显示未安装的 Clean Room。如果您知道某个 Clean Room 已与您共享，但未显示在列表中，请调用 consumer.describe_cleanroom 查看该 Clean Room 是否可以联接。

实参： 无

返回： 按创建日期排序的所有现有 Clean Room（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = FALSE;

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。预算每日重置。

SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;

实参： cleanroom_name（字符串）

返回： 剩余的隐私预算（浮点）

示例：

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

consumer.set_cleanroom_ui_accessibility¶

描述：为当前账户中的使用者显示或隐藏 Web 应用程序中的 clean room。

实参：

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

• visibility_status（字符串） – 以下区分大小写的值之一：

  • HIDDEN – 对当前使用者账户中的所有用户隐藏 Web 应用程序中的指定 clean room。Clean Room 仍可通过 API 调用访问。

  • EDITABLE – 让 clean room 在 Web 应用程序中可见。

返回： success message（字符串）

示例：

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

library.enable_local_db_auto_upgrades¶

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

实参： 无

返回： success message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

library.disable_local_db_auto_upgrades¶

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

实参： 无

返回： success message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();