基本多方 Collaboration

简介

本主题介绍创建基本多方 Collaboration 的步骤。它演示了如何注册模板和数据产品、如何向 Collaboration 的初始版本添加数据，以及协作者在 Collaboration 创建后如何添加资源。它还演示了如何在 Collaboration 中使用模板和数据资源运行查询。

基本 Clean Room 协作工作流程

以下是基本的多方 Clean Room Collaboration 场景：

  1. Collaboration 所有者 可以注册他们希望在 Collaboration 的初始配置中显示的任何模板或数据产品。

  2. 所有者可以选择要求任何预期协作者注册他们希望在 Collaboration 的初始配置中显示的模板或数据产品。随后，协作者将已注册项目的 IDs 资源赋予所有者。

  3. 所有者 创建 Collaboration。Collaboration 由 Collaboration YAML 规范定义，列出协作者及其 Collaboration 角色，以及 Collaboration 初始版本中应存在的所有资源。

    • 创建 Collaboration 时，协作者集及其 Collaboration 角色是固定的。

    • 如果 Collaboration 角色允许，协作者可以在创建 Collaboration 后添加其他资源。

    • 如果您的 Collaboration 与其他云托管区域的用户共享数据，则共享者必须 为其账户启用 Cross-Cloud Auto-Fulfillment。

  4. 协作者 查看并加入协作。

  5. 之后，协作者可以根据他们在 Collaboration 中的角色，选择性地 将其他资源关联到 Collaboration，例如模板和数据产品。可以随时将其他资源添加到 Collaboration 中。

  6. 分析运行者可以在 Collaboration 中 运行为他们分配的任何模板，使用他们在 Collaboration 中可用的任何数据。分析运行者承担分析成本。模板可以设计为在响应中返回查询结果，也可以 将结果激活并传递给调用方或其他协作者。

以下部分介绍每个步骤的详细信息。

创建协作

要创建 Collaboration，您需要设计 :ref:` Collaboration 规范 <label-dcr_collaboration_spec_yaml>`，定义所有协作者 及其 Collaboration 角色。

如果希望在 Collaboration 创建后立即使资源可用， Collaboration 所有者可以在创建 Collaboration 之前 注册并关联这些资源，并将资源 IDs 包含在 Collaboration 规范中。

如果所有者希望使用协作者提供的资源，则所有者还可以提示这些用户注册其资源，并向所有者提供资源 IDs 以包含在协作规范中。所有者还需在 Collaboration 规范中指明：某些资源当前尚未关联，但未来可以进行关联。

然后，所有者调用 INITIALIZE 以开始创建协作。默认情况下，INITIALIZE 还会自动将所有者联结到协作。这是一个异步过程，因此所有者必须调用 GET_STATUS，直到状态为 JOINED。

以下代码片段演示了如何创建和加入 Collaboration。

 1  CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
 2    $$
 3    api_version: 2.0.0
 4    spec_type: collaboration
 5    name: my_first_collaboration
 6    owner: alice
 7    collaborator_identifier_aliases:
 8      alice: example_com.acct_abc
 9      bob: another_example.acct_xyz
10    analysis_runners:
11      bob:
12        data_providers:
13          alice:
14            data_offerings: [] -- alice has not provided data to bob, but can do so in the future.
15          bob:
16            data_offerings: [customers_v1]  -- bob has registered a data offering and made it available to himself.
17        templates: []   -- No templates available yet for bob.
18      alice:
19        data_providers:
20          alice:
21            data_offerings: []
22          bob:
23            data_offerings: []
24        templates: []
25    $$,
26    'APP_WH'            -- Use this warehouse for initialization.
27  );                    --  XSMALL or SMALL warehouses are recommended for initialization.
28  SET collaboration_name = 'my_first_collaboration';
29
30  -- INITIALIZE automatically joins the owner. Check status until JOINED.
31  CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);
32
33  -- Collaboration is visible here when it's joined.
34  CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();

脚本说明：

  • Collaboration 由两名协作者组成，其别名分别为 alice 和 bob。在任何使用别名的地方，您都可以使用完整的数据共享 ID，但这会显著降低用户体验的友好度。

  • alice 是所有者。

  • alice 和 bob 都是分析运行者。

  • alice 和 bob 互为数据提供商。

  • 如果您是数据提供商，则必须包括 data_offerings 字段。该字段可以填写内容，也可以留空；留空表示当前没有数据产品，但后续可以添加。

  • alice 目前并未向 bob 或自身提供数据，但后续可以做到（见第 14、22 行）。

  • bob 已经注册了一个数据产品，并在初始 Collaboration 中将其提供给了自己（见第 16 行）。

  • bob 目前未向 alice 提供数据，但后续可以做到（见第 24 行）。

  • alice 和 bob 目前都还没有可用的模板，但后续可以分配（见第 18、25 行）。请注意，templates 字段对于分析运行者来说是可选的。如果在初始化时省略此字段，协作者后续仍可以为该分析运行者分配模板。

查看和加入 Collaboration

您必须加入 Collaboration 才能在 Collaboration 中共享资源并运行分析。

  • 如果在调用 INITIALIZE 时提供了 auto_join_warehouse，则 创建者 会自动加入。如果未提供 auto_join_warehouse，创建者会在 INITIALIZE 完成后调用 JOIN。

  • 非创建者 调用 REVIEW，然后调用 JOIN。

    • REVIEW 返回 Collaboration 及其资源的概述。您仅可以调用 REVIEW 一次。

    • JOIN 在您的账户中安装 Collaboration Clean Room 并加入 Collaboration。

INITIALIZE 和 JOIN 均为异步过程，需要几分钟才能完成。您必须调用 GET_STATUS 查看每个步骤何时完成。

重要

如果您账户的云托管区域与 Collaboration 所有者不同，REVIEW 会触发额外的异步设置步骤。重复调用 REVIEW，直到返回成功响应，表示设置已完成。

联接是一个异步过程；调用 GET_STATUS 以查看您的状态何时列为 JOINED.

运行分析

如果您在 Collaboration 中拥有分析运行者的角色，则可以对 Collaboration 中与您共享的数据源运行分析。

Collaboration 支持两种类型的查询：

  • 模板分析。 这些查询会运行关联到 Collaboration 中的模板（即模板化 JinjaSQL 语句）。模板可以是分析模板（结果立即返回给您），也可以是激活模板（结果保存到指定参与者的 Snowflake 账户中）。

  • 自由格式 SQL 查询。 如果数据提供商允许，您可以使用协作者凭证登录，通过 SQL 语句访问指定的数据产品。您无需调用 Collaboration 的 API 存储过程，只需直接访问 Collaboration 所暴露的全限定视图名称，即可运行 SQL 查询。

分析运行者承担分析的运行成本。

协作规范决定了您是否可以运行模板、激活结果或运行自由格式的 SQL 查询。协作规范中描述了您的功能以及可供您使用的数据和模板。

备注

数据源中的列在向模板或用户公开时可能会有新名称。请参阅 源列重命名，了解如何以及何时重命名源列。如果重命名了列，模板和用户提供的实参（例如联接列名称）必须使用最终名称，而不是原始名称。

在以下部分中了解有关所有这些分析类型的更多信息。

从模板运行分析

要从模板运行分析，请查看您可以运行的模板列表，查看您可以使用的数据产品列表，然后调用 RUN，将您的值作为单个参数或作为 YAML 格式的分析规范。

您在运行配置中传入 source_tables 字段的表，将会填充模板中的 source_table 参数。除非您正在使用 Snowflake Standard Edition 并结合您自己的数据，否则模板的 my_table 参数不会被填充或使用。

备注

资源安装是异步的。如果模板是刚刚安装的，可能需要一段时间才能运行。如果模板包含代码捆绑包，则可能需要额外的时间才能使用模板。了解如何确定代码捆绑包何时可用。

以下示例列出了用户可以访问的数据产品和模板，然后使用 sales_join_template 模板（假定该模板已由 VIEW_TEMPLATES 列出）运行分析，并向该模板传递了五个命名参数。

-- See which data offerings are available.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- See which templates you can run.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: My_analysis
    description: Sales results Q2 2025
    template: sales_join_template

    template_configuration:
      view_mappings:
        source_tables:
          -  user1_alias.data_offering_v1.table_1
          -  user2_alias.another_data_offering_v1.table_2
      arguments:                                            -- The template defines conv_purchase_id and the other four arguments.
         conv_purchase_id: PURCHASE_ID                      -- You must examine a template to see which arguments it supports.
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

对数据启用并运行自由格式的 SQL 查询

数据提供商可以授予分析运行者权限，允许其针对数据产品运行任意 SQL 查询。这意味着分析运行者可以直接对数据产品运行任意 SQL 查询，而无需调用模板。

了解有关自由格式 SQL 查询的更多信息，请参阅 自由格式 SQL 查询。

使用 Standard Edition 时，使用自己的数据运行分析

如果您使用 Standard Edition，则可以 以标准方式 运行分析。但您不能将数据关联到 Collaboration 中以供其他用户分享使用。将自己的数据集传递到模板中的唯一方法是使用此处描述的技术。

要在 Snowflake Standard Edition 上的 Collaboration 中使用您自己的数据，请执行以下操作：

  1. 通过调用 REGISTER_DATA_OFFERING 注册您的数据产品。

  2. 调用 LINK_LOCAL_DATA_OFFERING 将您的数据关联到 Collaboration 中供您使用。其他协作者无法查看或访问本地关联的数据。

  3. 在调用 RUN 时，请使用数据产品 ID。

  • 如果您使用的是带参数的 RUN 版本，请将您的数据产品 IDs 传递给 local_template_view_names 参数

  • 如果您使用的是 RUN 的 YAML 版本，请在请求的 local_view_mappings.my_tables 部分提供您的数据产品 IDs。

  • 如果您使用的是带参数的 RUN 版本，请将您的数据产品 IDs 传递给 local_template_view_names 参数。

小技巧

local_template_view_names 和 local_view_mappings.my_tables 填充模板中的 my_table 参数。

以下示例展示了如何使用运行过程的 YAML 格式版本。此示例包括 my_tables 字段，该字段通过调用 LINK_LOCAL_DATA_OFFERING 填充。

-- See what data offerings are available. Your own local data will be listed here as well.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: my_analysis
    description: Cross-purchase results for Q4 2025
    template: mytemplate_v1

    template_configuration:
      view_mappings:
        source_tables:
          - ADVERTISER1.ADVERTISER_DATA_V1.CUSTOMERS
          - PUBLISHER.ADVERTISER_DATA_V1.CUSTOMERS
      local_view_mappings:
        my_tables:
          - PARTNER.MY_DATA_V1.MY_CUSTOMERS # Populate my_table array with my own table.
      arguments:  # Template arguments, as name: value pairs
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

激活结果

如果数据提供商和 Collaboration 规范允许，您可以将分析结果保存到您自己的 Snowflake 账户，或指定协作者的 Snowflake 账户。模板要么激活结果，要么立即返回结果，但不能两者兼而有之。

要了解有关激活的更多信息，请参阅 Activating query results。

退出或删除协作

  • 非所有者通过调用 LEAVE 来退出协作。他们提供的任何数据产品都将从协作中移除。退出协作后，您无法重新加入协作。

  • Collaboration 所有者无法退出 Collaboration；因为所有权无法转让。协作所有者可以通过调用 TEARDOWN，为所有协作者删除协作。

这两个过程都是异步过程。您必须调用 GET_STATUS 以监控状态，并在 GET_STATUS 将状态显示为 LOCAL_DROP_PENDING 时，再次调用 LEAVE 或 TEARDOWN。

示例

以下 SQL 示例演示了如何创建并运行一个基础 Collaboration：

双方 Collaboration 示例

以下示例演示了一个两方 Collaboration：一方（名为“alice”）是 Collaboration 创建者，同时是她自己和“bob”的数据提供商，也担任分析运行者。“bob”是他自己和“alice”的数据提供商，同时也是分析运行者。

该示例演示以下操作：

  • 创建协作。

  • 注册模板和数据产品。

  • 在 Collaboration 创建时关联模板和数据产品。

  • 加入协作。

  • 将其他资源关联到现有 Collaboration。

  • 运行分析。

要运行此示例，您必须拥有两个已安装 Snowflake Data Clean Rooms 的不同账户。

您可以下载文件并将其上传到您的 Snowflake 账户，也可以使用 Snowsight 将示例代码复制并粘贴到两个单独账户的工作表中。

下载源 SQL 文件，然后将它们上传到两个已安装 Snowflake Data Clean Rooms 的独立账户：

单方 Collaboration 示例

此示例演示了在仅使用单个账户进行测试时，如何创建和使用 Collaboration。

该示例演示了如何创建带有数据产品和模板的 Collaboration，在 Collaboration 创建后添加更多数据产品和模板，并运行分析。

您可以下载该文件并上传到您的 Snowflake 账户，或者使用 Snowsight 将示例代码复制粘贴到工作表中。

下载源 SQL 文件，然后将其上传到已安装 Snowflake Data Clean Rooms 的 Snowflake 账户中：