使用 Snowflake Collaboration Data Clean Room¶
本主题提供了使用 Collaboration Data Clean Room 的高级指南。它还详细介绍了创建或参与协作所需的所有关键步骤。
要求¶
所有者和数据提供商必须使用 Snowflake Enterprise Edition。分析执行器可以使用 Standard Edition。
您需要访问 Data Clean Room Collaboration API 才能查看或管理协作。有关更多信息,请参阅 管理对 DCR Collaboration API 的访问权限。
使用 Collaboration API 时,应禁用环境中的次要角色:
基本 Clean Room 协作工作流程¶
以下是简单的 Clean Room 协作场景:
协作 所有者 可以选择注册他们希望在协作的初始配置中显示的任何模板或数据产品。
所有者可以选择要求任何预期协作者注册他们希望在协作的初始配置中显示的任何模板或数据产品。然后,协作者提供他们注册的任何项目的资源 IDs。
然后,所有者 创建协作。协作由协作 YAML 规范定义,列出协作者及其角色,以及协作初始版本中应存在的所有资源。
创建协作时,协作者及其角色的集合是固定的:仅具有协作定义中指定角色的协作者会受邀加入。同样,分析运行者的集合也是固定的。但是,通过将新数据链接到协作,任何协作者也都可以成为数据提供商。
如果协作包括其他云托管区域的用户,他们必须 为其账户启用 Cross-Cloud Auto-Fulfillment,然后才能查看和加入协作。
所有者加入他们创建的协作,从而使协作处于活动状态。现在,规范中的任何协作者都可以看到和加入协作。
协作者 查看并加入协作。
然后,协作者可以选择 将资源添加到协作,例如模板,如果是数据提供商,则为数据产品。
然后,分析运行者可以在协作中 运行为他们分配的任何模板,使用他们在协作中可用的任何数据(以及可选的非共享本地数据)。分析运行者承担分析成本。模板可以在响应中返回查询结果,也可以 将结果激活并传递给调用方或其他协作者。
以下部分介绍每个步骤的详细信息。
创建协作¶
要创建协作,您需要设计 协作规范,定义所有协作者 及其角色。协作所有者可以选择 注册并链接他们希望在初始协作中提供的任何其他资源,并将这些资源包含在协作规范中。如果所有者希望使用协作者提供的资源,则所有者还可以提示这些用户注册其资源,并向所有者提供资源 IDs 以包含在协作规范中。
然后,所有者调用 INITIALIZE 以开始创建协作。默认情况下,INITIALIZE 还会自动将所有者联结到协作。这是一个异步过程,因此他们必须调用 GET_STATUS,直到状态为 JOINED。当协作状态为 JOINED 时,协作将处于活动状态,并且所有协作者都可以查看并加入协作。
将资源添加到协作¶
任何协作者都可以将资源添加到协作中,也可以移除已添加到协作中的资源。将资源添加到协作有两个步骤:
资源所有者为资源创建 资源定义规范,并使用该规范在其账户中注册资源。您可以在账户的 默认注册表 中注册资源,或使用自定义注册表。
协作者将资源链接到协作中。链接资源后,指定的协作者就可以使用该资源。某些资源类型(例如模板)可以由任何协作者链接;其他资源(例如数据产品)只能由具有数据提供商角色的用户链接。资源通常仅提供给协作规范和资源共享者定义的特定协作者。
在创建协作之前或之后都可以将资源添加到协作中。
资源支持版本控制;但是,使用新版本创建新资源不会将以前的版本从协作中移除。
资源通过组合用户提供的名称和版本(以及数据产品的别名)进行唯一命名。
您可以将以下资源添加到协作中:
模板¶
模板是可由指定协作者运行的 JinjaSQL Clean Room 模板。只要所有受影响的协作者都批准了请求,任何协作者都可以注册模板并将其添加到协作中,如以下步骤所述。您只能添加或移除您的账户已注册的模板。
要将模板添加到协作,请执行以下操作:
通过调用
REGISTRY.REGISTER_TEMPLATE注册模板。这会返回一个模板 ID。链接模板。过程取决于协作是否已存在:
要在创建协作之前添加模板, 请向协作所有者提供模板 ID,该所有者会将其添加到 协作规范,定义谁可以运行模板。
要将模板添加到现有协作中, 您必须向受模板影响的所有协作者请求权限。请执行以下步骤,将模板添加到现有协作:
调用
REGISTER_TEMPLATE以在您的账户中注册模板,使其可以添加到协作中。使用模板 ID 调用
ADD_TEMPLATE_REQUEST以启动审批流程,以便为特定用户将模板添加到特定协作。受资源影响的所有协作者在调用
VIEW_UPDATE_REQUESTS时都会看到请求。看到状态为 PENDING 的请求的协作者应该调用
APPROVE_UPDATE_REQUEST或REJECT_UPDATE_REQUEST。如果有任何协作者拒绝请求,则更新请求都将被拒。
协作者无法之后将批准更改为拒绝,或将拒绝更改为批准。
当请求状态为 APPROVED 时,模板可供模板添加请求中指定的用户使用。如果请求状态为 REJECTED,则拒绝方提供的任何原因在请求报告中均可见。获得所有用户批准后,模板在可用之前可能会有短暂的延迟。如果要确保模板可供使用,请调用
view_templates。
小技巧
要查看您注册了哪些模板,请调用 REGISTRY.VIEW_REGISTERED_TEMPLATES。
协作的模板设计¶
协作模板与 Clean Room 模板 相同,但有一些特殊注意事项:
协作中列出的共享表用于填充模板的
source_table变量。my_table仅当分析运行者想要使用本地非共享数据时使用。如果您在模板中使用my_table的变量,请注意,分配给该变量的表不会与协作共享。数据源中的列在向模板或用户公开时可能会有新名称。请参阅 源列重命名,了解如何以及何时重命名源列。如果重命名了列,模板和用户提供的实参(例如联接列名称)应使用最终名称,而不是原始名称。
协作中的激活模板无需命名为
activation_template_name。所有其他 激活模板要求 仍然适用。
有关 Snowflake Data Clean Room 中自定义模板语法的信息,请参阅 自定义 Clean Room 模板参考。
数据产品¶
数据产品 是协作中与特定分析运行者共享的一个或多个数据视图。协作中列出的任何数据提供商都可以添加数据产品。数据产品以限定范围的格式 data offering ID.alias 公开,其中别名是数据产品中的特定视图。仅当 协作规范 中将您列为该分析运行者的数据提供商时,您才能与指定的协作者共享数据产品。
数据产品是数据的实时视图,而不是创建或注册数据产品时的数据快照。应用于源数据的任何 Snowflake 策略在协作中都处于活动状态。
注册数据产品时,Snowflake 会为 数据产品规范 中列出的每个数据源创建视图。该视图仅包括数据产品规范中列出的列。当您将数据产品链接至协作时,Snowflake 会根据 协作规范 创建该视图的副本,并对可访问该数据产品的任何分析运行者实施访问保护。如果您移动、重命名或更改基础表的访问权限,则数据产品将无法通过任何以前注册的链接使用。
如果您使用的是 Snowflake Standard Edition,则无法与其他协作者共享数据产品,但可以 在查询中使用您自己的数据。
要求:
您必须对您要共享的任何数据拥有 OWNERSHIP。否则,当您尝试加入协作时,您会收到“missing reference usage grant”错误。了解如何处理此问题。
您必须在协作中拥有 数据提供商角色。
要将数据产品添加到协作,请按照以下步骤操作:
为您的数据创建 数据产品规范。
通过调用
REGISTRY.REGISTER_DATA_OFFERING注册数据产品,这会返回数据产品 ID。此步骤使数据产品 可以 链接到您可以访问的任何协作。您可以使用相同的数据产品 ID 与多个协作共享数据产品。
下一步取决于是否已创建协作:
如果尚未创建协作, 数据提供商将向协作创建者提供数据产品 ID,以添加到 协作定义。将数据产品添加到协作定义时,在数据提供商加入协作后,协作中的任何人都可以看到该数据产品。
如果已创建协作, 数据提供商会加入协作并调用
COLLABORATION.LINK_DATA_OFFERING,提供数据产品 ID、协作名称,以及数据共享对象。获得所有用户批准后,数据产品或服务在可用之前可能会有短暂的延迟。如果要确保数据可供使用,请调用view_data_offerings。
您可以调用
unlink_data_offering,从协作中移除数据资源。
每个数据产品代表一个或多个表或视图。使用语法 collaborator alias.data offering ID.dataset alias 访问单个表,其中数据产品 ID 是用户提供的名称和版本值的组合,别名是产品中的单个表。注册数据产品时,将名称、版本和别名视为范围界定系统。
例如,您可以注册以下销售数据的数据产品,其中每个表对应一个 US 州:
然后,分析运行者会以 data offering id.AL、data offering id.NY 或 data offering id.CA 引用这些表。
在注册数据产品的用户加入协作之前,数据产品在协作中不可见。
小技巧
如果您对共享的数据没有 OWNERSHIP,当您尝试加入协作或链接数据产品时,您将会收到错误消息。错误消息提供有关 ACCOUNTADMIN 必须运行的 SQL 命令的信息,以授予对协作的数据访问权限。ACCOUNTADMIN 运行该命令后,您将能够加入协作。查看更多信息。
运行查询时,分析运行者会按 ID 将数据产品传递给 COLLABORATION.RUN 的 source_tables 参数。
要查看您注册的数据产品,请调用 VIEW_REGISTERED_DATA_OFFERINGS。
将使用策略应用于数据¶
有两种方法可以将 Snowflake 列策略(例如联接或聚合策略)应用于共享数据:
在源数据上应用策略。 应用于源数据的任何策略都会在协作公开的数据集中强制执行。确保将策略传达给用户。
在自由格式查询中使用时,将策略应用于数据产品。 如果您允许对数据产品进行自由格式查询,则可以指定要对数据的自由格式查询强制执行的列策略。在数据产品规范中指定自由格式查询的列策略。这些策略叠加在源表上任何现有 Snowflake 策略之上。
将策略应用于源数据¶
应用于源数据的任何 Snowflake 策略也适用于协作中的数据产品视图。
如果您将 Snowflake 策略应用于源数据,请务必让您的协作者了解这些策略,以免他们在不知不觉中尝试运行对不可联接列进行联接的查询,或者在应该进行分组时不进行分组的查询。您可以在数据产品的 description 字段中提及任何 Snowflake 策略。
在数据产品上应用策略(仅限自由格式查询使用)¶
您可以将 Snowflake 策略应用于共享数据中的 自由格式查询,而无需将其应用于源数据。这些策略会在通过自由格式查询访问您的数据时生效,且会与直接应用于源表的任何 Snowflake 策略叠加执行。
要为数据添加自由格式的 SQL 策略,请执行以下步骤:
将以下信息添加到数据产品定义中:
设置
allowed_analyses: template_and_freeform_sql。为数据集定义添加
freeform_sql_policies部分。在
freeform_sql_policies下面添加适当的策略类型部分,列出您创建的 Snowflake 策略,以及要为这些策略应用的协作列。
协作者在调用 COLLABORATION.VIEW_DATA_OFFERINGS 时会看到应用于数据的策略类型。
您可以对多个表的多个列重复使用同一个策略。
示例:
源列重命名¶
向模板或自由格式 SQL 调用方公开的列名由 category 和 column_type 值确定,这些值在 数据产品定义 中定义列。列重命名遵循以下准则:
如果列的
category为join_custom或passthrough,则公开原始列名。如果
category为join_standard,则列被重命名为column_type值。如果
category为timestamp,列在数据产品中被重命名为timestamp。
例如,如果源表中的列名为 user_email_address,则此列向模板或自由格式 SQL 公开的方式取决于数据产品定义中的定义方式:
如果列类别为
join_standard并且column_type存在:然后
column_type值用于查询和模板:如果列类别为
join_custom:然后,在查询和模板中使用原始源列名称:
加入协作¶
您必须加入协作,才能使您为该协作提供的任何资源在协作中可用,或能够在该协作中运行分析。
创建者 会在调用时自动联结 INITIALIZE(除非提供了
auto_join_warehouse)。如果禁用了自动联结,创建者将单独调用 JOIN。非创建者 调用 REVIEW,然后调用 JOIN。
重要
如果您的账户与协作所有者的账户位于不同的云托管区域:
如果 您的账户未启用 Cross-Cloud Auto-Fulfillment,则
REVIEW请求将失败。REVIEW会触发额外的异步设置步骤。重复调用REVIEW,直到返回成功响应,表示设置已完成。
联接是一个异步过程;调用 GET_STATUS 以查看您的状态何时列为 JOINED.
运行分析¶
要运行分析,您可以在查询中运行模板,也可以对协作数据运行自由格式的 SQL 查询。您必须是协作中指定的 分析运行者,才能运行分析。协作规范决定了您是否可以运行模板、激活结果或运行自由格式的 SQL 查询。协作规范中描述了您的功能以及可供您使用的数据和模板。
分析运行者承担分析的运行成本。
从模板运行分析¶
要从模板运行分析,请查看您可以运行的模板列表,查看您可以使用的数据产品列表,然后调用 COLLABORATION.RUN,将您的值作为单个参数或作为 YAML 格式的分析规范:
对数据启用并运行自由格式的 SQL 查询¶
数据提供商支持分析运行者对其协作数据产品运行 SQL 查询。您必须是协作的成员,并被授予分析运行者角色,对数据产品具有自由格式的 SQL 权限,能够对该数据运行自由格式的 SQL 查询。
数据提供商步骤¶
要支持协作者从命令行查询数据集,请在数据集描述中设置 allowed_analyses: template_and_freeform_sql。加入协作的用户可以对他们可访问的数据集运行自由格式的 SQL 查询。
以下 YAML 定义数据集,允许自由格式的查询:
分析运行者步骤¶
要查看哪些数据集支持自由格式查询,在加入协作后,分析运行者会运行
COLLABORATION.VIEW_DATA_OFFERINGS。结果中的 FREEFORM_SQL_VIEW_NAME 列显示可以使用自由格式 SQL 访问的表以及要在 SQL 查询中使用的表名称。然后,协作者可以使用自由格式的 SQL 查询来查询 FREEFORM_SQL_VIEW_NAME 列:
强制实施应用于表的所有策略。
使用 Standard Edition 时,使用自己的数据运行分析¶
如果您使用 Standard Edition,则可以 以标准方式 运行分析。但是,您无法将数据添加到协作描述并与其他用户共享。
要以 Standard Edition 用户身份在协作中使用自己的数据,请执行以下操作:
要注册数据产品,请调用
REGISTRY.REGISTER_DATA_OFFERING。您必须指定列名称。调用
COLLABORATION.LINK_LOCAL_DATA_OFFERING。在调用
COLLABORATION.VIEW_DATA_OFFERINGS时,只有您可以看到您的产品;其他协作者不会看到您列出的数据源。如果传入分析 YAML,则在调用
COLLABORATION.RUN时,请在local_template_view_names参数或local_view_mappings.my_tables字段中使用数据产品 ID。local_template_view_names和local_view_mappings.my_tables填充模板中的my_table参数。
以下示例展示了如何使用运行过程的 YAML 格式版本。此示例包括 my_tables 字段,该字段通过调用 LINK_LOCAL_DATA_OFFERING 填充。
激活查询结果¶
备注
如果您没有使用 SAMOOHA_APP_ROLE 角色,也就是说,您正在使用由 访问管理过程 管理的角色,则您必须拥有 REGISTER DATA OFFERING 权限,才能您作为分析运行者的任何协作,并且协作规范包括 activation_destinations 字段。
激活查询结果:
确保所有激活列在相应规范中设置了以下属性:
对于具有已激活列的表,数据产品规范 必须为该列设置
activation_allowed: TRUE:协作规范 必须为分析运行者提供
activation_destinations值。数据产品规范将激活限制为指定的分析运行者和模板。分析规范 必须包括带有
snowflake_collaborator和segment_name值的activation部分,并调用 激活模板,遵循 自定义模板的协作准则。您无法通过运行标准分析模板来激活结果。备注
模板已应用
activation_policy筛选器的任何列都必须在数据产品规范中将activation_allowed值设置为 TRUE。以下示例显示了一个模板,该模板已将激活策略应用于分析运行者提供的两列:分析运行者调用
RUN以运行分析。如果自行激活,结果将立即在表
consumers_database.ACTIVATION_RESULTS.CONSUMER_DIRECT_ACTIVATION_SUMMARY中的调用方账户中提供。要了解如何查看查询结果,请参阅最后一步。如果激活至其他协作者:
协作者调用
VIEW_ACTIVATIONS,直到它返回状态 SHARED。对于大型结果集,激活至其他账户可能需要相当长的时间,因为数据必须传输到协作者的账户并解密。当激活状态为 SHARED 时,协作者调用
PROCESS_ACTIVATION,将结果发送到他们的账户。对PROCESS_ACTIVATION的响应包括表和段名称。这会将激活状态设置为 PROCESSED。
要检索查询结果,请运行以下命令 SQL 命令,提供结果表名称和(可选)用于筛选结果的段名称:
退出或删除协作¶
非所有者通过调用
COLLABORATION.LEAVE来退出协作。他们提供的任何数据产品都将从协作中移除。退出协作后,您无法重新加入协作。协作所有者无法退出协作;所有权无法转让。协作所有者可以通过调用
COLLABORATION.TEARDOWN,为所有协作者删除协作。
这两个过程都是异步过程。您必须调用 GET_STATUS 以监控状态,并在 GET_STATUS 将状态显示为 LOCAL_DROP_PENDING 时,再次调用 LEAVE 或 TEARDOWN。
启用 Cross-Cloud Auto-Fulfillment¶
如果您与协作所有者不在同一云托管区域,则必须为您的账户启用 Cross-Cloud Auto-Fulfillment (LAF),您才能加入协作。如果您尝试在另一个云区域中查看协作,并且未为您的账户启用 LAF,或者您没有适当的权限,您在对协作调用 REVIEW 时会收到错误。
备注
在协作中使用 Cross-Cloud Auto-Fulfillment 时:
数据将复制到可访问该数据的每个协作者的账户。
数据也会复制到所有者所在的区域,无论他们是否可以访问数据产品。但是,他们访问数据的能力由数据产品的共享规则决定。
您可以通过运行 SELECT CURRENT_REGION(); 来确定您自己的云区域
在账户中启用 Cross-Cloud Auto-Fulfillment:
组织管理员必须调用 SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT,对您的账户启用 LAF。有关更多信息,请参阅 管理自动履行权限。
要有适当的权限来查看或加入 LAF 协作,请使用 SAMOOHA_APP_ROLE,或使用被授予 MANAGE LISTING AUTO FULFILLMENT 账户级权限 的角色。
由于 复制频率,位于不同云托管区域的协作者将遇到一些额外的数据滞后。在 Collaboration Data Clean Room 中,复制频率尚不可配置。
示例:双方协作¶
以下示例演示双方协作,其中一方(名为“alice”)是协作创建者、她自己和 bob 的数据提供商以及分析运行者。另一方(名为“bob”)是他自己和 alice 的数据提供商,也是分析运行者。
该示例演示以下操作:
创建协作。
注册模板和数据产品。
在协作创建时添加模板和数据产品。
加入协作。
向现有协作添加模板和资源。
运行分析。
要运行此示例,您必须拥有两个已安装 Snowflake Data Clean Rooms 的不同账户。
您可以下载文件并将其上传到您的 Snowflake 账户,也可以使用 Snowsight 将示例代码复制并粘贴到两个单独账户的工作表中。