Snowflake Data Clean Rooms Collaboration API¶

简介¶

这是 Snowflake Data Clean Rooms Collaboration API 的参考页面。此 API 使用的是 COLLABORATION 和 REGISTRY 命名空间，而不是提供商和使用者 APIs 所使用的 PROVIDER 或 CONSUMER 命名空间。

授予对 DCR Collaboration API 的使用权限¶

协作者可以使用高级 SAMOOHA_APP_ROLE 角色调用所有 DCR Collaboration API 过程。

但是，我们建议管理员根据特定协作或特定角色的需求，授予其更精细的访问权限。您可以在访问管理过程中找到更精细的权限说明。

要向用户授予精细的 API 权限，请执行以下步骤：

创建角色。
将正在使用的仓库的使用权限授予该角色。
如果需要将特定协作的相应权限授予某个角色，请调用 GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE。
如果需要将账户中所有协作的相应高级权限授予该角色，请调用 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。
向用户授予该角色，用户现在可以调用协作过程来参与协作。

示例¶

以下是创建两个 Collaboration API 角色的示例：一个角色可以创建和联接协作，另一个角色可以查看协作中的资源并在协作中运行分析（但不能联接或修改协作）。

-- Create a role that can create and join collaborations.
USE ROLE ACCOUNTADMIN;
CREATE ROLE COLLABORATION_CREATOR_ROLE;
GRANT USAGE ON WAREHOUSE APP_WH TO COLLABORATION_CREATOR_ROLE;
GRANT APPLY ROW ACCESS POLICY ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE APPLICATION ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE DATABASE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE LISTING ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT IMPORT SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT MANAGE SHARE TARGET ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'COLLABORATION_CREATOR_ROLE');
GRANT ROLE COLLABORATION_CREATOR_ROLE TO USER george_washington;

-- Create a role that can run analyses on a specific collaboration.
USE ROLE COLLABORATION_CREATOR_ROLE;
CREATE ROLE ANALYST_ROLE;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_id,
  'ANALYST_ROLE'
);

-- Also grant READ, which gives permission to read the resources available to use in a collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'READ',
  'COLLABORATION',
  $collaboration_id,
  'ANALYST_ROLE'
);

GRANT ROLE ANALYST_ROLE to USER alexander_hamilton;

Copy

元数据备忘单¶

以下是查找有关协作的一些常见信息的方法：

要了解以下信息...	调用以下数据
我可以联接哪些协作？	`VIEW_COLLABORATIONS`。查找 COLLABORATION_NAME 列为 NULL 的协作。
我已联接哪些协作？	`VIEW_COLLABORATIONS`。查找 COLLABORATION_NAME 列不是 NULL 的协作，这可能意味着您已创建或联接了协作。
我拥有哪些协作？	`VIEW_COLLABORATIONS`。查看 OWNER_ACCOUNT 列。
协作中所有协作者的状态是什么？	`GET_STATUS`
我在协作中的联接或创建状态是什么？	`GET_STATUS` 或 `VIEW_COLLABORATIONS`
谁拥有给定的协作？	`GET_STATUS`。在 ROLES 列查找 OWNER。
我在特定协作中的角色是什么？	`GET_STATUS`。查看 ROLES 列。
在给定协作中分配了哪些角色？	`GET_STATUS`。查看 ROLES 列。
给定协作的规范是什么？	`VIEW_COLLABORATIONS`。查看 COLLABORATION_SPEC 列。
规范是最新的吗？	无法判断给定规范是否正在进行变更，但您可以调用 `VIEW_COLLABORATIONS` 以查看何时应用了最新更新。
我有哪些待处理的更新请求？	`VIEW_UPDATE_REQUESTS`。查找 STATUS = PENDING 的行。

对于其中的许多调用，您可以使用管道运算符将行限制为具有特定值的行。例如，要查看特定协作的规范，请运行以下 SQL 命令：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS()
  ->> SELECT "COLLABORATION_SPEC" FROM $1
    WHERE "SOURCE_NAME" = $collaboration_id;

Copy

模板过程¶

REGISTER_TEMPLATE¶

架构:: REGISTRY

注册模板以使其能够在协作中使用。注册的每个模板都必须在本地注册表中具有唯一的（name、version）对。

语法¶

REGISTER_TEMPLATE( <template_spec> )

Copy

实参¶

template_spec: 模板定义采用 YAML 格式，以字符串形式呈现。

返回¶

在协作规范中使用的模板 ID。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: my_test_template
  version: 2026_01_12_V1
  type: sql_analysis
  description: A test template
  template:
    SELECT * FROM IDENTIFIER({{ source_table[0] }}) LIMIT 10;
$$);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER TEMPLATE', 'role name')

VIEW_REGISTERED_TEMPLATES¶

架构:: REGISTRY

列出您已注册的所有模板。要注册模板，请调用 REGISTRY.REGISTER_TEMPLATE。

语法¶

VIEW_REGISTERED_TEMPLATES()

Copy

实参¶

无

返回¶

一个表，其中列出了您在此账户中注册的所有模板的详细信息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_TEMPLATES();

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED TEMPLATES', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ADD_TEMPLATE_REQUEST¶

架构:: COLLABORATION

发送向现有协作添加模板的请求。如果发起方受到该请求的影响，则发起方会自动批准该请求；所有其他受影响的协作者必须批准该请求，变更才能生效。所有协作者（甚至协作所有者）都需要调用此过程，以将模板添加到现有协作中。

要查看请求的状态，请调用 VIEW_UPDATE_REQUESTS。

请参阅添加模板流程。

语法¶

ADD_TEMPLATE_REQUEST( <collaboration_name>, <template_id>, <share_with> )

Copy

实参¶

collaboration_name: 要添加模板的协作的名称。
template_id: 要添加到协作的模板的 ID。注册模板以获取此值。
share_with: 可以使用此模板的分析执行器的别名数组。此处列出的协作者必须是此协作中的分析执行者。您可以通过调用 REVIEW 查看协作别名。

返回¶

字符串成功消息。

示例¶

-- Ask to add the template only for Collaborator3 in this collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ADD_TEMPLATE_REQUEST(
  $collaboration_id,
  $template_alias,
  ['Collaborator3']
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REMOVE_TEMPLATE¶

架构:: COLLABORATION

从指定协作者的给定协作中移除模板的异步请求。只有注册模板的协作者才能移除模板。移除您已注册的模板不需要任何其他人的批准。为协作者移除模板后，该协作者将无法看到或查看该模板。

语法¶

REMOVE_TEMPLATE( <collaboration_name>, <template_id>, <remove_for> )

Copy

实参¶

collaboration_name: 要从中移除模板的协作的名称。
template_id: 要从协作中移除的模板的 ID。
remove_for: 此协作中一个或多个分析执行器的别名数组，这些分析执行器应该无法再看到或使用此模板。

返回¶

字符串成功消息。要查看协作者的模板是否已移除，请查看协作规范。

示例¶

-- Prevent collaborator_1234 from using the specified template
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REMOVE_TEMPLATE(
  $collaboration_id,
  $template_id,
  ['collaborator_1234']
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_TEMPLATES¶

架构:: COLLABORATION

显示您可以运行或已提交到指定协作的所有模板。

语法¶

VIEW_TEMPLATES( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。您必须先查看或联接此协作，然后才能列出其模板。

返回¶

一个表，其中列出了有关您可以在此协作中运行的模板（包括您已注册的模板）的信息。信息包括模板 ID（用于运行模板）、模板正文、参数、创建者和运行者。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW TEMPLATES', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_TEMPLATE_AUTO_APPROVAL¶

架构:: COLLABORATION

使其他协作者发送的所有模板更新请求自动获得批准。请求仍将显示在请求日志中。这仅影响启用自动审批后发送的请求。

语法¶

ENABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。

返回¶

字符串成功消息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

DISABLE_TEMPLATE_AUTO_APPROVAL¶

架构:: COLLABORATION

禁用对其他协作者提出的模板请求的自动批准。未来的所有请求都必须通过调用 APPROVE_UPDATE_REQUEST 来手动批准。

语法¶

DISABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。

返回¶

字符串成功消息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

数据产品过程¶

REGISTER_DATA_OFFERING¶

架构:: REGISTRY

注册数据产品，以便将其添加到协作定义中。您无法将已注册的数据产品取消注册。您无法覆盖现有数据产品，但可以注册具有相同名称和新版本的新数据产品。创建数据产品的新版本不会移除任何早期版本。

每个数据产品都必须在本地注册表中具有唯一的（name、version）对。

如果要与协作中的其他人共享此表，请在创建协作之前将该表添加到协作规范中。

您必须拥有您在协作中共享的任何数据的 OWNERSHIP。如果不这样做，当您尝试联接协作或注册对象时，您将收到“缺少引用使用授权”错误。了解如何处理此问题。

语法¶

REGISTER_DATA_OFFERING( <data_offering_spec> )

Copy

实参¶

data_offering_spec: 数据产品定义采用 YAML 格式，用于描述此数据产品。

返回¶

在协作的 data_offerings.id 字段中使用的数据产品 ID。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_DATA_OFFERING(
    $$
    api_version: 2.0.0
    spec_type: data_offering
    version: v1
    name: customers
    datasets:
     - alias: customers_1
       data_object_fqn: SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
       allowed_analyses: template_only
       schema_and_template_policies:
         hashed_email:
           category: join_custom
         status:
           category: passthrough
    $$
  );

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER DATA OFFERING', 'role name')

LINK_DATA_OFFERING¶

架构:: COLLABORATION

数据提供商运行此过程，通过将指定的数据产品提供给指定的分析执行器来更新现有协作。这是一个异步过程；分析执行器应调用 VIEW_DATA_OFFERINGS 来查看数据产品何时可供使用。

如果您想使用此表，但不想使其对其他协作者可见，请调用 LINK_LOCAL_DATA_OFFERING``（而不是 ``LINK_DATA_OFFERING）。

运行此过程时，您不能拥有活动的次要角色。运行以下 SQL 代码以禁用任何次要角色：

USE SECONDARY ROLES NONE;

Copy

此方法是原子方法：必须满足以下所有条件，此过程才能成功。如果任何一个协作者的链接尝试失败，则所有协作者的链接尝试都会失败。

所有指定的协作者都必须是分析执行者。
此数据产品不得已与任何指定的分析执行者共享。
此过程只能由已联接协作且具有数据提供商角色的用户运行。

您必须拥有您希望共享的任何数据的 OWNERSHIP。如果不这样做，当您尝试联接协作时，您将收到“缺少引用使用授权”错误。了解如何处理此问题。

语法¶

LINK_DATA_OFFERING( <collaboration_name>, <data_offering_id>, <share_with> )

Copy

实参¶

collaboration_name: 协作的名称。
data_offering_id: 要共享的数据集的 ID，在注册时生成。
share_with: 要与之共享此数据集的分析执行器的字符串别名数组。此处列出的所有协作者都必须是您作为数据提供商的分析执行者。

返回¶

字符串成功消息。

示例¶

此示例允许协作者 alice 在指定协作中使用指定的数据产品。

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LINK_DATA_OFFERING(
  $collaboration_id,
  $my_data_id,
  ['alice']
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

UNLINK_DATA_OFFERING¶

架构:: COLLABORATION

数据提供商运行此过程，以从现有协作中的指定分析执行器中移除对数据产品的访问权限。这是一个异步过程；分析执行器应调用 VIEW_COLLABORATIONS 来确认数据产品是否已移除。

语法¶

UNLINK_DATA_OFFERING( <collaboration_name>, <data_offering_id>, <remove_for> )

Copy

实参¶

collaboration_name: 协作的名称。
data_offering_id: 要取消链接的数据集的 ID，在注册时生成。
remove_for: 要移除访问权限的一个或多个分析执行器的字符串别名数组。此处列出的所有协作者都必须是当前有权访问此数据产品的分析执行者。

返回¶

字符串成功消息。

示例¶

-- Remove data offering access for specific analysis runners in this collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.UNLINK_DATA_OFFERING(
  $collaboration_id,
  $data_offering_id,
  ['AnalysisRunner_1', 'AnalysisRunner_2']
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

LINK_LOCAL_DATA_OFFERING¶

架构:: COLLABORATION

如果您使用的是 Snowflake Standard Edition，请使用此过程将您自己的数据链接到协作中。您必须先通过调用 REGISTER_DATA_OFFERING 来注册您的数据产品。这些产品对任何其他协作者都不可见，并且不会强制执行模板策略。此处提交的表会在模板中传播 my_table 数组。

有关更多信息，请参阅使用 Standard Edition 时，使用自己的数据运行分析。

语法¶

LINK_LOCAL_DATA_OFFERING( <collaboration_name>, <data_offering_id> )

Copy

实参¶

collaboration_name: 协作的名称。
data_offering_id: 数据集的 ID，在您注册该数据集时生成。在 VIEW_REGISTERED_DATA_OFFERINGS 和 VIEW_DATA_OFFERINGS 中也可见（仅对您可见）。

返回¶

字符串成功消息。

示例¶

此示例链接了一个已注册的数据产品，仅供当前账户使用，不会向其他协作者公开。

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LINK_LOCAL_DATA_OFFERING(
  $collaboration_id,
  $my_private_data_offering_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

UNLINK_LOCAL_DATA_OFFERING¶

架构:: COLLABORATION

使用此过程可将您自己的本地数据与协作取消关联。取消关联后，数据产品将不再可用于此协作中的分析。有关本地数据产品的更多信息，请参阅使用 Standard Edition 时，使用自己的数据运行分析。

语法¶

UNLINK_LOCAL_DATA_OFFERING( <collaboration_name>, <data_offering_id> )

Copy

实参¶

collaboration_name: 协作的名称。
data_offering_id: 要取消关联的数据集的 ID，在您注册该数据集时生成。在 VIEW_REGISTERED_DATA_OFFERINGS 和 VIEW_DATA_OFFERINGS 中也可见（仅对您可见）。

返回¶

字符串成功消息。

示例¶

-- Unlink a local data offering from a collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.UNLINK_LOCAL_DATA_OFFERING(
  $collaboration_id,
  $my_private_data_offering_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_REGISTERED_DATA_OFFERINGS¶

架构:: REGISTRY

列出您已注册的所有数据产品。要查看其他人添加的协作中的数据产品，请调用 COLLABORATION.VIEW_DATA_OFFERINGS。

语法¶

VIEW_REGISTERED_DATA_OFFERINGS()

Copy

实参¶

无

返回¶

一个表，其中列出了您使用此账户注册的所有数据产品。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS();

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED DATA OFFERINGS', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_DATA_OFFERINGS¶

架构:: COLLABORATION

列出您作为分析执行者可以访问的或您自己添加的指定协作中的所有数据产品。要仅查看您已注册的数据产品，请调用 REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS。

只有在 X 已联接协作后，您才能看到来自协作者 X 的数据产品。

语法¶

VIEW_DATA_OFFERINGS( <collaboration_name> )

Copy

实参¶

collaboration_name: 要探索的协作的名称。

返回¶

有关指定协作中所有数据产品的信息。该表包括以下各列：

FREEFORM_SQL_COLUMN_POLICIES：选择使用时默认使用的角色和仓库。此协作中所有自由格式列策略的 JSON 表示，按策略类型键入。
FREEFORM_SQL_VIEW_NAME：选择使用时默认使用的角色和仓库。当数据集支持自由格式 SQL 查询时，自由格式 SQL 查询中使用的完全限定表名。如果数据集不提供自由格式 SQL 查询，则此单元格为空。
SHARE_WITH：选择使用时默认使用的角色和仓库。谁可以在分析中使用数据。如果此值为 LOCAL，这是一个本地数据集，除托管数据的一方外，不与任何协作者共享。
TEMPLATE_VIEW_NAME：选择使用时默认使用的角色和仓库。调用 COLLABORATION.RUN 时，模板中使用的完全限定表名。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW DATA OFFERINGS', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

更新请求过程¶

这些过程用于管理需要批准的协作更新请求，例如添加模板流程。

VIEW_UPDATE_REQUESTS¶

架构:: COLLABORATION

查看您在指定协作中已创建或可以批准或拒绝的所有更新请求。注册更新请求可能需要几秒钟的时间，因此您可能看不到刚才发送的请求。

请参阅添加模板流程。

语法¶

VIEW_UPDATE_REQUESTS( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。

返回¶

在此协作中发送的更新请求表。信息包括

ID：请求的 ID。将其用于批准或拒绝请求。
TYPE：选择使用时默认使用的角色和仓库。请求的类型。支持以下值：
- “添加模板”
STATUS：选择使用时默认使用的角色和仓库。请求的当前状态。可以报告以下状态：
- REJECTED：选择使用时默认使用的角色和仓库。协作中有人拒绝了此请求。
- PENDING：选择使用时默认使用的角色和仓库。该请求正在等待您的批准或拒绝。
- AWAITING_PARTNER_APPROVAL：选择使用时默认使用的角色和仓库。您已批准该请求，但该请求仍需要得到一个或多个其他协作者的批准。
- APPROVED：选择使用时默认使用的角色和仓库。所有必需的审批者都已批准该请求，并且变更已应用于协作。
APPROVAL_LOG：选择使用时默认使用的角色和仓库。该请求的所有批准和拒绝的日志。如果该请求被拒绝，此处还会提供拒绝方给出的原因。
DETAILS：选择使用时默认使用的角色和仓库。特定于请求类型的详细信息，例如模板名称、描述以及“添加模板”请求的共享对象。
SPEC：选择使用时默认使用的角色和仓库。正在更新的资源的详细信息，例如“添加模板”请求的模板规范。
UPDATED_ON：选择使用时默认使用的角色和仓库。上次对此请求采取操作（例如，批准或拒绝）的时间戳。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_UPDATE_REQUESTS(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

APPROVE_UPDATE_REQUEST¶

架构:: COLLABORATION

批准协作更新请求。通过调用 VIEW_UPDATE_REQUESTS 来查看待处理请求列表。您批准某个请求后，以后将无法将其拒绝。

在将变更实际应用于协作之前，所有受影响的协作者都必须批准请求。

请参阅添加模板流程。

语法¶

APPROVE_UPDATE_REQUEST( <collaboration_name>, <request_id> )

Copy

实参¶

collaboration_name: 协作的名称。
request_id: 请求的 ID。

返回¶

字符串成功消息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.APPROVE_UPDATE_REQUEST(
  $collaboration_id,
  'request_1324f934457'
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REJECT_UPDATE_REQUEST¶

架构:: COLLABORATION

拒绝协作更新请求。单次拒绝会阻止将变更应用于协作。您无法在拒绝请求后批准该请求。

语法¶

REJECT_UPDATE_REQUEST( <collaboration_name>, <request_id>, <reason> )

Copy

实参¶

collaboration_name: 协作的名称。
request_id: 请求的 ID。
reason: 人类可读的描述，说明请求被拒绝的原因。该实参是必需的，但您可以提交空字符串。

返回¶

字符串成功消息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REJECT_UPDATE_REQUEST(
  $collaboration_id,
  'request_1324f934457',
  'Needs more cowbell'
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

协作管理过程¶

INITIALIZE¶

架构:: COLLABORATION

所有者调用此过程来创建协作。调用 INITIALIZE 后，您必须调用 JOIN 才能使协作可供其他协作者使用。您必须使用相同的角色才能调用 INITIALIZE 和 JOIN。

如果提交的协作定义与现有协作的 name 值相同，将会引发错误。

创建协作需要一些时间，因此您必须调用 GET_STATUS 才能了解协作何时创建。

创建协作后，所有列出的协作者在调用 VIEW_COLLABORATIONS 时可以看到该协作，并且可以查看和联接该协作。

语法¶

INITIALIZE( <collaboration_spec> )

Copy

实参¶

collaboration_spec: 协作定义采用 YAML 格式，以字符串形式呈现。

返回¶

字符串成功消息。调用 GET_STATUS 来了解协作何时准备就绪。

示例¶

以下示例创建了一个协作，其中 Alice 是所有者，并且可以使用 Bob 提供的数据运行分析。

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
  $$
  api_version: 2.0.0
  spec_type: collaboration
  name: basic_collaboration
  owner: alice
  collaborator_identifier_aliases:
    alice: corp_id.account_id
    bob: corp2_id.account2_id
  analysis_runners:
    alice:
      data_providers:
        bob:
          data_offerings:
          - id: bob_data_v1
      templates:
      - id: alice_test_template_2026_01_12_V1
  $$
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

有关所需的其他角色权限，请参阅 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。

TEARDOWN¶

架构:: COLLABORATION

由所有者调用，用于删除所有各方的协作。

必须调用此过程两次。 调用一次，然后调用 GET_STATUS 直到返回 LOCAL_DROP_PENDING，然后再次调用此过程。

备注

只能对您已创建和联接的协作调用此过程。如果您已创建但尚未联接协作，则必须先联接协作，然后才能将其拆除。

语法¶

TEARDOWN( <collaboration_name> )

Copy

实参¶

collaboration_name: 要删除的协作的名称。

返回¶

字符串成功消息。

示例¶

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_id);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_id);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_id);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

有关所需的其他角色权限，请参阅 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。

GET_STATUS¶

架构:: COLLABORATION

显示有关给定协作中所有协作者的信息。

运行异步操作（例如创建或联接协作）时，必须检查状态以了解上次操作何时完成，然后才能对该协作执行其他操作（例如运行分析）。受邀参与协作的任何协作者都可以调用此过程。

语法¶

GET_STATUS( <collaboration_name> )

Copy

实参¶

collaboration_name: 要查看其状态的协作的名称。您可以通过调用 COLLABORATION.VIEW_COLLABORATIONS 来查看协作列表。您必须先受邀参与协作或已联接协作，然后才能对该协作调用 GET_STATUS。

返回¶

一个表，其中显示有关指定协作中所有协作者的最新联接尝试的详细信息。该表包括以下各列：

UPDATED_ON：选择使用时默认使用的角色和仓库。系统报告状态的时间戳。
COLLABORATOR_ACCOUNT：选择使用时默认使用的角色和仓库。此协作者的数据共享账户 ID。
COLLABORATOR_NAME：选择使用时默认使用的角色和仓库。协作规范中声明的协作者别名。
COLLABORATOR_ROLES：选择使用时默认使用的角色和仓库。此协作者的实际和潜在角色。值包括 owner、data_provider、analysis_runner。
STATUS：选择使用时默认使用的角色和仓库。更新时的状态。支持以下值，并显示指定协作中指定协作者的状态。
- CREATING：选择使用时默认使用的角色和仓库。协作创建已启动。
- CREATE_FAILED：选择使用时默认使用的角色和仓库。协作创建失败。
- CREATED：选择使用时默认使用的角色和仓库。协作已创建，可以进行操作。
- INVITED：选择使用时默认使用的角色和仓库。已邀请参与者。
- REVIEWING：选择使用时默认使用的角色和仓库。目前正在审查该协作。
- JOINING：选择使用时默认使用的角色和仓库。联接过程已启动。
- JOIN_FAILED：选择使用时默认使用的角色和仓库。联接过程失败。
- JOINED：选择使用时默认使用的角色和仓库。已成功联接该协作。
- INVITE_STARTED：选择使用时默认使用的角色和仓库。邀请过程已启动。
- INVITE_ACCEPTED：选择使用时默认使用的角色和仓库。已接受邀请。
- LEAVING：选择使用时默认使用的角色和仓库。退出过程已启动。
- LEAVE_FAILED：选择使用时默认使用的角色和仓库。退出过程失败。
- LEFT：选择使用时默认使用的角色和仓库。成功退出该协作。
- LOCAL_DROP_PENDING：选择使用时默认使用的角色和仓库。您已成功提交删除或退出该协作的请求。请再次调用 TEARDOWN 或 LEAVE 来完成该过程。
- DROPPING：选择使用时默认使用的角色和仓库。删除过程已启动。
- DROPPED：选择使用时默认使用的角色和仓库。已成功删除。
- DROP_FAILED：选择使用时默认使用的角色和仓库。删除过程失败。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION¶

架构:: ADMIN

启用外部表和 Apache Iceberg™ 表，以便在您的账户中将其用于运行分析。分析执行器必须调用此过程，然后才能运行任何包含外部表或 Iceberg 表的分析。此过程在每次协作时调用一次，而不是在每次分析时调用一次。

语法¶

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。

返回¶

字符串成功消息。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用获得 MANAGE FIREWALL CONFIGURATION 权限的角色才能调用此过程。

VIEW_COLLABORATIONS¶

架构:: COLLABORATION

查看有关您已创建、可以查看或已联接的协作的信息。

语法¶

VIEW_COLLABORATIONS()

Copy

实参¶

无

返回¶

列出您可以访问的所有协作的详细信息的表。该表包括以下各列：

SOURCE_NAME：选择使用时默认使用的角色和仓库。协作的名称，由协作规范中的 name 值指定。
COLLABORATION_NAME：选择使用时默认使用的角色和仓库。已安装的协作的名称。在通过调用 ``JOIN``（所有者）或 ``REVIEW``（非所有者）安装协作之前，此值为 NULL。
OWNER_ACCOUNT：选择使用时默认使用的角色和仓库。创建了协作的账户的数据共享 ID。
UPDATED_ON：选择使用时默认使用的角色和仓库。上次更新协作的时间。
COLLABORATION_SPEC：选择使用时默认使用的角色和仓库。此协作的规范采用 YAML 格式。这将显示协作的最新版本，包括创建协作后添加或移除的任何资源。但是，可能会有正在进行的更新请求，这些请求很快就会添加，例如新增或移除模板或数据产品。

示例¶

查看所有协作：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();

Copy

按名称查看给定协作的规范：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS() ->>
SELECT "COLLABORATION_SPEC" FROM $1 WHERE "SOURCE_NAME" = $collaboration_id;

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW COLLABORATIONS', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REVIEW¶

架构:: COLLABORATION

提供有关您受邀参加的协作的详细信息。调用 COLLABORATION.VIEW_COLLABORATIONS 来查看您已受邀但尚未联接的协作。除所有者之外的所有协作者都必须先调用此过程，然后才能调用 JOIN。您不能对已联接的协作调用此过程。您必须使用相同的角色才能调用 REVIEW 和 JOIN。如果您的账户与所有者位于不同的云托管区域，您可能需要多次调用此过程，直到它返回成功的响应。

此过程将在您的账户中安装基础应用程序。

重要说明：

所有者无法对自己的协作调用 REVIEW。
除所有者外，每个人都必须先调用 REVIEW，然后才能调用 JOIN。
联接协作后，您无法再次调用 REVIEW。

语法¶

REVIEW( <source_name>, <owner_account> )

Copy

实参¶

source_name: 您受邀联接的协作的名称。您可以通过调用 COLLABORATION.VIEW_COLLABORATIONS 来查看协作列表。
owner_account: 所有者的数据共享账户标识符。这可以在对 COLLABORATION.VIEW_COLLABORATIONS 的响应中找到。

返回¶

有关协作的信息表，包括协作 ID、所有者和协作规范。

如果您的账户位于与协作所有者不同的云托管区域，REVIEW 可能会返回一条消息，说明仍在执行其他设置步骤。如果您收到此消息，请继续调用 REVIEW，直到返回有关协作的信息表。

示例¶

-- View the collaboration for your own usage.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REVIEW(
  $collaboration_id,
  'org1.account1234'
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

有关所需的其他角色权限，请参阅 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。

JOIN¶

架构:: COLLABORATION

用于联接指定协作的异步方法。请注意，您只能访问联接时协作中列出的资源。此过程需要一些时间才能运行。

您需要 REGISTER DATA OFFERING 账户权限才能联接任何可以在其中激活数据的协作（即，您是分析执行者，并且协作规范包括 activation_destinations 字段）。请参阅访问管理 API 参考指南。

运行此过程时，您不能拥有活动的次要角色。运行以下 SQL 代码以禁用任何次要角色：

USE SECONDARY ROLES NONE;

Copy

除协作创建者外，每个人都必须先调用 COLLABORATION.REVIEW，然后才能调用此过程。

此过程是异步的；调用 GET_STATUS 以确定您何时成功联接了协作。

向协作提交资源或想要在协作中运行模板的任何人（包括协作创建者）都必须先联接协作。

语法¶

JOIN( <collaboration_name> )

Copy

实参¶

collaboration_name: 要联接的协作的名称。您可以通过调用 COLLABORATION.VIEW_COLLABORATIONS 来查看协作列表。如果您受邀联接具有相同名称的多个协作，系统将默认选择您对其调用过 COLLABORATION.REVIEW 的最后一个协作。

返回¶

字符串成功消息。如果您收到有关缺少引用使用授权的错误，请参阅故障排除指南。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.JOIN(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

有关所需的其他角色权限，请参阅 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。

LEAVE¶

架构:: COLLABORATION

退出您已联接的协作。退出协作后，您无法重新联接该协作。

必须调用此过程两次。 调用一次，然后调用 GET_STATUS 直到返回 LOCAL_DROP_PENDING，然后再次调用此过程。

语法¶

LEAVE( <collaboration_name> )

Copy

实参¶

collaboration_name: 要退出的协作的名称。

返回¶

字符串成功消息。

示例¶

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_id);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_id);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_id);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

有关所需的其他角色权限，请参阅 GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE。

运行分析和激活¶

RUN¶

架构:: COLLABORATION

在 Data Clean Room 中运行分析。您可以以独立参数的形式传递运行详细信息，也可以通过传入分析 YAML 规范字符串传递运行详细信息。

有关在 Data Clean Room 中运行模板的背景信息，请参阅 consumer.run_analysis 参考。

此过程有两个版本：一个版本将运行实参作为单个 YAML 格式的字符串，另一个版本则将实参作为单独的参数。

YAML 实参语法¶

RUN( <collaboration_name>, <analysis_spec> )

Copy

实参¶

collaboration_name: 要在其中运行此分析的协作的名称。
analysis_spec: 分析定义，采用 YAML 格式，以字符串形式呈现，描述要在此分析中使用的模板、表和模板值。

显式参数语法¶

RUN( <collaboration_name>, <template_id>, <template_view_names>, <local_template_view_names>, <arguments> )

Copy

实参¶

collaboration_name: 要在其中运行此分析的协作的名称。
template_id: 要运行的模板的 ID。
template_view_names: 要在分析中使用的源表的字符串名称数组。使用 TEMPLATE_VIEW_NAME 列中 VIEW_DATA_OFFERINGS 返回的表名。每个条目的格式为 user_alias.data_offering_id.dataset_alias
local_template_view_names: 要在分析中使用的您自己的表的字符串 IDs 数组。您必须先通过调用 LINK_LOCAL_DATA_OFFERING 来链接这些表。
arguments: 包含模板使用的命名实参的 JSON 对象，其中每个键都是模板实参名称，值是该实参的值。

返回¶

以表格形式呈现的分析结果。

示例¶

按参数传递示例：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_id,
  $template_name,
  ['Provider.data_offering_1_2026_01_12_v0.test_dataset'], -- Tables to pass to source_tables variable.
  [],
  {} -- Template takes no parameters.
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_ACTIVATIONS¶

架构:: COLLABORATION

显示您触发发送给协作者的任何分析运行的激活状态，或者协作者触发发送给您的激活。未列出向自己发送数据的激活请求。

有关激活的更多信息，请参阅激活查询结果。

语法¶

VIEW_ACTIVATIONS( <collaboration_name> )

Copy

实参¶

collaboration_name: 协作的名称。

返回¶

包含每次激活详细信息的表。该表包括以下各列：

UPDATED_ON：选择使用时默认使用的角色和仓库。上次更新状态的时间。
SEGMENT_NAME：选择使用时默认使用的角色和仓库。分析执行器分配的任意字符串，用于标识此激活。有关更多信息，请参阅 Activating query results。
ACTIVATION_ID：此激活请求的 ID。有关更多信息，请参阅查看提供商和使用者激活结果。
TEMPLATE_ID：选择使用时默认使用的角色和仓库。用于生成此激活数据的模板。
SHARED_BY：选择使用时默认使用的角色和仓库。已运行分析的协作者。
SHARED_WITH：选择使用时默认使用的角色和仓库。应接收分析数据的协作者。
STATUS：选择使用时默认使用的角色和仓库。激活的状态。支持以下值：
- PENDING：选择使用时默认使用的角色和仓库。已请求激活，但正在等待处理。
- SHARED：选择使用时默认使用的角色和仓库。激活数据可进行处理。调用 PROCESS_ACTIVATION 将结果发送到您的账户。
- FAILED：选择使用时默认使用的角色和仓库。激活处理失败。请参阅 DETAILS 列中的信息。
- PROCESSED：选择使用时默认使用的角色和仓库。激活结果已发送到激活请求中指定的账户。
DETAILS：选择使用时默认使用的角色和仓库。失败详细信息（如果激活失败）。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_ACTIVATIONS(
  $collaboration_id
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW ACTIVATIONS', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

PROCESS_ACTIVATION¶

架构:: COLLABORATION

如果分析执行器正在向另一个协作者的账户发送数据，则该协作者应调用 PROCESS_ACTIVATION 将激活数据导入到其账户。该协作者应调用 VIEW_ACTIVATIONS，并等待输出显示给定段的激活状态为 SHARED，然后再调用 PROCESS_ACTIVATION。

语法¶

PROCESS_ACTIVATION( <collaboration_name>, <segment_name> )

Copy

实参¶

collaboration_name: 协作的名称。
segment_name: 分配的任意字符串，用于在结果表中标识此激活。在分析查询中使用 template_configuration.arguments.segment_name 指定段名称。有关更多信息，请参阅 Activating query results。

返回¶

用户可以检索结果的表名称，以及为结果指定的段名称。请参阅激活查询结果，了解如何读取结果。

示例¶

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.PROCESS_ACTIVATION(
  $collaboration_id,
  'q1_2025_segment'
);

Copy

访问要求¶

如果不使用 SAMOOHA_APP_ROLE 角色，则必须使用通过调用以下任一过程获得权限的角色：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('PROCESS ACTIVATION', 'COLLABORATION', 'collaboration name', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')
GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

访问管理过程¶

SAMOOHA_APP_ROLE 角色授予对所有 DCR Collaboration API 过程的访问权限。但是，如果管理员想向特定角色授予更精细的权限，您可以创建一个角色，并按照本节中描述的过程授予其特定权限。

要了解有关授予访问权限的更多信息，请访问授予对 DCR Collaboration API 的使用权限。

以下过程用于管理对 Snowflake Data Clean Room Collaboration API 的细粒度访问权限：

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE¶

架构:: ADMIN

向特定角色授予对特定对象调用特定过程的权限。对象类型是通过 OBJECT_TYPE 实参定义的。

您可以多次调用此过程，以向同一角色授予多个权限。使用拥有该对象的角色运行此过程。

语法¶

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  <privilege>,
  <object_type>,
  <object_name>,
  <account_role_name> )

Copy

实参¶

privilege

应授予此角色什么权限。请参阅下表，了解哪些权限可用于哪些对象。

object_type

向此角色授予权限的对象类型。支持的值：

COLLABORATION
REGISTRY

object_name

按照对象规范中指定的对象的 ID。

account_role_name

获得授权的角色。

支持以下权限和对象类型组合：

权限	对象类型	已启用的过程
`READ`	`COLLABORATION`	`VIEW_COLLABORATIONS`、`GET_STATUS`、`VIEW_DATA_OFFERINGS`、`VIEW_UPDATE_REQUESTS`、`VIEW_TEMPLATES`
`RUN`	`COLLABORATION`	`RUN`、 `VIEW_ACTIVATIONS`、 `VIEW_COLLABORATIONS`
`UPDATE`	`COLLABORATION`	`LINK_DATA_OFFERING`、`UNLINK_DATA_OFFERING`、`LINK_LOCAL_DATA_OFFERING`、`UNLINK_LOCAL_DATA_OFFERING`、`ADD_TEMPLATE_REQUEST`、`REMOVE_TEMPLATE`、`APPROVE_UPDATE_REQUEST`、`REJECT_UPDATE_REQUEST`、`ENABLE_TEMPLATE_AUTO_APPROVAL`、`DISABLE_TEMPLATE_AUTO_APPROVAL`、`VIEW_UPDATE_REQUESTS`

返回¶

字符串成功消息。

示例¶

此示例为分析师创建了一个角色，用于在名为 my_collaboration 的协作中运行分析，并将其分配给用户。

USE ROLE role_that_created_this_collaboration;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_id,
  'collaborator_analyst_role'
);
GRANT ROLE collaborator_analyst_role to USER alexander_hamilton;

Copy

访问要求¶

您必须使用创建该协作的同一角色才能对该协作调用 GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE。

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE¶

架构:: ADMIN

向角色授予账户级权限。此过程允许任何使用该角色的用户调用为该权限列出的相关过程。

语法¶

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE( <privilege>, <account_role_name> )

Copy

实参¶

privilege

要授予此角色的权限。支持以下字符串值：

JOIN COLLABORATION：选择使用时默认使用的角色和仓库。授予运行 COLLABORATION.JOIN 的权限，以及对已联接的协作运行以下过程的权限：
- ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE
- COLLABORATION.ADD_TEMPLATE_REQUEST
- COLLABORATION.APPROVE_UPDATE_REQUEST
- COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL
- COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL
- COLLABORATION.REMOVE_TEMPLATE
- COLLABORATION.GET_STATUS
- COLLABORATION.LEAVE
- COLLABORATION.LINK_DATA_OFFERING
- COLLABORATION.LINK_LOCAL_DATA_OFFERING
- COLLABORATION.PROCESS_ACTIVATION
- COLLABORATION.REJECT_UPDATE_REQUEST
- COLLABORATION.REVIEW
- COLLABORATION.RUN
- COLLABORATION.TEARDOWN
- COLLABORATION.UNLINK_DATA_OFFERING
- COLLABORATION.UNLINK_LOCAL_DATA_OFFERING
- COLLABORATION.VIEW_ACTIVATIONS
- COLLABORATION.VIEW_COLLABORATIONS
- COLLABORATION.VIEW_DATA_OFFERINGS
- COLLABORATION.VIEW_TEMPLATES
- COLLABORATION.VIEW_UPDATE_REQUESTS
- REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS
- REGISTRY.VIEW_REGISTERED_TEMPLATES
此权限需要手动向角色授予以下账户级权限：
- APPLY ROW ACCESS POLICY
- CREATE APPLICATION
- CREATE DATABASE
- CREATE LISTING
- CREATE SHARE
- IMPORT SHARE
- MANAGE SHARE TARGET
CREATE COLLABORATION：选择使用时默认使用的角色和仓库。授予运行 COLLABORATION.INITIALIZE 的权限，以及对已联接的协作运行 JOIN COLLABORATION 允许的所有过程的权限。需要手动向角色授予以下账户级权限：
- APPLY ROW ACCESS POLICY
- CREATE APPLICATION
- CREATE DATABASE
- CREATE LISTING
- CREATE SHARE
- IMPORT SHARE
- MANAGE SHARE TARGET
VIEW COLLABORATIONS：选择使用时默认使用的角色和仓库。授予运行 COLLABORATION.VIEW_COLLABORATIONS 的权限。需要手动向角色授予以下权限：
- IMPORT SHARE
REGISTER DATA OFFERING：选择使用时默认使用的角色和仓库。授予运行 REGISTRY.REGISTER_DATA_OFFERING 的权限。任何分析执行器都需要此权限才能联接实施激活的协作。
VIEW REGISTERED DATA OFFERINGS：选择使用时默认使用的角色和仓库。授予运行 REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS 的权限。
VIEW REGISTERED TEMPLATES：选择使用时默认使用的角色和仓库。授予运行 REGISTRY.VIEW_REGISTERED_TEMPLATES 的权限。
REGISTER TEMPLATE：选择使用时默认使用的角色和仓库。授予运行 REGISTRY.REGISTER_TEMPLATE 的权限。
MANAGE LISTING AUTO FULFILLMENT：选择使用时默认使用的角色和仓库。授予协作者在另一个云托管区域联接协作的权限。有关更多信息，请参阅启用 Cross-Cloud Auto-Fulfillment。

account_role_name

账户级角色的名称。

返回¶

字符串成功消息。

示例¶

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE(
  'REGISTER DATA OFFERING',
  'COLLABORATOR_ANALYST_ROLE'
);

Copy

访问要求¶

您需要 ACCOUNTADMIN 角色来运行此过程。