Snowflake Data Clean Room:提供商 API 参考指南¶
This page describes procedures used by clean rooms API consumers to manage their clean rooms. For coding setup instructions, see 编码设置.
创建、配置和删除 Clean Room¶
These procedures enable a provider to create, configure, and delete a clean room.
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;
返回: (字符串) 成功消息。
示例:
-- 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 之前调用。
无论何时上传或更改 Python 代码,Clean Room 应用程序都会创建一个新版本的 Clean Room。如果您希望为用户提供最新版本的服务,请使用新的版本号调用此过程。要查看可用版本并了解当前默认版本,请运行:
如果您忘了最新的补丁号,可以运行以下代码来查看有哪些版本可用(您可能想使用最新的版本作为默认版本):
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_<cleanroom_name>
Where <cleanroom_name>
follows this format.
创建的所有 Clean Room 都有以下版本号和补丁号:
版本:V1_0
补丁:0
备注
If the clean room distribution is set to EXTERNAL, this procedure can be called only after the clean room security scan moves to an
APPROVED state. To see the security status, call view_cleanroom_scan_status
.
实参:
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.
备注
You must set the release directive at least once before calling this procedure. For more information, see provider.set_default_release_directive.
实参:
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
);
注册和取消注册数据¶
Use the following command to register and unregister databases, schemas, and objects. Tables and views must be registered before they can be linked into the clean room. If you register a database or schema, all of the objects in that database or schema are registered. Learn more about registering data.
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'
]
);
链接数据和表¶
使用以下命令在 Clean Room 中添加或删除表和视图。
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, thereby avoiding any need to make a copy of your table. The table is still linked to its source, so updates in the source will be reflected in the secure version within the 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'
]
);
备注
如果将某个视图链接到 Clean Room,并且该视图基于其他数据库中的表,则必须同时注册该视图和该视图的源
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.
备注
Restrictions that you create by calling this procedure might not behave as expected in the clean rooms UI. You should not call this procedure on a clean room that can be used in the clean rooms UI.
实参:
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']
}
);
管理策略¶
Join policies in data clean rooms are not the same as Snowflake-wide join policies. Join policies for clean rooms are set only by using this procedure; join policies set on tables outside of clean rooms are ignored by clean rooms.
Learn more about table policies in clean rooms.
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 内运行模板时,使用者可以联接哪些列。注意,联接策略是 仅替换,因此如果再次调用过程,新的联接策略会完全替换之前设置的联接策略。
重要
Join policies are enforced only when the template applies the join_policy
or join_and_column_policy
JinjaSQL filters to join rows.
备注
Data Clean Room 中的联接策略与 Snowflake 全域联接策略不同。仅使用此过程设置 Clean Room 的联接策略;Clean Room 会忽略在 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 formatdatabase_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'
]
);
管理提供商模板¶
使用以下命令添加此 Clean Room 支持的模板/分析。
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, calladd_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 namedactivation_data_analysis_results
, you would returndata_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 callingprovider.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 theis_obfuscated
state.is_obfuscated
cannot be used together withsensitivity
.
返回: (字符串) 成功消息。
示例:
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 thetemplate_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 themy_table
template variable. If any element setsreferences=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 thesource_table
template variable. If any element setsreferences=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 anycleanroom
prefix. Learn about activation templates.enabled_activations
- (String) Which kind of activations are enabled. Possible values:consumer
,provider
. No default; must be provided ifactivation_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>] }
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 selectorinteger
: Use arrows to change the numbermultiselect
: Select multiple items from a dropdown listdropdown
: Select one item from a dropdown listdate
: Date selector
default
: Default value of this elementchoices
: (Array of string) List of choices for dropdown and multiselect elementsinfoMessage
: 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 eithermultiselect
ordropdown
. 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 theprovider_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 theprovider_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 byconsumer_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; useCONSUMER_JOIN_POLICY
orCONSUMER_COLUMN_POLICY
for provider-run templates instead.CONSUMER_JOIN_POLICY
: List all columns in the consumer's join policy from the table selected in theconsumer_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 theconsumer_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 whenreferences
is set toPROVIDER_COLUMN_POLICY
orPROVIDER_JOIN_POLICY
. To reference the default provider table chooser, specifysource_table
here and setrender_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 whenreferences
is set toCONSUMER_COLUMNS
,CONSUMER_JOIN_POLICY
, orCONSUMER_COLUMN_POLICY
. To reference the default consumer table chooser, specifymy_table
here and setrender_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 formatBAR
: Bar chart, which is good for comparing different categoriesLINE
: Line chart, which is good for showing trends over time or continuous dataPIE
: 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:
|
|
|
|
|
|
---|---|---|---|---|---|
|
|
未获准 |
未获准 |
FALSE |
TRUE 或 FALSE |
|
|
未获准 |
TRUE |
TRUE 或 FALSE |
|
|
|
未获准 |
TRUE 或 FALSE |
TRUE 或 FALSE |
|
|
|
未获准 |
TRUE |
TRUE 或 FALSE |
|
|
|
未获准 |
TRUE 或 FALSE |
TRUE 或 FALSE |
|
|
未获准 |
未获准 |
TRUE 或 FALSE |
FALSE |
|
|
未获准 |
|
TRUE 或 FALSE |
TRUE |
|
|
未获准 |
|
TRUE 或 FALSE |
TRUE |
|
|
未获准 |
|
TRUE 或 FALSE |
TRUE |
|
|
未获准 |
未获准 |
TRUE 或 FALSE |
TRUE 或 FALSE |
返回: (字符串) 成功消息。
示例:
-- 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/模板对指定的任何访问列表。
备注
Restrictions that you create by calling this procedure might not behave as expected in the clean rooms UI. You should not call this procedure on a clean room that can be used in the clean rooms UI.
实参:
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']
}
);
使用者自定义模板¶
The following APIs allow you to approve or reject a request from a consumer to add a template to the clean room. A consumer-defined template is added to a clean room only if the provider approves the consumer's request to add it. For more information, see 使用者编写的自定义模板.
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
) .
实参:
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($template_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. Callprovider.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, callprovider.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. Callprovider.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, callprovider.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')
]
);
模板链¶
Use the following commands to create and manage template chains.
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 callingprovider.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) - Whencache_results
= TRUE, specifies the name of the Snowflake table where template results are stored.jinja_output_table_param
(String) - Whencache_results
= TRUE, specifies the name of the Jinja parameter that other templates must include to accept the results that are stored inoutput_table_name
.cache_expiration_hours
(integer) - Whencache_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');
多提供商分析¶
These procedures enable multi-provider analysis.
备注
The current multi-provider flow will be deprecated soon. Clean rooms is working on a new multi-provider flow to replace the current multi-provider procedures.
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 byconsumer_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 inapproved_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 isprovider_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 toprovider.enable_multiprovider_computation
.request_id
- (String) Request ID to approve, fromprovider.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);
激活¶
Activation means exporting results to a provider, a consumer, or a third party. Read more about activation.
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 istemplate_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');
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();
以提供商身份运行分析¶
Learn how to run a provider analysis.
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.
重要
This procedure must be called after provider.add_consumers
, and before a consumer installs a clean room. If this is changed
after a consumer has already installed their clean room, then the consumer must reinstall the clean room to reflect the new configuration.
实参:
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 中运行分析(默认已禁用)。
重要
You must call this procedure after calling provider.add_consumers
, and before a consumer installs a clean room. If the run
analysis setting is changed after a consumer has installed a clean room, then the consumer must reinstall the clean room to implement the
new setting.
实参:
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 toprovider.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)
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 callingconsumer.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 thesource_table
array variable.consumer_tables
- (array) List of consumer tables to expose to the template. This list will populate themy_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 byprovider.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.
实参:
cleanroom_name (String) - Name of the clean room where the request was made.
request_id
- (String) ID of the request, returned byprovider.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:选择使用 时默认使用的角色和仓库。表示以下情况之一:
请求仍在传播,可能需要几分钟。请过几分钟再试。
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, callprovider.mount_request_logs_for_all_consumers
.
COMPLETED: The analysis is complete. You can call
provider.get_analysis_result
.
示例:
-- 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 bysubmit_analysis_request
.consumer_account_locator
- (String) Account locator of the consumer passed in tosubmit_analysis_request
.
返回: (表) 查询结果。
示例:
CALL samooha_by_snowflake_local_db.provider.get_analysis_result(
$cleanroom_name,
$request_id,
$locator
);
管理 Clean Room 共享¶
使用以下命令,管理与使用者共享 Clean Room。
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 inconsumer_account_names
.consumer_account_names
- (String) A comma-delimited list of consumer data sharing account IDs for the consumer in the formatorg_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 inconsumer_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 theprivacy_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 inconsumer_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 bothenable_differential_privacy_tasks
andprivacy_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 a clean room to be shared with a consumer on another cloud region. Learn more.
enable_laf_on_account¶
- 架构:
LIBRARY
描述: 在当前账户上启用 Cross-Cloud Auto-Fulfillment。运行此过程需要 ACCOUNTADMIN 角色。
重要
You must first enable Cross-Cloud Auto-Fulfillment for the account by calling SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT.
Learn more about auto-fulfillment and managing auto-fulfillment privileges.
实参: 无
返回: (字符串) 成功消息。
示例:
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_laf_on_account();
disable_laf_on_account¶
- 架构:
LIBRARY
描述: 在当前账户上禁用 Cross-Cloud Auto-Fulfillment。运行此过程需要 ACCOUNTADMIN 角色。
重要
You must first call SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT before you can disable Cross-Cloud Auto-Fulfillment on an account.
Learn more about auto-fulfillment and managing auto-fulfillment privileges.
实参: 无
返回: (字符串) 成功消息。
示例:
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);
在 Clean Room 中使用 Python¶
load_python_into_cleanroom¶
- 架构:
PROVIDER
描述: 将自定义 Python 代码加载到 Clean Room。使用此过程加载到 Clean Room 的代码都对使用者不可见。Jinja 模板可以调用上传的代码。尽管您的代码可能包含多个函数定义,但一个模板只能调用一个函数。
Learn how to upload and use Python code in a clean room.
此过程会递增 Clean Room 的补丁号并触发安全扫描。您必须等待扫描状态变为 APPROVED,然后才能与协作者共享最新版本。
此过程重载,并且具有两个签名,该签名与第五个实参的数据类型不同,它们决定了是内联上传代码还是从暂存区上的文件加载代码:
Signature
load_python_into_cleanroom
has the following signature for inline code upload. Pass your code string into the code
argument.
(cleanroom_name String, function_name String, arguments Array, packages Array, rettype String, handler String, code String)
实参:
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 byhandler
. The template must qualify the function name with thecleanroom
namespace. For example:cleanroom.my_func(val1, val2)
.arguments
- (Array of string pairs) An array of arguments required by functionfunction_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.ret_type
- (String) SQL data type of the value returned by the functionhandler
. (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 callsfunction_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.
Signature
Upload your code to a Snowflake stage, and then provide the stage location to the clean room API. You must use the stage enabled for your
specific clean room by calling provider.get_stage_for_python_files
.
load_python_into_cleanroom
has the following signature to upload code into the clean room from a stage.
(cleanroom_name String, function_name String, arguments Array, packages Array, imports Array, rettype String, handler String)
实参:
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 byhandler
. The template must qualify the function name with thecleanroom
namespace. For example:cleanroom.my_func(val1, val2)
.arguments
- (Array of string pairs) An array of arguments required by functionfunction_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.imports
- (Array of string) List of files to import from the 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 callingprovider.get_stage_for_python_files
.ret_type
- (String) SQL data type of the value returned by the functionhandler
. (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 callsfunction_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.
返回: (字符串) 成功消息。
示例:
-- 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.
);
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 检查。
实参:
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);
请求日志¶
Use the following commands to manage consumer request logs. Request logs enable the consumer to send messages to the provider, and must be mounted to enable functionality such as consumer custom template requests, consumer approval of provider-run requests, and Cross-Cloud Auto-Fulfillment.
mount_request_logs_for_all_consumers¶
- 架构:
PROVIDER
描述: 允许提供商访问使用者的请求。您必须挂载请求日志,才能支持各种功能,包括使用者自定义模板请求、使用者对提供商运行请求的批准以及 Cross-Cloud Auto-Fulfillment。
这仅为已安装指定 Clean Room 的使用者挂载请求日志;如果使用者在提供商调用此过程后安装了 Clean Room,则提供商必须再次调用此过程。
实参:
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.
返回: (表) – 使用者表和每个使用者的请求日志挂载状态。
示例:
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);
差分隐私¶
These commands control differential privacy at the user level or provider account level. Learn more about differential privacy.
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();
Snowpark Container Services 命令¶
These procedures enable you to use Snowpark Container Services inside a clean room.
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 thespec
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
$$);
环境管理¶
使用以下命令一般有助于充分利用 Clean Room 功能和支持流程。
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 最近的功能更新.) 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();
已弃用的过程¶
The following procedures are deprecated and listed here only for completeness. If a replacement procedure is indicated, use the newer procedure.
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 是关闭的,即使该环境已启用。
重要
A Snowflake administrator with the ACCOUNTADMIN role must enable Cross-Cloud Auto-Fulfillment in your Snowflake account before you can run this procedure. Learn about 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
注意
此命令现已弃用。 您不再需要手动注册 Clean Room 模板以在 Clean Room UI 中使用。
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
注意
This command is now deprecated. Use register_objects instead.
描述: 注册所有类型的表和视图。
实参: 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
注意
This command is now deprecated. Use register_objects instead.
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
注意
This command is now deprecated. Use register_objects instead.
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
注意
This command is now deprecated. Use register_objects instead.
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
注意
This command is now deprecated. Use register_objects instead.
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
注意
This command is now deprecated. Use unregister_objects instead.
描述: 取消注册所有类型的表和视图。
实参: 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
注意
This command is now deprecated. Use unregister_objects instead.
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
注意
This command is now deprecated. Use unregister_objects instead.
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
注意
This command is now deprecated. Use unregister_objects instead.
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
注意
This command is now deprecated. Use unregister_objects instead.
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
注意
This command is now deprecated. Use create_or_update_cleanroom_listing instead.
描述: 配置 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 查找账户的组织和账户名称.
备注
To use this procedure, you need to have set the release directive. For more information, see provider.set_default_release_directive.
实参: 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,供使用者在 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>)