Collaboration Data Clean Room 架构参考¶
本主题介绍所有协作资源的规范架构。规范以 YAML 格式显示。
规范具有架构版本字段 api_version。使用此处显示的 API 版本号；不保证支持早期的架构版本。
当前 DCR 协作 API 版本： 2.0.0
协作规范¶
定义高级别协作。该规范定义了邀请哪些分析运行者，以及针对每个分析运行者，他们可以访问和运行哪些数据及模板。此处列出的任何模板或数据产品都必须先注册，然后才能包含在协作规范中。
所有者通过调用 COLLABORATION.INITIALIZE 提交此定义。
架构：
api_version: 2.0.0 # Required: Must be "2.0.0"
spec_type: collaboration # Required: Must be "collaboration"
name: <collaboration_name> # Required: Unique name (max 75 chars)
description: <collaboration_description> # Optional: Description (max 1,000 chars)
owner: <owner_alias> # Optional: Alias of owner
collaborator_identifier_aliases: # Required: Map aliases to account identifiers
<alias_1>: <account_identifier_1> # One or more alias mappings...
analysis_runners: # Required: Who can run analyses
<analysis_runner_alias>: # One or more analysis runner definitions...
data_providers: # Required: Data providers for this runner
<provider_alias>: # One or more provider definitions...
data_offerings: # Required: List of offerings (can be empty [])
- id: <data_offering_id> # Zero or more data offering IDs...
templates: # Optional: Templates this runner can use
- id: <template_id> # One or more template IDs...
activation_destinations: # Optional: Where results can be sent
snowflake_collaborators: # Optional: Collaborators who can receive results
- <collaborator_alias> # One or more collaborator aliases...
api_version所使用的 Collaboration API 的版本。必须是
2.0.0spec_type规范类型标识符。必须是
collaborationname: collaboration_name此协作的用户友好名称。在创建者的账户中必须是唯一的，并遵循 :doc:`Snowflake 标识符规则 </sql-reference/identifiers-syntax>`（最多 75 个字符）。
- :samp:`description: {collaboration_description}`（可选）
人类可读的协作描述（最多 1,000 个字符），供协作者阅读。
- :samp:`owner: {owner_alias}`（可选）
协作所有者的别名或 数据共享账户标识符。如果未指定，则注册此规范的账户将被指定为所有者。
collaborator_identifier_aliases协作者别名到其 数据共享账户标识符 的映射。只有此处列出的用户才能参与协作。使用此处定义的别名来引用所有协作者，而不是直接使用其数据共享账户标识符。
analysis_runners描述谁可以在此协作中运行分析。每个分析运行者均由唯一的别名作为键。您必须允许至少一个账户在此协作中运行分析。
<analysis_runner_alias>可以在此协作中运行分析的账户别名。别名定义在
collaborator_identifier_aliases列表中。data_providers此分析运行者可以访问其数据的数据提供商。每个提供商均由在
collaborator_identifier_aliases中定义的别名作为键。data_offerings分析运行者可以访问的来自此数据提供商的数据产品列表，或一个空数组
[]。如果存在项目，则每个项目都具有以下属性：data_offering_id：选择使用 时默认使用的角色和仓库。此数据产品的参考 ID，在数据提供商调用REGISTRY.REGISTER_DATA_OFFERING时生成。
- ``templates``（可选）
此分析运行者可以使用的模板。每个模板均通过其 ID 进行引用。
- ``activation_destinations``（可选）
定义分析结果的激活设置。
示例¶
api_version: 2.0.0
spec_type: collaboration
name: my_sample_collaboration
owner: Owner
collaborator_identifier_aliases:
Owner: ENG.OWNER
AnalysisRunner_1: ENG.CONSUMER_1
DataProvider_1: ENG.PROVIDER_1
DataProvider_2: ENG.PROVIDER_2
AnalysisRunner_2: ENG.PROVIDER_3
analysis_runners:
AnalysisRunner_1:
data_providers:
DataProvider_1:
data_offerings:
- id: DCR_PREPROD_CI_PROVIDER_ANY_NAME_ZUDFTMULHQ_iuDfn_v0
DataProvider_2:
data_offerings: []
templates:
- id: test_sca_three_party_template_JOaVG_v0
AnalysisRunner_2:
data_providers:
DataProvider_2:
data_offerings: []
templates:
- id: test_sca_three_party_template_JOaVG_v0
数据产品规范¶
定义提供商愿意与分析运行者共享的一组表，以及共享规则（例如策略、列格式以及表是否必须配合模板使用）。
数据提供商通过调用 REGISTRY.REGISTER_DATA_OFFERING 提交此定义，这将返回一个可在协作定义中使用的产品 ID。
在注册数据产品的账户加入协作之前，该数据产品在协作中不可用。
您必须拥有 REGISTER DATA OFFERING 账户权限才能加入任何可以激活数据的协作；即，您是分析运行者且协作规范包含 activation_destinations 字段。有关更多信息，请参阅 访问管理 API 参考指南。
架构：
api_version: 2.0.0 # Required: Must be "2.0.0"
spec_type: data_offering # Required: Must be "data_offering"
name: <data_offering_name> # Required: Unique name (max 75 chars)
version: <version_string> # Required: Version identifier (max 20 chars)
description: <data_offering_description> # Optional: Description (max 1,000 chars)
datasets: # Required: Tables to share
- alias: <dataset_name> # One or more dataset items...
data_object_fqn: <database.schema.table_name> # Required: Fully-qualified table name
allowed_analyses: <allowed_analysis_type> # Required: template_only or template_and_freeform_sql
object_class: <object_class> # Optional: ads_log or custom
schema_and_template_policies: # Required: Column definitions
<column_name>: # One or more column definitions...
category: <category_type> # Required: join_standard, join_custom, timestamp, or passthrough
column_type: <format_type> # Required for join_standard category, omitted for other categories.
activation_allowed: <true_or_false> # Optional: Whether column can be used for activation
freeform_sql_policies: # Optional: Policies for freeform SQL queries
aggregation_policy: # Optional: Single aggregation policy
name: <fully_qualified_policy_name>
entity_keys: # Optional: Entity key columns
- <column_name> # One or more column names...
join_policy: # Optional: Single join policy
name: <fully_qualified_policy_name>
columns: # Optional: Columns this policy applies to
- <column_name> # One or more column names...
masking_policies: # Optional: Masking policies
- name: <fully_qualified_policy_name> # One or more masking policy items...
columns: # Optional: Columns this policy applies to
- <column_name> # One or more column names...
projection_policies: # Optional: Projection policies
- name: <fully_qualified_policy_name> # One or more projection policy items...
columns: # Optional: Columns this policy applies to
- <column_name> # One or more column names...
row_access_policy: # Optional: Row access policies
- name: <fully_qualified_policy_name> # One or more row access policy items...
columns: # Optional: Columns this policy applies to
- <column_name> # One or more column names...
require_freeform_sql_policy: <true_or_false> # Optional: Require a policy for freeform SQL
api_version所使用的 Collaboration API 的版本。必须是
2.0.0spec_type规范类型标识符。必须是
data_offeringversion此数据产品规范的自定义版本标识符（最多 20 个字符）。必须遵循 Snowflake 标识符规则。一个推荐的版本控制方案是 YYYY_MM_DD_V#。例如：
2025_06_21_V1。name: data_offering_name要向协作者公开的一组表和列的名称。此名称用作协作定义中的数据产品参考值。您可以针对不同的用例，创建包含重叠表和列的多个数据产品。必须遵循 Snowflake 标识符规则，长度最多 75 个字符，并且在您的 Snowflake Data Clean Room 账户中是唯一的。
name_version对在此账户的所有数据产品中必须是唯一的。- :samp:`description: {data_offering_description}`（可选）
数据产品的描述（最多 1,000 个字符）。
datasets可供协作使用的一个或多个数据集的列表。
alias: dataset_name此数据对象的名称，用于
collaboration.run。必须遵循 Snowflake 标识符规则 并在此产品中保持唯一。data_object_fqn: fully_qualified_table_name描述可供协作者使用的单个表。提供账户中源对象的完全限定名称 (
database.schema.table_name)。最大长度为 773 个字符。allowed_analyses: allowed_analysis_type协作者可以针对此表运行的分析类型。必填字段，具有以下值：
template_only：选择使用 时默认使用的角色和仓库。分析运行者只能使用协作定义中列出的模板来查询此表。template_and_freeform_sql：选择使用 时默认使用的角色和仓库。分析运行者可以使用协作定义中列出的模板查询此表，或者在代码环境中使用 自由格式 SQL 查询。
- ``object_class``（可选）
对象类型。以下值之一：
ads_log：选择使用 时默认使用的角色和仓库。此处列出的表和列必须符合广告日志要求。custom：选择使用 时默认使用的角色和仓库。一组没有特殊要求的自定义表和列。
schema_and_template_policies提供由
data_object_fqn列出的表中的列名列表，并定义每列的策略和格式。只有此处列出的列可供协作者使用。每列具有以下描述符：category: category_type类别决定了是否应用列重命名，以及应应用哪些数据格式强制执行。
category和column_type决定了向分析运行者公开的列名。支持以下值：join_standard：选择使用 时默认使用的角色和仓库。这是一个可联接列，其数据采用column_type字段中指定的格式。此列在共享数据产品中被重命名为column_type值。join_custom：选择使用 时默认使用的角色和仓库。这是任何格式的可联接列。当联接列没有合适的column_type时，请使用此项。在共享数据产品中使用原始列名。timestamp：选择使用 时默认使用的角色和仓库。这是一个可投影列，用于指定任何事件的时间戳。该列在共享数据产品中重命名为timestamp。passthrough：选择使用 时默认使用的角色和仓库。这是任何其他类型的可投影列。在共享数据产品中使用原始列名。
- ``column_type: <format_type>``（当 category=join_standard 时必填，其他类别类型则忽略）
数据的格式。如果数据不符合此格式，则您对
REGISTER_DATA_OFFERING的调用将失败。为符合category = join_standard的列提供此字段。category和column_type决定了向分析运行者公开的列名。您不能为同一个表中的多个列分配相同的column_type值。支持以下格式类型：email：选择使用 时默认使用的角色和仓库。原始电子邮件地址。hashed_email_sha256：选择使用 时默认使用的角色和仓库。经 SHA256 哈希处理的电子邮件。hashed_email_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希电子邮件。phone：选择使用 时默认使用的角色和仓库。不带标点符号的电话号码。例如：2015551212。hashed_phone_sha256：选择使用 时默认使用的角色和仓库。经 SHA256 哈希处理的电话号码。原始号码应采用phone格式。hashed_phone_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希电话号码。device_id：选择使用 时默认使用的角色和仓库。原始设备 ID，例如移动广告 ID 或 CTV 设备 ID。hashed_device_id_sha256：经 SHA256 哈希处理的设备 ID。原文应采用device_id格式。hashed_device_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希设备 ID。ip_address：选择使用 时默认使用的角色和仓库。采用 IPv4 格式的原始 IP 地址。hashed_ip_address_sha256：经 SHA256 哈希处理的 IPv4 地址。原文应采用ip_address格式。hashed_ip_address_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希 IP 地址。
- ``activation_allowed``（可选）
此列是否可用于激活目的。默认值为
false。
- ``freeform_sql_policies``（可选）
如果
allowed_analyses为template_and_freeform_sql，则此可选字段列出了在此数据产品上运行的 SQL 自由格式查询中应应用的任何 Snowflake 策略。有关更多信息，请参阅 在数据产品上应用策略（仅限自由格式查询使用）。
支持以下类型：
- ``aggregation_policy``（可选）
单个 聚合策略 配置。
name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。``entity_keys``（可选）：用作聚合策略实体键的列名列表。
- ``join_policy``（可选）
单个 联接策略 配置。
name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。``columns``（可选）：此策略适用的列名列表。
- ``masking_policies``（可选）
掩码策略 配置数组。
name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。``columns``（可选）：此策略适用的列名列表。
- ``projection_policies``（可选）
投影策略 配置数组。
name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。``columns``（可选）：此策略适用的列名列表。
- ``row_access_policy``（可选）
行访问策略 配置数组。
name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。``columns``（可选）：此策略适用的列名列表。
- ``require_freeform_sql_policy``（可选）
此数据源是否必须定义
freeform_sql_policies。这用作故障保护，以防止在未分配策略的情况下添加支持自由格式 SQL 查询的数据源。
模板资源规范¶
定义协作中的单个模板。发送至 REGISTRY.REGISTER_TEMPLATE 以注册要在协作中使用的模板。
架构：
api_version: 2.0.0 # Required: Must be "2.0.0"
spec_type: template # Required: Must be "template"
name: <template_name> # Required: Unique name (max 75 chars)
version: <version_string> # Required: Version identifier (max 20 chars)
type: <template_type> # Required: sql_analysis or sql_activation
description: <template_description> # Optional: High-level description (max 1,000 chars)
methodology: <methodology_description> # Optional: Detailed description (max 1,000 chars)
parameters: # Optional: User-provided parameters
- name: <parameter_name> # One or more parameter items...
description: <parameter_description> # Optional: Description (max 500 chars)
required: <true_or_false> # Optional: Whether required (default: false)
default: <default_value> # Optional: Default value
type: <data_type> # Optional: String, integer, number, Boolean, array, or object
template: | # Required: JinjaSQL template content
<template_content>
api_version所使用的 Collaboration API 的版本。必须是
2.0.0spec_type规范类型标识符。必须是
templatename: template_name此模板的唯一且用户友好名称。必须遵循 Snowflake 标识符规则，最多 75 个字符。
name_version对在此账户的所有模板中必须是唯一的。version: version_string此模板的版本标识符（最多 20 个字符）。必须遵循 Snowflake 标识符规则。推荐使用的格式是 YYYY_MM_DD_V#。例如：
2025_10_22_V1。type模板类型。以下值之一：
sql_analysis：选择使用 时默认使用的角色和仓库。数据分析操作模板。sql_activation：选择使用 时默认使用的角色和仓库。数据激活操作模板。
- :samp:`description: {template_description}`（可选）
对此模板功能的简要描述（最多 1,000 个字符）。
- :samp:`methodology: {methodology_description}`（可选）
关于此模板工作原理的更详细说明（最多 1,000 个字符）。
- ``parameters``（可选）
此模板中所有用户提供的参数列表。每个项目可以具有以下字段：
name：选择使用 时默认使用的角色和仓库。作为有效 Snowflake 标识符 的参数名称。``description``（可选）：人类可读的参数描述（最多 500 个字符）。
``required``（可选）：参数是否必填。默认值为
false。``default``（可选）：参数默认值，可以是任何数据类型。
``type``（可选）：参数的预期数据类型。以下之一：
string、integer、number、boolean、array或object。
template模板内容。对于 SQL 模板，这包含 JinjaSQL 模板。有关更多信息，请参阅 协作的模板设计。
向模板公开的列名由 数据产品定义 中该列的
category和column_type值决定。有关更多信息，请参阅 源列重命名。
示例：
api_version: 2.0.0
spec_type: template
name: trivial_template
version: 2025_01_01_v1
type: sql_analysis
description: Simple one-row template.
methodology: Always returns "1". Requires one source table.
parameters:
- name: row_count
description: Count of rows
required: true
template: |
SELECT 1 FROM IDENTIFIER( {{ source_table[0] }} ) LIMIT {{ row_count }};
分析请求规范¶
指定分析运行者运行分析所需的所有信息，包括要使用的模板、要传递给模板的表以及模板使用的任何变量值。如果不使用自由格式 SQL 查询数据，任何想要运行分析的分析运行者都会使用此规范来定义模板和输入数据。
架构：
api_version: 2.0.0 # Required: Must be "2.0.0"
spec_type: analysis # Required: Must be "analysis"
template: <template_id> # Required: ID of the template to use
name: <analysis_name> # Optional: Unique name (max 75 chars)
version: <version_string> # Optional: Version identifier (max 20 chars)
description: <analysis_description> # Optional: Description (max 1,000 chars)
template_configuration: # Optional: Values used when running the template
view_mappings: # Optional: Mappings for shared data
source_tables: # Optional: Tables from data offerings
- <source_table_name> # One or more source table names...
local_view_mappings: # Optional: Mappings for local data
my_tables: # Optional: Tables from local data offerings
- <my_table_name> # One or more local table names...
arguments: # Optional: Template arguments as key-value pairs
<argument_name>: <argument_value> # One or more argument key-value pairs...
api_version所使用的 Collaboration API 的版本。必须是
2.0.0spec_type规范类型标识符。必须是
analysistemplate: template_name用于此分析的模板 ID，定义在 模板 YAML 中。必须遵循 Snowflake 标识符规则，最多 75 个字符。
- ``name``（可选）
此分析的唯一且用户友好名称。必须遵循 Snowflake 标识符规则，长度最多 75 个字符，并且在您的 Snowflake Data Clean Room 账户中是唯一的。
- ``version``（可选）
此分析规范的版本标识符（最多 20 个字符）。必须遵循 Snowflake 标识符规则，且在您的账户中针对此分析名称是唯一的。推荐使用的格式是 YYYY_MM_DD_V#。例如：
2025_10_22_V1。- ``description``（可选）
对此分析功能的简要描述（最多 1,000 个字符）。
- ``template_configuration``（可选）
运行指定模板时使用的值。
- ``source_tables``（可选）
用于填充
source_table模板变量的表名列表。使用数据产品规范中指定的表别名。您可以通过调用COLLABORATION.VIEW_DATA_OFFERINGS获取可用表的列表。每个条目的格式为collaborator alias.data offering ID.dataset alias。- ``my_tables``（可选）
用于填充
my_table模板变量的表名列表。这仅适用于通过调用LINK_LOCAL_DATA_OFFERING链接的私有数据集。每个条目的格式为collaborator alias.data offering ID.dataset alias。- ``arguments``（可选）
以键值对形式呈现的模板实参。实参值可以是字符串、数字、布尔值、数组或对象，具体取决于模板要求。在任何请求中使用以下实参：
collaborator_name：选择使用 时默认使用的角色和仓库。激活请求必填。将值设置为应接收已激活结果的协作者别名。此协作者必须列在协作规范的 activation_destinations 部分中。segment_name：选择使用 时默认使用的角色和仓库。激活请求必填。将值设置为任意段名称，以帮助接收者过滤结果。