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

view_cleanrooms¶

架构:

PROVIDER

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

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();

describe_cleanroom¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room to get information about.

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

示例：

CALL samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

cleanroom_init¶

架构:

PROVIDER

Description: Creates a clean room with the specified name in your account. This procedure can take a minute or more to run. The clean room isn't visible in the clean rooms UI or to collaborators until after you call create_or_update_cleanroom_listing.

实参：

• cleanroom_name (String) - Clean room name, 80 characters maximum. Valid characters: [A-Z,a-z,0-9,_] and spaces.

• distribution - (String, optional) One of the following values:

  • INTERNAL (Default) - Clean room is visible only to users in the same organization and does not trigger a security scan before changing the default version.

  • EXTERNAL - Clean room is production ready and can be shared outside the organization. The clean room triggers a security scan before changing the default version. If you want to change the distribution after a clean room is created, call ALTER PACKAGE as shown here:

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

set_default_release_directive¶

架构:

PROVIDER

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

The clean room application creates a new version of a clean room whenever you upload or change Python code. If you want users to be served the newest version, call this procedure with the new version number. To see the available versions and their status, or the current release directive, run the appropriate SQL command:

-- See all versions, including failed versions.
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>;

-- See current release directive.
SHOW RELEASE DIRECTIVES IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>;

Where <cleanroom_name> follows this format.

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

• 版本：V1_0

• 补丁：0

实参：

• cleanroom_name (String) - Clean room name.

• version - (String) Version. Must always be "V1_0".

• patch - (String) Patch number loaded by the consumer. This starts at 0, and you should increment it whenever a new clean room version is available. You can see the available versions as described above.

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

示例：

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

drop_cleanroom¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room to delete.

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

示例：

CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

enable_consumer_run_analysis¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room in which consumer-run analyses are allowed.

• consumer_accounts - (Array of string) Account locators of all consumers to enable this feature for. NOTE: These consumers must already have been added to the clean room.

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

示例：

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

disable_consumer_run_analysis¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Clean room where consumer-run analysis is being disabled.

• consumer_accounts - (Array of string) Account locators of consumers that cannot run an analysis in this clean room. NOTE: These consumers must already have been added to the clean room.

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

示例：

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

is_consumer_run_enabled¶

架构:

LIBRARY

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

实参：

• cleanroom_name (String) - Name of the clean room to check.

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

示例：

CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)

create_or_update_cleanroom_listing¶

架构:

PROVIDER

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

首次发布 Clean Room 时，可能需要最多 15 分钟的时间才能在 Clean Room UI 中看到 Clean Room。

If you make updates to a clean room without calling this method afterwards, there is no guarantee that the changes will be propagated to consumers.

There is a limit to the number of clean rooms + collaborators that you can create in a single account. If you create too many test clean rooms, you might need to delete a few in order to create new clean rooms. If you need more clean rooms than your account can hold, contact Snowflake support.

实参：

• cleanroom_name (String) - Name of the clean room to publish or update.

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

错误处理：

If you get an error saying that "Cross-Cloud Auto-Fulfillment is not enabled for this account", it means that one of the consumers is in another cloud hosting region. You must enable Cross-Cloud Auto-Fulfillment as described in 在 Snowflake Data Clean Rooms 中管理 Cross-Cloud Auto-Fulfillment.

示例：

CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name
);

register_db¶

架构:

PROVIDER

Description: Enables a database and all objects within it to be linked into individual clean rooms in this clean room environment. This procedure grants USAGE and SELECT privileges on the database to SAMOOHA_APP_ROLE, which is used by the clean room environment to access data.

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

实参：

• db_name - (String) Name of database to register.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.provider.register_db('SAMOOHA_SAMPLE_DATABASE');

register_schema¶

架构:

LIBRARY

Description: Similar to register_db, but operates at a schema level. You must have MANAGE GRANTS privilege on the schema to call this procedure.

This procedure grants USAGE and SELECT privileges on the schema to SAMOOHA_APP_ROLE, which is used by the clean room environment to access data.

If you want to register a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.register_managed_access_schema instead.

实参：

• schema_name - (Array of string) An array of one or more fully qualified schema names to register.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

register_managed_access_schema¶

架构:

LIBRARY

Description: Similar to register_schema, but registers a schema that was created using the WITH MANAGED ACCESS parameter. You must have MANAGE GRANTS privileges on the schema to call this procedure.

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

实参：

• schema_name - (Array of string) An array of one or more fully qualified schema names.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.register_managed_access_schema(
  ['SAMOOHA_SAMPLE_DATABASE.DEMO']
);

register_objects¶

架构:

LIBRARY

Description: Grants the clean room access to tables and views of all types, making them available to be linked into the clean room by calling provider.link_datasets. You can register broader groups of objects by calling library.register_schema, library.register_managed_access_schema, or provider.register_db.

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

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

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

实参：

• object_names - (array) Array of fully qualified object names. These objects can then be linked into the 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'
  ]
 );

enable_external_tables_on_account¶

架构:

LIBRARY

Description: Enable Iceberg or external tables to be used in all clean rooms in this account. Must be called by an ACCOUNTADMIN in both the provider and consumer accounts to allow Iceberg or external tables to be linked by either account. To limit this ability to specific clean rooms in this account, call enable_external_tables_for_cleanroom instead.

If successful and all security scans pass, this generates a new patch version of the clean room.

实参： 无

Returns: (String) Success message. If successful, it triggers a security scan and also provide the number of the patch that will be generated if the security scan succeeds.

示例：

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();

enable_external_tables_for_cleanroom¶

架构:

PROVIDER

Description: Enable Iceberg or external tables to be linked into the specified clean room in this account by the provider. To allow Iceberg and external tables for all clean rooms in this account, call enable_external_tables_on_account instead.

If successful, this will generate a new patch version of the clean room.

实参：

• cleanroom_name (String) - The name of the clean room into which the provider can link Iceberg or external tables.

Returns: (String) Success message. If successful, it triggers a security scan and also provide the number of the patch that will be generated if the security scan succeeds.

示例：

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
  $cleanroom_name);

unregister_db¶

架构:

LIBRARY

Description: Reverses the register_db procedure and removes the database-level grants given to the SAMOOHA_APP_ROLE role and Snowflake Data Clean Room native application. This also removes any database from the selector in the clean rooms UI.

实参：

• db_name - (String) Name of the database to unregister.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');

unregister_schema¶

架构:

LIBRARY

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

If you want to unregister a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.unregister_managed_access_schema instead.

实参：

• schema_name - (array) Schemas to unregister.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_schema(
  ['SAMOOHA_SAMPLE_DATABASE.DEMO']
);

unregister_managed_access_schema¶

架构:

LIBRARY

Description: Similar to unregister_schema, but unregisters a schema that was created using the WITH MANAGED ACCESS parameter.

实参：

• schema_name - (array) Managed schemas to unregister.

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

示例：

USE ROLE <role_with_manage_grants>;
CALL samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

unregister_objects¶

架构:

LIBRARY

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

实参：

• object_names - (array) Array of fully-qualified object names for which access should be revoked.

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

示例

要取消注册表和视图：

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

link_datasets¶

架构:

PROVIDER

Description: Links a Snowflake table or view into the clean room. The procedure automatically makes the table accessible to the clean room by creating a secure view of the table within the clean room, without any requirement to copy your table. The table is linked to its source, so updates in the source appear in the secure version within the clean room.

If the dataset includes a Snowflake policy that is stored in a different database, you (or a clean rooms administrator) must grant your clean room access to that policy database to enable linking the data into a clean room.

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

实参：

• cleanroom_name (String) - Name of the clean room with access to the objects.

• tables_list - (Array of string) List of tables or views to link into the clean room. Objects must be registered before they can be linked in.

• consumer_list - (Array of string, optional) If present, allows only consumers listed here to access these objects. If absent, allows anyone with access to the clean room to access this data.

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

示例：

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

unlink_datasets¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of clean room linked to these data sets.

• tables_list - (array) Array of table or view names to unlink from the clean room.

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

示例：

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

view_provider_datasets¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room.

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

restrict_table_options_to_consumers¶

架构:

PROVIDER

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

Consumers granted access through provider.link_datasets, provider.restrict_table_options_to_consumers, or any other method will lose access to a table if it isn't specified when calling this method.

实参：

• cleanroom_name (String) - Name of the clean room to restrict.

• access_details - (Object) A JSON object, where each field name is the fully qualified name of a table or view, and the field value is an array of account locators of users who can access that table or view.

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

示例：

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

view_join_policy¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room to query.

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

set_join_policy¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room where the join policy should be enforced.

• table_and_col_names - (Array of string) Fully qualified column name in the format database_name.schema_name.table_or_view_name:column_name. Note the correct use of . versus : marks

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

示例：

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

view_added_templates¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Clean room to query.

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

view_template_definition¶

架构:

PROVIDER

Description: Shows information about a specific template. Consumers looking at a provider template should use consumer.view_template_definition.

实参：

• cleanroom_name (String) - Name of the clean room with this template.

• template_name - (String) Name of the template to request information about.

Returns: (String) The template definition.

示例：

CALL samooha_by_snowflake_local_db.provider.view_template_definition(
  $cleanroom_name,
  $template_name);

add_templates¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room to add templates to.

• template_names - (Array of string) Name of the templates to add. These are Snowflake-provided templates only. To add a custom template, call add_custom_sql_template.

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

示例：

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['my_custom_template']);

clear_template¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room.

• template_name - (String) Name of the template to remove from that clean room.

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

示例：

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

clear_all_templates¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room from which to remove all templates.

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

示例：

CALL samooha_by_snowflake_local_db.provider.clear_all_templates($cleanroom_name);

set_column_policy¶

架构:

PROVIDER

Description: Sets which columns in the data are available to a specified template in the clean room as non-join rows. Columns must be either declared here or in set_join_policy to be used in the clean room. Columns listed here can be used anywhere in the template except as a join column. A column cannot be listed in both a column policy and a join policy.

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

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

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

实参：

• cleanroom_name (String) - Name of the clean room.

• analysis_and_table_and_cols - (Array of string) Array of columns that can be used by templates. The format for each column is: 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']);

view_column_policy¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String)

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

add_custom_sql_template¶

架构:

PROVIDER

Description: Adds a custom JinjaSQL template into the clean room. This makes the template callable by the consumer. Learn how to create custom templates.

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

If the template is used by the consumer to activate results back to the provider, the command must meet the following requirements:

• The name of the custom template must begin with the string activation. For example: activation_custom_template.

• The template must create a table that begins with cleanroom.activation_data_. For example: CREATE TABLE cleanroom.activation_data_analysis_results AS ....

• The template must return the unique part of the table name that was created in the definition, which is the string appended to cleanroom.activation_data_. For example, for the template named activation_data_analysis_results, you would return data_analysis_results.

实参：

• cleanroom_name (String) - Name of the clean room to which this template is applied.

• template_name - (String) Name of the template. Must be all lowercase letters, numbers, spaces, or underscores. Activation templates must have a name beginning with "activation".

• template - (String) The JinjaSQL template.

• sensitivity - (Float, optional) If differential privacy is enabled for this clean room, it controls the amount of differential privacy noise applied to the data returned by this template. Must be a number greater than 0. Default is 1.0. The differential privacy task must be running in this clean room for this argument to have any effect.

• consumer_locators - (Array of string, optional) An array of one or more account locators. If present, this template will be added to the clean room only for these accounts. You can later modify this list by calling provider.restrict_template_options_to_consumers. If you don't specify a list of consumers, all consumers can use the custom template in the specified clean room.

• is_obfuscated - (Boolean, optional) If TRUE, prevents consumers from being able to view the template body. Note that you must be using Snowflake Enterprise Edition or higher to run an obfuscated template. If this template is used for a provider-run analysis, the consumer must re-approve the analysis request any time you change the is_obfuscated state. is_obfuscated cannot be used together with sensitivity.

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

示例：

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
        IDENTIFIER({{ c.consumer_id  }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
      WHERE {{ where_clause | sqlsafe | join_and_column_policy }}
    {% endif %};
    $$);

add_ui_form_customizations¶

架构:

PROVIDER

Description: Defines a customization form for a template in a clean room when the clean room is run in the clean rooms UI. This is useful when you let consumers choose template parameters, such as tables or columns. At a minimum, you must specify values for display_name, description, and methodology in the template_information argument.

It is recommended to put table selection elements before column selection elements, especially when the column choosers populate based on the table selection.

Learn how to design user input forms for custom templates.

You must update the clean room after calling this function. If you do not call provider.create_or_update_cleanroom_listing after updating the UI, collaborators will not see any updates.

实参：

• cleanroom_name (String) - The name of the clean room that contains this template. The submitted form applies only to the specified template in the specified clean room.

• template_name - (String) Name of the template to which this UI applies. This is not the user-visible title, which is specified using the template_information.display_name field.

• template_information - (Dict) Meta information about the template to show in the clean rooms UI. The following properties must or can be defined:

  • display_name (Required): Display name of the template in the clean rooms UI.

  • description (Required): Description of the template.

  • methodology ( Required): Description of any arguments, and what the result is.

  • warehouse_hints (Object): Recommends what type of warehouse to use to run the analysis. This is an object with the following fields:

    • warehouse_size: See warehouse_size in CREATE WAREHOUSE for valid values.

    • snowpark_optimized (Boolean): Whether to use a Snowpark-optimized warehouse to process the query. For most machine learning use cases, Snowflake recommends TRUE.

  • render_table_dropdowns (Object): Whether to show the default drop-down lists that let the user select which provider or consumer tables to use in the query. This is an object with the following fields:

    • render_consumer_table_dropdown - (Boolean) If TRUE, show the default consumer table selector. If FALSE, hide the consumer tables selector. The template can access the chosen values as a list using the my_table template variable. If any element sets references=CONSUMER_TABLES, this defaults to FALSE, otherwise it defaults to TRUE.

    • render_provider_table_dropdown - (Boolean) If TRUE, show the default provider table selector. If FALSE, hide the provider tables selector. The template can access the chosen values as a list using the source_table template variable. If any element sets references=PROVIDER_TABLES, this defaults to FALSE, otherwise it defaults to TRUE.

  • activation_template_name - (String) Name of an activation template in this clean room. Use the template name without any cleanroom prefix. Learn about activation templates.

  • enabled_activations - (String) Which kind of activations are enabled. Possible values: consumer, provider. No default; must be provided if activation_template_name is specified.

• details - (Dict, optional) Defines user-configurable input fields that pass values to the template. This is a dictionary of key - object pairs, each pair representing one form element. The key is a variable name available to the linked JinjaSQL template. The value is an object that defines the form element. If a template variable doesn't have an equivalent form element defined here, clean rooms autogenerates a default form element. Each object can define the following fields:

  <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: Label text for this item in the UI form.

  • order: 1-based order in which this element should be shown in the form. If not specified, the elements will be rendered in the order in which they appear in the object.

  • description: A description of the element purpose, shown below the label. Provide short help or examples here. If not provided, none is shown.

  • type: The type of UI element. If references is specified for this input field, then omit this entry (the type is determined for you). Supported values:

    • any (Default): Regular text entry field.

    • boolean: True/False selector

    • integer: Use arrows to change the number

    • multiselect: Select multiple items from a dropdown list

    • dropdown: Select one item from a dropdown list

    • date: Date selector

  • default: Default value of this element

  • choices: (Array of string) List of choices for dropdown and multiselect elements

  • infoMessage: Informational hovertext shown next to the element. If not provided, no tooltip is provided.

  • size: Element size. Supported values: XS, S, M, L, XL

  • required: Whether a value is required by the user. Specify TRUE or FALSE.

  • group: A group name, used to group items in the UI. Use the same group name for items that should be grouped together in the UI. If you hide the default dropdown lists, you can use the {{ source_table }} and {{ my_table}} special arguments in the custom template, then define your own dropdown list that contains the desired tables. For more information about using these special variables when defining the custom template, see provider.add_custom_sql_template.

  • references: Populates a drop-down list with tables or columns of the specified type in the clean room. If used, type must be either multiselect or dropdown. The following string values are supported:

    • PROVIDER_TABLES: List all the provider's tables in the clean room. If specified, render_table_dropdowns.render_provider_table_dropdown must be FALSE.

    • PROVIDER_JOIN_POLICY: List all columns in the provider's join policy for the table currently selected in the provider_parent_table_field element.

    • PROVIDER_COLUMN_POLICY: List all columns in the provider's column policy for the current template and the table selected in the provider_parent_table_field element.

    • PROVIDER_ACTIVATION_POLICY: List all columns in the provider's activation policy.

    • CONSUMER_TABLES: List all the consumer tables in the clean room. If specified, render_table_dropdowns.render_consumer_table_dropdown must be FALSE.

    • CONSUMER_COLUMNS: List all columns in the consumer table specified by consumer_parent_table_field. You shouldn't use consumer column references in provider-run templates, as the consumer might apply join and column policies to these columns; use CONSUMER_JOIN_POLICY or CONSUMER_COLUMN_POLICY for provider-run templates instead.

    • CONSUMER_JOIN_POLICY: List all columns in the consumer's join policy from the table selected in the consumer_parent_table_field element.

    • CONSUMER_COLUMN_POLICY: List all columns in the consumer's column policy for the current template and the table selected in the consumer_parent_table_field field.

  • provider_parent_table_field: The name of the UI element where the user selects a provider table; don't provide the table name itself here. Use only when references is set to PROVIDER_COLUMN_POLICY or PROVIDER_JOIN_POLICY. To reference the default provider table chooser, specify source_table here and set render_table_dropdowns.render_provider_table_dropdown to TRUE.

  • consumer_parent_table_field: The name of the UI element where the user selects a consumer table; don't provide the table name itself here. Use only when references is set to CONSUMER_COLUMNS, CONSUMER_JOIN_POLICY, or CONSUMER_COLUMN_POLICY. To reference the default consumer table chooser, specify my_table here and set render_table_dropdowns.render_provider_table_dropdown to TRUE.

• output_config - (Dict) Defines how to display template results graphically in the clean rooms UI. If not provided, the results are not displayed in a graph, only in a table. If you do not want a graph, provide an empty object {} for this argument. Allowed fields:

  • measure_columns: Names of columns containing measures and dimensions to use in the graph generated by the clean rooms UI.

  • default_output_type: The default format to display the results. The user will typically be able to change the display format in the UI if the data is in the proper format. Supported types:

    • TABLE: (Default) Tabular format

    • BAR: Bar chart, which is good for comparing different categories

    • LINE: Line chart, which is good for showing trends over time or continuous data

    • PIE: Pie chart, which is suitable for showing proportions or percentages

The following table shows a matrix of values that are allowed in the details object for values that can conflict:

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

示例：

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

restrict_template_options_to_consumers¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - The name of the clean room.

• access_details - (JSON object) The name of a template and the users who can access that template in that clean room. If a template is specified, only users listed here can access that template in that clean room. This is an object with one child object per template in the following format: '{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']
  }
);

list_pending_template_requests¶

架构:

PROVIDER

Description: Lists all unapproved requests from consumers who want to add a consumer-defined template to a clean room. This includes pending, approved, and rejected requests. Use this procedure to check for pending requests and approve them (provider.approve_template_request) or reject them (provider.reject_template_request).

This will fail until all consumers that the clean room is shared with have installed the clean room.

实参：

• cleanroom_name (String) - View consumer requests to add a template to this clean room.

返回： 包含以下值的表：

• request_id - (String) ID of the request, needed to accept or reject the request.

• consumer_locator - (String) Account locator of the person making the request.

• template_name - (String) Name of the consumer-provided template.

• template_definition - (String) Full definition of the consumer-proposed template.

示例：

CALL samooha_by_snowflake_local_db.provider.list_pending_template_requests($cleanroom_name);

list_template_requests¶

架构:

PROVIDER

Description: Lists all requests from consumers who want to add a consumer-defined template to a clean room. This includes pending, approved, and rejected requests. Use this to check for pending requests and approve them (provider.approve_template_request) or reject them (provider.reject_template_request) .

实参：

• cleanroom_name (String) - View consumer requests to add a template to this clean room.

返回： 包含以下值的表：

• request_id - (String) ID of the request, needed to accept or reject the request.

• consumer_identifier - (String) Account locator of the person making the request.

• template_name - (String) Name of the consumer-provided template.

• template_definition - (String) Full definition of the consumer-proposed template.

• status - (String) Status of the request: PENDING, APPROVED, REJECTED.

示例：

CALL samooha_by_snowflake_local_db.provider.list_template_requests($cleanroom_name);

approve_template_request¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room the user wants to add the template to.

• request_id - (String) ID of the request to approve. Call provider.list_template_requests to see request IDs.

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

示例：

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

approve_multiple_template_requests¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - The name of the clean room to which this request applies.

• request_ids - (Array of strings) The IDs of all template requests to approve. To obtain a request ID, call 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'
  ]
);

reject_template_request¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room the user wants to add the template to.

• request_id - (String) ID of the request to reject. Call provider.list_template_requests to see request IDs.

• reason_for_rejection - (String) Reason for rejecting the request.

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

示例：

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

reject_multiple_template_requests¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room to which this request applies.

• rejected_templates - (array of objects) An array of objects with the following fields, one per rejection:

  • request_id - (string) ID of the request to reject. To obtain a request ID, call provider.list_template_requests.

  • reason_for_rejection - (string) A free-text description of why the request is being rejected.

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

示例：

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

add_template_chain¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room where the template chain should be added.

• template_chain_name - (String) Name of the template chain.

• templates - (Array of objects) - Array of objects, one per template. The object can contain the following fields:

  • template_name (String) - Specifies the template being added to the template chain. The template must already be added to the clean room by calling provider.add_template_chain.

  • cache_results (Boolean) - Determines whether the results of the template are temporarily saved so other templates in the template chain can access them. To cache results, specify TRUE.

  • output_table_name (String) - When cache_results = TRUE, specifies the name of the Snowflake table where template results are stored.

  • jinja_output_table_param (String) - When cache_results = TRUE, specifies the name of the Jinja parameter that other templates must include to accept the results that are stored in output_table_name.

  • cache_expiration_hours (integer) - When cache_results = TRUE, specifies the number of hours before the results in the cache are dropped. When the cache expires, the next time the template chain is executed, the cache is refreshed with the results of the template.

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

示例：

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

view_added_template_chains¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room.

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_added_template_chains($cleanroom_name);

view_template_chain_definition¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room associated with this template chain.

• template_chain_name - (String) Name of the template chain associated with this clean room.

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

示例：

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

clear_template_chain¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - The clean room that is assigned this template chain.

• template_chain_name - (String) The template chain to remove from this clean room.

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

示例：

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

enable_multiprovider_computation¶

架构:

PROVIDER

Description: This procedure enables tables from your clean room to be used in combination with the specified template, when requested by the specified user, and in combination with tables from the specified clean rooms. This procedure enables a consumer to run a query against data from multiple clean rooms. This procedure does not automatically approve these requests, but enables the manual or automated approval process to begin for the specified user and clean rooms by logging requests to the multi-provider request log for this clean room.

Any calls made to this clean room using consumer.prepare_multiprovider_flow will be saved and visible even before you call enable_multiprovider_computation for this clean room.

To enable a consumer to access multiple clean rooms in your account, specify one clean room in the cleanroom_name argument, and the others in the approved_other_cleanrooms argument.

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

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

There's no way to disable request logging after it's started, but you can suspend automated approval for a given user (if you granted it by calling provider.suspend_multiprovider_tasks) , and then not approve any further requests.

实参：

• cleanroom_name (String) - Name of a clean room that you own. All data in this clean room can be shared with clean rooms listed in approved_other_cleanrooms in multi-provider requests by consumer_account.

• consumer_account - (String) Account locator of a consumer who is allowed to make the request and, if approved, run a query against any tables in this clean room combined with data from any clean rooms listed in approved_other_cleanrooms.

• approved_other_cleanrooms - (Array of string) Array of fully qualified clean room names with which data from this clean room can be combined. The format of each entry is provider_org_name.provider_account_name.cleanroom_name. Important: Provide the account name, not the account locator, in each clean room description.

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

示例：

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

view_multiprovider_requests¶

架构:

PROVIDER

Description: Shows all requests for multi-provider analysis from a given account and clean room. This includes both approved and denied requests. Providers can use this procedure to poll for requests in order to approve them manually by calling provider.process_multiprovider_request, or as a way to see all requests from a given consumer in a given clean room.

You must call enable_multiprovider_computation for this clean room and consumer account before you can call view_multiprovider_requests.

实参：

• cleanroom_name (String) - Show requests from the specified consumer from this clean room.

• consumer_account - (String) Show requests from this consumer account locator from the specified clean room.

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

示例：

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

process_multiprovider_request¶

架构:

PROVIDER

Description: Approves execution of the specified multi-provider query, if all checks pass. Checks include the age of the request and whether or not the provider approved the request in a previous call to provider.enable_multiprovider_computation. The consumer must still call consumer.execute_multiprovider_flow to run the query. A request will be dropped after four hours if not approved.

By default, all multi-provider requests must be handled using this procedure. If you prefer that all requests from this consumer in this clean room be approved automatically, specify -1 for request_id. If you want all requests from all consumers in this clean room to be approved, call provider.resume_multiprovider_tasks. Learn how to revoke previously approved requests.

After the request is evaluated, the request and evaluation status are written to the log table for this clean room.

实参：

• cleanroom_name (String) - The name of your clean room, which a consumer is asking to include in a multi-provider analysis.

• consumer_account - (String) The consumer account locator of the user requesting multi-provider analysis. This locator must have been approved for this clean room and the other clean rooms listed in the request in a call to provider.enable_multiprovider_computation.

• request_id - (String) Request ID to approve, from provider.view_multiprovider_requests. Pass in -1 to approve all requests for this consumer in this clean room.

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

示例：

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

suspend_multiprovider_tasks¶

架构:

PROVIDER

Description: Stops automated review and approval (for qualifying queries) in a multi-provider query in the specified clean room. Multi-provider queries are still enabled for the clean room, but each request must now be explicitly approved by the provider by calling provider.process_multiprovider_request.

Default status for all clean rooms is that multi-provider automated approval is disabled. To enable it, call provider.resume_multiprovider_tasks.

实参：

• cleanroom_name (String) - Name of the clean room.

• consumer_account - (String) Account locator of the consumer whose multi-provider requests should be suspended for all templates in this clean room. Later requests by this user in this clean room will be dropped.

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

示例：

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

resume_multiprovider_tasks¶

架构:

PROVIDER

Description: Enables automated review of, and approval (for qualifying queries) of, multi-provider analyses for the given user in the given clean room. Automated review is disabled by default for a clean room.

To stop automated approval, call provider.suspend_multiprovider_tasks.

实参：

• cleanroom_name (String) - Name of the clean room.

• consumer_account - (String) Account locator of the consumer whose multi-provider requests in this clean room will now be queued.

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

示例：

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

set_activation_policy¶

架构:

PROVIDER

Description: Defines which provider columns can be used within an activation template. Only columns listed in an activation policy can be activated from the provider's data set. Not setting an activation policy prevents any provider data from being activated.

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

实参：

• cleanroom_name (String) - Name of the clean room where activation should be allowed.

• columns - (Array of string) Only columns listed here can be used in an activation template in this clean room. Column name format is template_name:fully_qualified_table_name:column_name. Note the proper usage of dot . and colon : markers.

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

示例：

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

request_provider_activation_consent¶

架构:

PROVIDER

描述： 向使用者发送请求，允许提供商运行指定模板并将结果推送到提供商的 Snowflake 账户。在后台，它将模板添加到 Clean Room 的提供商激活模板列表中。将模板指定为激活模板后，它只能在激活请求中使用。

实参：

• cleanroom_name (String) - Clean room that contains the activation template.

• template_name - (String) Name of the activation template to request approval for. This template must have been added to the clean room in a previous call. The template name must start with "activation".

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

示例：

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent(
    $cleanroom_name, 'activation_my_activation_template');

update_activation_warehouse¶

架构:

PROVIDER

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

实参：

• size - (String) Warehouse size. Choose one of the WAREHOUSE_SIZE values from the CREATE WAREHOUSE command.

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

示例：

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

setup_provider_activation_share_mount_task¶

架构:

PROVIDER

描述： 当提供商的账户中未安装 Clean Room UI 时，允许提供商激活操作。

Call this after adding consumers with provider.add_consumers. It is called only when you are implementing provider activation and you (the provider) do not have the clean room UI installed. (Whether or not the consumer has the UI installed does not matter.)

This starts a thread to asynchronously mount consumer shares needed for provider activation. Rather than mount the shares synchronously and block your code, this code mounts the share asynchronously and rechecks for new collaborators periodically. You need to call this only once, and can add additional collaborators later without needing to call this procedure again.

实参：

• frequency_minutes - (Integer) How often to recheck for new consumers in this clean room, in order to mount shares for them as well. A recommended value is 15.

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

示例：

CALL samooha_by_snowflake_local_db.provider.setup_provider_activation_share_mount_task(15);

dcr_health.provider_run_provider_activation_history¶

描述： 返回指定 Clean Room 的提供商激活请求历史记录。显示了由提供商和使用者发起的提供商激活请求。此过程提供了额外的信息，以帮助调试提供商激活方面的问题。

实参：

• cleanroom_name (String) - Name of the clean room in which the activation was requested. You must be a provider or consumer in this clean room.

Returns: (Table) - A list of activation requests with information about each, including the template and segment name, the status, the consumer's account locator, and any error message returned by the request.

示例：

CALL samooha_by_snowflake_local_db.dcr_health.provider_run_provider_activation_history(
  $cleanroom_name);

view_external_activation_history¶

架构:

LIBRARY

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

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.library.view_external_activation_history();

enable_provider_run_analysis¶

架构:

PROVIDER

Description: Enables the provider (clean room creator) to run analyses in a specified clean room. This is disabled by default. The consumer must then call consumer.enable_templates_for_provider_run to enable provider-run analyses for specific templates in the clean room. After that, the provider can run an analysis by calling provider.submit_analysis_request.

Learn more about provider-run analyses.

实参：

• cleanroom_name (String) - Name of the clean room that should enable provider-run analysis.

• consumer_accounts - (Array of string) Account locators of all consumer accounts that have added data to this clean room.

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

示例：

CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis(
  $cleanroom_name,
  ['<CONSUMER_ACCOUNT_LOCATOR>']
);

disable_provider_run_analysis¶

架构:

PROVIDER

描述： 阻止提供商（Clean Room 创建者）在 Clean Room 中运行分析（默认已禁用）。

实参：

• cleanroom_name (String) - Name of the clean room where provider-run analysis should be disabled.

• consumer_account_locator - (String) Same list of consumer account names passed to provider.enable_provider_run_analysis.

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

示例：

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

is_provider_run_enabled¶

架构:

LIBRARY

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

实参：

• cleanroom_name (String) - Name of the clean room to check.

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

示例：

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

is_request_back_share_mounted¶

架构:

PROVIDER

Description: Checks whether messages can be propagated from the specified consumer to the provider in the specified clean room. If a back share has not been mounted for this consumer in this clean room, messages such as provider-run request approvals aren't propagated from the consumer to the provider (though they will be queued on the consumer side).

Call provider.mount_request_logs_for_all_consumers to set up back sharing with this consumer. If you called provider.mount_request_logs_for_all_consumers previously and is_request_back_share_mounted fails, it's likely that you added this consumer to this clean room after you last called provider.mount_request_logs_for_all_consumers.

实参：

• cleanroom_name (String) - Name of the clean room to check.

• consumer_account - (String) Account locator of the consumer.

Returns: SUCCESS if back sharing is enabled for the specified consumer in the specified clean room. Throws an error otherwise.

示例：

CALL samooha_by_snowflake_local_db.library.is_request_back_share_mounted(
  $cleanroom_name,
  $consumer_locator);

view_warehouse_sizes_for_template¶

架构:

PROVIDER

Description: View the list of warehouse sizes and types available to use in provider-run analyses with a given template. The consumer must first populate the list in their call to consumer.enable_templates_for_provider_run.

实参：

• cleanroom_name (String) - Name of the clean room.

• template_name - (String) Name of the template that the provider wants to run.

• consumer_account - (String) Account locator of the consumer who will approve the provider-run request.

Returns: A table of permitted warehouse sizes and types. Supported warehouse type and size strings are those used by the WAREHOUSE_TYPE and WAREHOUSE_SIZE properties in the CREATE WAREHOUSE command.

示例：

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

submit_analysis_request¶

架构:

PROVIDER

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

• The provider must have enabled provider-run analyses in this clean room.

• The consumer must have approved provider-run analyses for the specified template.

• All join) and column) policies on the consumer data and the template must be respected.

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

实参：

• cleanroom_name (String) - Name of the clean room where the template should run.

• consumer_account_locator - (String) Account locator of the consumer in this clean room who has allowed provider-run analyses by calling consumer.enable_templates_for_provider_run.

• template_name - (String) Name of the template to run.

• provider_tables - (array) List of provider tables to expose to the template. This list will populate the source_table array variable.

• consumer_tables - (array) List of consumer tables to expose to the template. This list will populate the my_table array variable.

• analysis_arguments - (object) JSON object where each key is an argument name used in the template you created. If you want to use a specific warehouse type and size, choose a type and size listed by provider.view_warehouse_sizes_for_template and then specify them using the following fields:

  • warehouse_type (String) - A warehouse type that the consumer supports for provider-run analyses with the specified template.

  • warehouse_size (String) - A warehouse size that the consumer supports for provider-run analyses with the specified template.

返回： （字符串） 用于检查请求状态以及访问结果的请求 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.
  )
);

check_analysis_status¶

架构:

PROVIDER

Description: The provider calls this procedure to check the status of the provider analysis request. There can be a significant delay before you can start seeing the status of a request. When an analysis is marked as complete, call provider.get_analysis_result to see the results.

All consumers in the clean room must have their request logs mounted before you can call check_analysis_status. This is done once per consumer per clean room by calling provider.mount_request_logs_for_all_consumers.

You can see your list of analysis requests by running this SQL command, where cleanroom_name is your clean room name, with spaces replaced by underscores.

SELECT * FROM SAMOOHA_CLEANROOM_<cleanroom_name>.ADMIN.PROVIDER_ANALYSIS_REQUESTS;

实参：

• cleanroom_name (String) - Name of the clean room where the request was made.

• request_id - (String) ID of the request, returned by provider.submit_analysis_request.

• consumer_account_locator - (String) Account locator of the consumer to whom the request was sent.

Returns: (String) Status of the request, where COMPLETED means a successful completion of the analysis. Possible statuses:

• IN-PROGRESS：正在进行分析。

• PENDING: Indicates one of the following cases:

  • The request is still propagating, which can take a few minutes. Try again in a few minutes.

  • The user has not approved the request by calling consumer.enable_templates_for_provider_run. Try again in a few minutes.

  • You have not mounted the request logs for this consumer. Call provider.is_request_back_share_mounted; if that procedure not return SUCCESS, call provider.mount_request_logs_for_all_consumers.

• COMPLETED: The analysis is complete. You can call provider.get_analysis_result.

Errors:

If you see an error "ResultSet is empty or not prepared", this can indicate that at request logs were not mounted for at least one consumer in this clean room. Call provider.mount_request_logs_for_all_consumers to mount request logs for all consumers.

示例：

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

get_analysis_result¶

架构:

PROVIDER

Description: Get the results for a provider-run analysis. Do not call get_analysis_result until provider.check_analysis_status returns COMPLETED. Analysis results persist in the clean room indefinitely.

实参：

• cleanroom_name (String) - Name of the clean room for which the request was sent.

• request_id - (String) ID of the request, returned by submit_analysis_request.

• consumer_account_locator - (String) Account locator of the consumer passed in to submit_analysis_request.

返回： （表） 查询结果。

示例：

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

view_consumers¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - The clean room of interest.

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

add_consumers¶

架构:

PROVIDER

Description: Grants the specified users access to the specified clean room. The clean room can be accessed both through the clean rooms UI and the API. This doesn't overwrite the consumer lists from previous calls. Clean room access is granted to a specific user, not an entire account. The consumer account must be in the same Snowflake region as the provider to be able to access a clean room. You can check your region by calling select current_region();

You can see the current list of consumers by calling provider.view_consumers.

实参：

• cleanroom_name (String) - Name of the clean room to share with the specified users. Users can install the clean room using either the clean rooms API or UI.

• consumer_account_locators - (String) A comma-delimited list of consumer account locators, as returned by CURRENT_ACCOUNT. This list should include the same number of entries, in the same order, as contained in consumer_account_names.

• consumer_account_names - (String) A comma-delimited list of consumer data sharing account IDs for the consumer in the format org_name.account_name Org name can be retrieved by calling CURRENT_ORGANIZATION_NAME. Account name can be retrieved by calling CURRENT_ACCOUNT_NAME. This list should include the same number of items, in the same order, as listed in consumer_account_locators.

• enable_differential_privacy_tasks - (Boolean, optional) TRUE to enforce differential privacy in all queries by the listed users in this clean room. This is a simple way to enable differential privacy with default values for the listed users. To specify advanced settings, provide the privacy_settings argument instead. The differential privacy task must be running in this clean room to enable differential privacy. Default is FALSE.

• privacy_settings - (String, optional) If present, applies privacy settings to custom templates when used by any of the users in consumer_account_names. This is a string version of an object with a single NULL key and a value that specifies various privacy settings. Do not specify both enable_differential_privacy_tasks and privacy_settings. The differential privacy task must be running in this clean room to enable differential privacy. See the available fields for this object.

返回： 成功消息。请注意，该过程不会验证用户定位器或账户名称，因此成功仅表示提交的定位器已添加到此 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"
    }
  }'
);

remove_consumers¶

架构:

PROVIDER

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

You can see the current list of consumers by calling provider.view_consumers.

实参：

• cleanroom_name (String) - The ID of the clean room (not the user-friendly name).

• cleanroom_account_locators - (String) A comma-delimited list of user account locators. All users in the account will lose access to the clean room.

Returns: (String) - Success message.

示例：

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

set_cleanroom_ui_accessibility¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - The name of the clean room.

• visibility_status - (String) One of the following case-sensitive values:

  • HIDDEN - Hides the clean room in the clean rooms UI from all users in the current provider account. The clean room is still accessible for API calls.

  • EDITABLE – 让 Clean Room 在 Clean Room UI 中可见。

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

示例：

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

enable_laf_on_account¶

架构:

LIBRARY

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

实参： 无

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

示例：

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

disable_laf_on_account¶

架构:

LIBRARY

描述： 在当前账户上禁用 Cross-Cloud Auto-Fulfillment。运行此过程需要 ACCOUNTADMIN 角色。

实参： 无

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

示例：

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.disable_laf_on_account();

is_laf_enabled_on_account¶

架构:

LIBRARY

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

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.library.is_laf_enabled_on_account();

set_laf_dcr_refresh_schedule¶

架构:

PROVIDER

Description: Sets the refresh interval for clean room data between the provider and the consumer when they are located on different cloud regions. This data includes provider datasets, provider run requests, clean room policies, and clean room metadata. If you need an immediate refresh, you can call SYSTEM$TRIGGER_LISTING_REFRESH.

实参：

• schedule - (Int) Interval, in minutes, between refreshes. The minimum allowed value is 10.

Returns: (String) - Success message.

示例：

CALL samooha_by_snowflake_local_db.provider.set_laf_dcr_refresh_schedule(10);

load_python_into_cleanroom¶

架构:

PROVIDER

描述： 将自定义 Python 代码加载到 Clean Room。使用此过程加载到 Clean Room 的代码都对使用者不可见。Jinja 模板可以调用上传的代码。尽管您的代码可能包含多个函数定义，但一个模板只能调用一个函数。

If you want to load multiple callable Python packages into a clean room in a single patch, call prepare_python_for_cleanroom instead.

Learn how to upload and use Python code in a clean room.

This procedure increments the patch number of your clean room and triggers a security scan. You must wait for the scan status to be APPROVED before you can share the latest version with collaborators. This step does not report syntax errors in the code, which are thrown at run time.

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

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

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

Returns: (String) Success message if the upload succ

示例：

-- Inline UDF

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'assign_group',                      -- Name of the UDF.
    ['data STRING', '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)
    $$
);

-- Upload from stage

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

prepare_python_for_cleanroom¶

架构:

PROVIDER

Description: Loads custom Python code into the clean room as part of a bulk code upload flow. Call this procedure multiple times to upload multiple packages, then call load_prepared_python_into_cleanroom to trigger the upload to the specified clean room, flush the pool of prepared code, and generate a new clean room patch.

Uploaded code can be called by your Jinja template. To upload only a single Python bundle, you can call load_python_into_cleanroom instead.

Learn how to upload and use Python code in a clean room.

You can either pass code directly into this procedure using the code parameter, or pass in the name of a file in a stage that contains the code using the imports parameter.

实参：

• cleanroom_name (String) - Name of the clean room where the script should be loaded.

• function_name - (String) Name that a template uses to call the function specified by handler. The template must qualify the function name with the cleanroom namespace. For example: cleanroom.my_func(val1, val2).

• arguments - (Array of space-delimited string pairs) An array of arguments required by function function_name. Each element is a space-delimited 'name  data_type' pair that specifies the argument name and its Snowflake SQL data type. For example: ['size INT', 'start_date DATE'].

• packages - (Array of string) List of any Python package names used by the code. Clean rooms natively supports all the packages in this list (https://repo.anaconda.com/pkgs/snowflake/) or the Snowpark API. If you need a package not listed there, you must use Snowpark Container Services in a clean room.

• imports - (Array of string) List of Python source files, when importing your source from a stage. Each file address is relative to the stage to where you uploaded the code, for example: ['/my_func.py']. Find the clean room stage by calling provider.get_stage_for_python_files. If you are providing code inline by using the code parameter, provide an empty array.

• rettype - (String) SQL data type of the value returned by the function handler. (See some equivalent Python and SQL types. Snowflake SQL type synonyms are accepted, such as STRING for VARCHAR.) For a UDF, the return type is a single SQL type. For a UDTF, the return type is a TABLE function with <column name> <SQL column type> pairs. For example:

  TABLE (item_name STRING, total FLOAT)

• handler - (String) The function called in your code when a template calls function_name. For a UDF this should be the function name itself; for a UDTF, this should be the name of the class that implements the UDTF.

• code - (String) Your Python code as a string. This should be a Python UDF or UDTF. If you are uploading the code from a stage, this should be an empty string.

Returns: (String) Summary of the upload request, including the patch number before the code is added to the clean room.

示例：

This example loads two simple Python procedures into a clean room and triggers only a single patch generation.

CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_next_status',  -- Name of the UDF. Can be different from the handler.
    ['status VARCHAR'], -- Arguments of the UDF, specified as (variable name, SQL type).
    ['numpy'],          -- Packages needed by UDF.
    [],                 -- When providing the code inline, this is an empty array.
    'VARCHAR',          -- Return type of UDF.
    'get_next_status',  -- Handler.
    $$
import numpy as np
def get_next_status(status):
  """Return the next higher status, or a random status
  if no matching status found or at the top of the list."""

  statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM', 'DIAMOND']
  try:
    return statuses[statuses.index(status.upper()) + 1]
  except:
    return 'NO MATCH'
    $$
);

 CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'hello_world',  -- Name of the UDF.
    [],
    [],
    [],
    'VARCHAR',
    'hello_world',
    $$
import numpy as np
def hello_world():
  return 'Hello world!'
    $$
);

CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

load_prepared_python_into_cleanroom¶

架构:

PROVIDER

Description: Takes all code staged using previous calls to prepare_python_for_cleanroom, runs a security scan on the code and, if the scan passes, uploads the code to the clean room and generates a new clean room patch. To serve this version of the clean room to users, you must then update the clean room's release directive to the patch number returned by this procedure by calling set_default_release_directive. Whether or not the call succeeds, it flushes the pool of Python code stored in previous calls to prepare_python_for_cleanroom. This step does not report syntax errors, which are only reported when you try to run your code.

实参：

• cleanroom_name (String) - Name of the clean room where you want to upload Python code.

Returns: (String) If successful, returns the new patch number created. Update the clean room's release directive to the patch number returned by this procedure by calling set_default_release_directive.

示例：

CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

get_stage_for_python_files¶

架构:

PROVIDER

Description: Returns the stage path where Python files should be uploaded, if you plan to use code files uploaded to a stage rather than inline code definitions to define custom Python code in a clean room. The stage does not exist, and can't be examined, until after files are uploaded by calling provider.load_python_into_cleanroom.

Learn how to upload and use Python code in a clean room.

实参：

• cleanroom_name (String) - Name of the clean room where you want to upload files.

Returns: (String) The path where you should upload code files. Use this for the imports argument in provider.load_python_into_cleanroom.

示例：

CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

view_cleanroom_scan_status¶

架构:

PROVIDER

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

A scan is run after any action that generates a new patch version; most commonly this is either after you first publish the clean room, or after you upload Python into the clean room. Snowflake Data Clean Rooms uses the Snowflake Native App security scan framework.

实参：

• cleanroom_name (String) - Name of the clean room to check the status of.

返回： （字符串） 扫描状态。可能是以下值：

• NOT_REVIEWED - The scan is in progress.

• APPROVED - The scan passed.

• REJECTED - The scan failed; a new clean room version won't be published. Try to find the problems in your code and retry the last action.

• MANUAL_REVIEW - The scan requires manual review by Snowflake. This might take a few days, so check again periodically.

示例：

CALL samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

mount_request_logs_for_all_consumers¶

架构:

PROVIDER

Description: Gives providers access to requests from the consumer. You must mount request logs to support various functionality, including consumer custom template requests, consumer approval of provider-run requests, and Cross-Cloud Auto-Fulfillment.

This mounts request logs only for consumers that have already installed the specified clean room; if a consumer installs a clean room after the provider calls this procedure, the provider must call this procedure again.

实参：

• cleanroom_name (String) - Name of the clean room to mount request logs for.

Returns: (Table) A table of consumers, with the request log mount status for each. If a consumer was granted access to a clean room but hasn't yet installed the clean room, the status is described as pending, and you should call mount_request_logs_for_all_consumers again after they have installed the clean room.

示例：

CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);

view_request_mount_status_for_all_consumers¶

架构:

PROVIDER

Description: Shows the mount status of request logs for all consumers in the specified clean room. Only consumers that were included in a call to provider.mount_request_logs_for_all_consumers are shown. Request logs enable messages to be passed from the consumer to the provider.

实参：

• cleanroom_name (String) - Name of the clean room.

Returns: (Table) - A table of consumers and the request log mount status of each consumer.

示例：

CALL samooha_by_snowflake_local_db.provider.view_request_mount_status_for_all_consumers($cleanroom_name);

view_request_logs¶

架构:

PROVIDER

Description: Shows the request logs sent by consumers in this clean room. Only requests from consumers who were included in a previous successful call to mount_request_logs_for_all_consumers are shown.

实参：

• cleanroom_name (String) - Name of the clean room to review request logs for.

Returns: (Table) The requests sent by the consumer to the provider in the specified clean room.

示例：

CALL samooha_by_snowflake_local_db.provider.view_request_logs($cleanroom_name);

set_privacy_settings¶

架构:

PROVIDER

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

实参：

• cleanroom_name (String) - Name of the clean room.

• consumer_account_locator - (String) Account locator of one or more consumers, in a comma-delimited list.

• privacy_settings - (Object) A JSON object that specifies differential privacy settings for one or more templates. Settings are applied to all templates run by the specified consumer. See the available fields for this object.

返回： 成功消息。

示例：

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

is_dp_enabled_on_account¶

架构:

PROVIDER

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

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.provider.is_dp_enabled_on_account();

suspend_account_dp_task¶

架构:

PROVIDER

Description: Disables the task that monitors and enforces differential privacy budgets. This is used to control the costs associated with differential privacy in your account. If the differential privacy task is disabled, noise will still be added to queries by users, templates, or clean rooms where differential privacy is specified, but budget limits will not be enforced and you will not incur costs from differential privacy. Learn more about managing differential privacy.

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.provider.suspend_account_dp_task();

resume_account_dp_task¶

架构:

PROVIDER

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

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.provider.resume_account_dp_task();

load_service_into_cleanroom¶

架构:

PROVIDER

Description: Creates or updates a container service in a clean room. Calling this procedure updates the clean room patch number, so you must call provider.set_default_release_directive after calling this procedure. You must call this procedure every time you create or update the service. The client must then call consumer.start_or_update_service to see any updates.

Learn about using Snowpark Container Services in a clean room.

实参：

• cleanroom_name (String) - Name of the clean room.

• service_spec - (String) A YAML specification for the service, rooted at the spec element.

• service_config - (String) A YAML format configuration for the service. The following properties are supported:

  • default_service_options - An optional array of service-level default values. These values can be overridden by the consumer when they create their service. The following child properties are supported:

    • min_instances (Integer, optional)

    • max_instances (Integer, optional)

    • allow_monitoring (Boolean, optional) - If TRUE, allows the consumer to see service logs. Default is FALSE.

  • functions - An array of functions exposed by the service. Each function definition maps to the SPCS service function definition. See that documentation to learn the details of each element. The following child properties are supported:

    • name

    • args

    • returns

    • endpoint

    • path

    • max_batch_rows (optional)

    • context_headers (optional)

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

示例：

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

manage_datastats_task_on_account¶

架构:

PROVIDER

Description: Enables or disables the background task that computes clean room statistics. The task is running by default, but you can disable it to reduce your costs. To manage the task, all collaborators must call the appropriate provider or consumer version of this procedure with the same value.

实参：

• enable - (Boolean) TRUE to enable the task, FALSE to disable the task.

返回： 成功消息。

示例：

-- Disable the task in this account.
CALL samooha_by_snowflake_local_db.provider.manage_datastats_task_on_account(FALSE);

enable_local_db_auto_upgrades¶

架构:

LIBRARY

Description: Enables the task that automatically upgrades the Snowflake Data Clean Rooms environment when new procedures or functionality is released (The task is samooha_by_snowflake_local_db.admin.expected_version_task. ) Call this procedure to automate upgrades, rather than calling library.apply_patch with each new release.

Although you might reduce cost by disabling this task, we recommend that you leave it running to ensure that you have the latest version of the clean rooms environment on your system.

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

disable_local_db_auto_upgrades¶

架构:

LIBRARY

Description: Disables the task that automatically upgrades the Snowflake Data Clean Rooms environment when new versions are released. If you disable auto upgrades, you must call library.apply_patch with each new release.

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();

apply_patch¶

架构:

LIBRARY

Description: Updates your clean rooms environment, enabling new features and fixes in your environment. Call this when a new version of the clean rooms environment has been released. (This typically occurs weekly; see clean rooms entries in Recent feature updates.) This procedure updates samooha_by_snowflake_local_db.

You can automate patch updates by calling library.enable_local_db_auto_upgrades. We recommend enabling auto-updates.

实参： 无

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

示例：

CALL samooha_by_snowflake_local_db.library.apply_patch();

patch_cleanroom¶

架构:

PROVIDER

描述： 将指定的 Clean Room 更新到最新版本，从而为该 Clean Room 启用新功能和修复。通常，只有在 Snowflake 支持部门要求您调用此任务时，您才会进行调用。

The provider should call library.patch_cleanroom before the consumer calls library.patch_cleanroom. Otherwise, there is no patch to apply.

实参：

• cleanroom_name (String) : Name of the clean room to patch.

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

示例：

CALL samooha_by_snowflake_local_db.provider.patch_cleanroom($cleanroom_name);

dcr_health.dcr_tasks_health_check¶

描述： 显示有关正在运行或最近停止的 Clean Room 任务的信息。

实参： 无

返回： （表） 有关 Clean Room 任务的信息，包括计划、仓库名称和仓库规模。

示例：

CALL samooha_by_snowflake_local_db.dcr_health.dcr_tasks_health_check();

mount_laf_cleanroom_requests_share (Deprecated)¶

架构:

PROVIDER

This function is now deprecated; call provider.mount_request_logs_for_all_consumers instead.

Description: Makes cross-cloud requests accessible for the given clean room and consumer account. provider.request_laf_cleanroom_requests must return a status of FULFILLED before you can call this procedure.

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

实参：

• cleanroom_name (String) - Clean room that is shared.

• consumer_locator - (String) Snowflake account locator of consumer who will be making cross-cloud requests in this clean room.

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

示例：

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

request_laf_cleanroom_requests (Deprecated)¶

架构:

PROVIDER

This function is now deprecated; call provider.mount_request_logs_for_all_consumers instead.

Description: Sets up cross-cloud request sharing on the provider side for a given consumer. An account administrator must first enable cross-cloud auto-fulfillment, and the consumer must have called consumer.setup_cleanroom_request_share_for_laf.

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

You can call this procedure repeatedly to check the status of the request. When status reaches FULFILLED, you can call provider.mount_laf_cleanroom_requests_share. It can take 10 minutes for the status to reach FULFILLED.

实参：

• cleanroom_name (String) - Name of the clean room to enable cross-cloud request sharing.

• consumer_locator - (String) Account locator of consumer for whom to enable cross-cloud request sharing.

Returns: (String) Status message of the request: CREATED, PENDING, FULFILLED, FAILURE. 'FAILURE, listing not found' means that the consumer has not installed the clean room (or has uninstalled it).

示例：

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

enable_laf_for_cleanroom (Deprecated)¶

架构:

PROVIDER

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

Description: Enables Cross-Cloud Auto-Fulfillment, which allows you to share the clean room with collaborators whose Snowflake account is in a different region from the provider's account. Cross-Cloud Auto-Fulfillment is also known as Listing Auto-Fulfillment (LAF).

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

There are additional costs associated with collaborating with consumers in other regions. For more information about these costs, see Cross-Cloud Auto-Fulfillment costs.

实参：

• cleanroom_name (String) - The name of the clean room that should be shared across regions. Cross-Cloud Auto-Fulfillment must be enabled for the account by an administrator before individual clean rooms can be shared.

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

示例：

CALL samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);

view_ui_registration_request_log -- DEPRECATED¶

架构:

PROVIDER

Description: Views the list of requests raised from the account to register clean rooms into the clean rooms UI. Each request has an associated ID that can be used in conjunction with the view_ui_registration_log procedure to view the status of the requests. The requests are shared to the backend where they are processed and the clean room is added into the clean room.

实参：

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

示例：

CALL samooha_by_snowflake_local_db.provider.view_ui_registration_request_log();

register_table_or_view -- Deprecated¶

架构:

LIBRARY

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

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

要注册 Iceberg 表：

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

register_table -- Deprecated¶

架构:

LIBRARY

Description: Similar to register_db, but operates at a table level. Grant SELECT privilege on this table to the SAMOOHA_APP_ROLE role, enabling the user to link the table into the clean room.

If you want to register tables in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.register_managed_access_table instead.

实参： table_name（数组）

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

示例：

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

register_managed_access_table -- Deprecated¶

架构:

LIBRARY

Description: Similar to register_table, but registers tables in a schema that was created using the WITH MANAGED ACCESS parameter. An array or string representing the fully qualified table name can be passed in, and grant selects to the SAMOOHA_APP_ROLE role are made, enabling the user to link the table into the clean room.

实参： table_name（数组）

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

示例：

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

register_view -- Deprecated¶

架构:

LIBRARY

Description: Similar to register_db, but operates at a view level. An array or string representing the fully qualified view name can be passed in, and grant selects to the SAMOOHA_APP_ROLE role are made, enabling the user to link the view into the clean room.

If you want to register views in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.register_managed_access_view instead.

实参： view_name（数组）

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

示例：

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

register_managed_access_view -- Deprecated¶

架构:

LIBRARY

Description: Similar to register_view, but registers views in a schema that was created using the WITH MANAGED ACCESS parameter. An array or string representing the fully qualified view name can be passed in, and grant selects to the SAMOOHA_APP_ROLE role are made, enabling the user to link the view into the clean room.

实参： view_name（数组）

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

示例：

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

unregister_table_or_view -- Deprecated¶

架构:

LIBRARY

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

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

unregister_table -- Deprecated¶

架构:

LIBRARY

Description: Similar to unregister_db, but operates at a table level. An array or string representing the fully qualified table name can be passed in to unregister the tables. Users cannot link unregistered tables into a clean room.

If you want to unregister tables in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.unregister_managed_access_table instead.

实参： table_name（数组）

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

示例：

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

unregister_managed_access_table -- Deprecated¶

架构:

LIBRARY

Description: Similar to unregister_table, but unregisters tables in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter).

实参： table_name（数组）

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

示例：

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

unregister_view -- Deprecated¶

架构:

LIBRARY

Description: Similar to unregister_db, but operates at a view level. An array or string representing the fully qualified view name can be passed in to unregister the views. Users cannot link unregistered views into a clean room.

If you want to unregister views in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter), use library.unregister_managed_access_view instead.

实参： view_name（数组）

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

示例：

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

unregister_managed_access_view -- Deprecated¶

架构:

LIBRARY

Description: Similar to unregister_view, but unregisters views in a managed access schema (that is, a schema created using the WITH MANAGED ACCESS parameter).

实参： view_name（数组）

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

示例：

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

create_cleanroom_listing -- Deprecated¶

架构:

PROVIDER

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

You identify the collaborator using the orgname.account_name format of their account URL. The consumer can find this string by following the instructions in 查找账户的组织和账户名称.

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

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

示例：

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

register_cleanroom_in_ui -- DEPRECATED¶

架构:

PROVIDER

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

您可以多次调用该 API，将多个自定义模板添加到 Clean Room UI 中。

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