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

以下内容详细介绍了 Snowflake Data Clean Room 为使用者提供的所有开发者 APIs。所有函数都位于以下架构内：

samooha_by_snowflake_local_db.consumer

Copy

设置环境¶

在利用开发者 APIs 使用 Snowflake Data Clean Room 之前，请执行以下命令来设置 Snowflake 环境。如果您没有 SAMOOHA_APP_ROLE 角色，请联系账户管理员。

use role samooha_app_role;
use warehouse app_wh;

Copy

为提供商与您共享的 clean room 命名：

set cleanroom_name = 'Test Cleanroom 1';

Copy

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

Copy

consumer.is_enabled¶

描述：clean room 安装完毕后，提供商只需约 1 分钟即可完成设置并自行启用它。此函数允许用户检查 clean room 的状态，并查看其是否已启用。安装 clean room 约一分钟后，标志通常会切换为 True。

实参： cleanroom_name（字符串）

返回： 已启用（布尔值）

示例：

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

Copy

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

Copy

设置 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)

Copy

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)

Copy

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

Copy

注册和取消注册数据¶

使用以下命令注册和取消注册数据库、架构和对象。必须先注册表和视图，然后才能将其链接到 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');

Copy

library.register_schema¶

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

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

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

Copy

library.register_managed_access_schema¶

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

实参： schema_name（数组）

返回： success message（字符串）

示例：

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

Copy

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（字符串）

示例

要注册表和视图：

call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

Copy

library.register_table_or_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.register_objects。

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

实参： 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);

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 类似，但在表级运行。可以传入表示完全限定表名称的数组或字符串，并授予 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']);

Copy

library.register_managed_access_table – 已弃用¶

注意

此命令现已弃用。 请使用 library.register_objects。

描述：类似于 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']);

Copy

library.register_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.register_objects。

描述：与 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']);

Copy

library.register_managed_access_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.register_objects。

描述：类似于 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']);

Copy

library.unregister_db¶

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

实参： db_name（字符串）

返回： success message（字符串）

示例：

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（数组）

返回： success message（字符串）

示例：

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（数组）

返回： success message（字符串）

示例：

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（数组） – 应该撤消访问权限的完全限定对象名称数组。

返回： success message（字符串）

示例

要取消注册表和视图：

call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

Copy

library.unregister_table_or_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.unregister_objects。

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

实参： 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);

Copy

library.unregister_table – 已弃用¶

注意

此命令现已弃用。 请使用 library.unregister_objects

描述：与 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']);

Copy

library.unregister_managed_access_table – 已弃用¶

注意

此命令现已弃用。 请使用 library.unregister_objects

描述：类似于 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']);

Copy

library.unregister_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.unregister_objects

描述：与 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']);

Copy

library.unregister_managed_access_view – 已弃用¶

注意

此命令现已弃用。 请使用 library.unregister_objects

描述：类似于 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']);

Copy

管理数据集¶

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.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);

Copy

consumer.unlink_datasets¶

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

输入： cleanroom_name（字符串）, 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']);

Copy

为 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.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);

Copy

consumer.set_column_policy¶

描述：设置提供商可对数据中的哪些列进行操作。只有在添加模板后才可调用此函数。这也是模板的一个函数，因此输入的形式必须是 template_name:full_table_name:column_name。请注意，列策略是 仅替换，因此如果再次调用该函数，先前设置的列策略将被当前策略完全替换。

不应在电子邮件地址等标识列上调用列策略。它只能用于聚合列和分组依据列。

检查在名为 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']);

Copy

模板¶

通过以下命令，用户可以使用 Clean Room 中可用的模板。

consumer.view_template_definition¶

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

备注

请注意，所有 Samooha 程序都已加密，默认情况下无法查看。不过，您添加的任何自定义模板对您来说都是可见的。

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

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

示例：

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

Copy

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

Copy

模板链¶

通过以下命令，用户可以使用 clean room 中可用的模板链。有关使用模板链的一般信息，请参阅使用开发者 APIs 按顺序执行模板。

consumer.view_added_template_chains¶

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

实参： cleanroom_name（字符串）

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

示例：

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);

Copy

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

Copy

consumer.get_arguments_from_template_chain¶

描述：返回模板链中所有模板的预期实参。

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

返回： 实参列表和规范（表）

示例：

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

Copy

运行分析¶

以下命令根据指定的模板执行特定的分析或激活。

consumer.run_analysis¶

描述：使用模板或模板链执行分析。使用者表和提供商表需要分别指定，而且如果不需要，某些输入可以为空。模板或模板链执行已经为特定分析配置的逻辑，并以表形式返回联接的数据。唯一可选的输入是“epsilon”值，即查询需要消耗多少不同的隐私预算。如果未指定，此输入的默认值为 0.1。

实参： cleanroom_name（字符串）、{template_name | template_chain_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.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['SAMOOHA_SAMPLE_DATABASE.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'
  )
);

Copy

激活¶

有关激活结果的更多信息，请参阅使用开发者 APIs 将结果发送到 Snowflake 账户进行激活。

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

Copy

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

Copy

使用者自定义模板¶

下列 APIs 允许您将使用者定义模板添加到 clean room。有关更多信息，请参阅使用开发者 API 添加使用者定义模板。

consumer.create_template_request¶

描述：向 clean room 提供商发送请求，要求他们批准自定义模板，以便将其添加到 clean room。

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

返回： 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 %};
  $$);

Copy

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

Copy

这是对之前调用的响应。如占位符所示插入您的 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;

Copy

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

Copy

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

Copy

consumer.view_provider_datasets¶

描述：查看提供商已添加到 clean room 的所有数据集。

实参： cleanroom_name（字符串）

返回： clean room 中的所有提供商数据集名称（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

Copy

consumer.view_join_policy¶

描述：概述用户可以在 clean room 内安全地联接哪些列，由使用者在使用者数据集上设置。

实参： cleanroom_name（字符串）

返回： 联接策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);

Copy

consumer.view_provider_join_policy¶

描述：概述用户可以在 Clean Room 内安全地联接哪些列，由提供商在提供商数据集上设置。

实参： cleanroom_name（字符串）

返回： 联接策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

Copy

consumer.view_added_templates¶

描述：查看 Clean Room 中的所有活动模板。

实参： cleanroom_name（字符串）

返回： 添加的模板（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

Copy

consumer.view_column_policy¶

描述：查看使用者已应用于 Clean Room 的所有列策略。

实参： cleanroom_name（字符串）

返回： 列策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);

Copy

consumer.view_provider_column_policy¶

描述：查看提供商已应用于 Clean Room 的所有列策略。

实参： cleanroom_name（字符串）

返回： 列策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

Copy

consumer.view_cleanrooms¶

描述：查看最近创建的所有 Clean Room（按创建日期排序）。

实参： 无

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

示例：

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

Copy

consumer.is_dp_enabled¶

描述：检查是否已在 Clean Room 中启用了差分隐私。

实参： cleanroom_name（字符串）

返回： Clean Room 是否启用了 DP（布尔）

示例：

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);

Copy

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

Copy

通用辅助方法¶

使用以下方法来协助通用 Clean Room 功能。

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

Copy

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

Copy

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

Copy

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

设置环境¶

安装 Clean Room¶

consumer.install_cleanroom¶

consumer.is_enabled¶

consumer.uninstall_cleanroom¶

设置 Provider Run Analysis¶

library.is_provider_run_enabled¶

library.is_consumer_run_enabled¶

consumer.enable_templates_for_provider_run¶

注册和取消注册数据¶

consumer.register_db¶

library.register_schema¶

library.register_managed_access_schema¶

library.register_objects¶

library.register_table_or_view – 已弃用¶

library.register_table – 已弃用¶

library.register_managed_access_table – 已弃用¶

library.register_view – 已弃用¶

library.register_managed_access_view – 已弃用¶

library.unregister_db¶

library.unregister_schema¶

library.unregister_managed_access_schema¶

library.unregister_objects¶

library.unregister_table_or_view – 已弃用¶

library.unregister_table – 已弃用¶

library.unregister_managed_access_table – 已弃用¶

library.unregister_view – 已弃用¶

library.unregister_managed_access_view – 已弃用¶

管理数据集¶

consumer.link_datasets¶

consumer.unlink_datasets¶

为 Provider Run Analysis 设置安全策略¶

consumer.set_join_policy¶

consumer.set_column_policy¶

模板¶

consumer.view_template_definition¶

consumer.get_arguments_from_template¶

模板链¶

consumer.view_added_template_chains¶

consumer.view_template_chain_definition¶

consumer.get_arguments_from_template_chain¶

运行分析¶

consumer.run_analysis¶

激活¶

consumer.set_activation_policy¶

consumer.approve_provider_activation_consent¶

consumer.run_activation¶

使用者自定义模板¶

consumer.create_template_request¶

consumer.generate_python_request_template¶

consumer.list_template_requests¶

Clean Room 元数据 getter 方法¶

consumer.describe_cleanroom¶

consumer.view_provider_datasets¶

consumer.view_join_policy¶

consumer.view_provider_join_policy¶

consumer.view_added_templates¶

consumer.view_column_policy¶

consumer.view_provider_column_policy¶

consumer.view_cleanrooms¶

consumer.is_dp_enabled¶

consumer.view_remaining_privacy_budget¶

通用辅助方法¶

consumer.set_cleanroom_ui_accessibility¶

library.enable_local_db_auto_upgrades¶

library.disable_local_db_auto_upgrades¶