Collaboration Data Clean Rooms 스키마 참조¶
이 항목에서는 모든 공동 작업 리소스에 대한 사양 스키마에 대해 설명합니다. 사양은 YAML 형식으로 표시됩니다.
사양에는 api_version 스키마 버전 필드가 있습니다. 여기에 표시된 API 버전 번호를 사용하세요. 이전 스키마 버전에 대한 지원은 보장되지 않습니다.
현재 DCR Collaboration 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)
version: <version_string> # Optional: Version identifier (max 20 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.0여야 합니다.spec_type사양 유형 식별자입니다.
collaboration여야 합니다.name: collaboration_name이 공동 작업에 사용할 사용자 친화적인 이름입니다. 이는 생성자의 계정에서 고유해야 하며 :doc:`Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`(최대 75자)을 따라야 합니다.
- ``version``(선택 사항)
이 공동 작업의 버전 식별자입니다(최대 20자). Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 합니다. *YYYY_MM_DD_V#* 형식을 사용하는 것이 좋습니다. 예를 들어 ``2025_10_22_V1` 과 같습니다.
- :samp:`description: {collaboration_description}`(선택 사항)
공동 작업자가 읽을 수 있는 공동 작업에 대한 설명입니다(최대 1,000자).
- :samp:`owner: {owner_alias}`(선택 사항)
공동 작업 소유자의 별칭 또는 :ref:`데이터 공유 계정 식별자 <label-account_name_data_sharing>`입니다. 지정하지 않으면 이 사양을 등록하는 계정이 소유자로 할당됩니다.
collaborator_identifier_aliases공동 작업자 별칭과 데이터 공유 계정 식별자 간의 매핑입니다. 여기에 나열된 사용자만 공동 작업에 참여할 수 있습니다. 모든 공동 작업자를 참조하려면 데이터 공유 계정 식별자를 직접 사용하는 대신 여기에 정의된 별칭을 사용합니다.
analysis_runners이 공동 작업에서 분석을 실행할 수 있는 사용자를 설명합니다. 각 분석 실행자는 고유한 별칭으로 키가 지정됩니다. 이 공동 작업에서 분석을 실행하려면 하나 이상의 계정을 허용해야 합니다.
<analysis_runner_alias>이 공동 작업에서 분석을 실행할 수 있는 계정의 별칭입니다. 별칭은
collaborator_identifier_aliases목록에 정의되어 있습니다.data_providers이 분석 실행자가 액세스할 수 있는 데이터의 데이터 공급자입니다. 각 공급자는 ``collaborator_identifier_aliases``에 정의된 별칭으로 키가 지정됩니다.
- ``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
데이터 오퍼링 사양¶
공급자가 분석 실행자와 공유하려는 테이블 세트 및 정책, 열 형식, 테이블을 템플릿과 함께 사용해야 하는지 여부와 같은 공유 규칙을 정의합니다.
데이터 공급자는 공동 작업 정의에서 사용할 수 있는 오퍼링 ID를 반환하는 ``REGISTRY.REGISTER_DATA_OFFERING``을 호출하여 이 정의를 제출합니다.
데이터 오퍼링을 등록한 계정이 공동 작업에 참여할 때까지는 공동 작업에서 데이터 오퍼링을 사용할 수 없습니다.
데이터를 활성화할 수 있는 모든 공동 작업에 참여하려면 REGISTER DATA OFFERING 계정 권한(즉, 분석 실행자이고 공동 작업 사양에 activation_destinations 필드가 포함되어 있음)이 있어야 합니다. 자세한 내용은 :ref:`액세스 관리 API 참조 가이드 <label-dcr_collaboration_access_management_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.0여야 합니다.spec_type사양 유형 식별자입니다.
data_offering여야 합니다.version이 데이터 오퍼링 사양의 사용자 지정 버전 식별자(최대 20자)입니다. Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 합니다. ``VIEW_DATA_OFFERINGS` 및
VIEW_REGISTERED_DATA_OFFERINGS``에 대한 응답에서 버전 문자열에 별도의 열이 제공되므로 오름차순으로 정렬할 수 있는 값을 사용합니다. 예: ``V0name: data_offering_name공동 작업자에게 노출할 테이블 및 열 세트의 이름입니다. 이 이름은 공동 작업 정의에서 데이터 오퍼링 참조 값으로 사용됩니다. 다양한 사용 사례에 대해 겹치는 테이블과 열이 있는 여러 데이터 오퍼링을 생성할 수 있습니다. Snowflake 식별자 규칙</sql-reference/identifiers-syntax>`(최대 75자)을 따라야 하며, Snowflake 데이터 클린룸 계정 내에서 고유해야 합니다. :samp:`{name}_{version} 쌍은 이 계정의 모든 데이터 오퍼링에 대해 고유해야 합니다.
- :samp:`description: {data_offering_description}`(선택 사항)
데이터 오퍼링에 대한 설명입니다(최대 1,000자).
datasets공동 작업에 사용할 수 있는 하나 이상의 데이터 세트 목록입니다.
alias: dataset_name:code:`collaboration.run`에서 사용되는 이 데이터 오브젝트의 이름입니다. :doc:`Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 하며, 이 오퍼링 내에서 고유해야 합니다.
data_object_fqn: fully_qualified_table_name공동 작업자가 사용할 수 있는 단일 테이블을 설명합니다. 계정에 있는 소스 오브젝트의 정규화된 이름을 입력합니다(
database.schema.table_name). 최대 길이는 773자입니다.allowed_analyses: allowed_analysis_type공동 작업자가 이 테이블에 대해 실행할 수 있는 분석 유형입니다. 다음 값이 있는 필수 필드입니다.
template_only: 분석 실행자는 공동 작업 정의에 나열된 템플릿을 사용해야만 이 테이블을 쿼리할 수 있습니다.template_and_freeform_sql: 분석 실행자는 공동 작업 정의에 나열된 템플릿을 사용하거나 코드 환경에서 :ref:`자유 형식 SQL 쿼리<label-dcr_collab_enable_free_form_queries>`를 사용하여 이 테이블을 쿼리할 수 있습니다.
- ``object_class``(선택 사항)
오브젝트의 유형입니다. 다음 값 중 하나입니다.
ads_log: 여기에 나열된 테이블과 열은 광고 로그 요구 사항을 충족해야 합니다.custom: 특별한 요구 사항이 없는 사용자 지정 테이블 및 열 세트입니다.
schema_and_template_policies``data_object_fqn``으로 나열된 테이블의 열 이름 목록을 제공하고 각 열의 정책과 형식을 정의합니다. 공동 작업자는 여기에 나열된 열만 사용할 수 있습니다. 각 열에는 다음과 같은 설명자가 있습니다.
category: category_type카테고리에 따라 열 이름 바꾸기가 적용되는지 여부와 적용해야 하는 데이터 형식이 결정됩니다.
category및 ``column_type``에 따라 :ref:`분석 실행자에 노출되는 열 이름이 결정 <label-dcr_source_column_renaming>`됩니다. 다음 값이 지원됩니다.join_standard:column_type필드에 지정된 형식의 데이터가 있는 조인 가능한 열입니다. 이 열의 이름은 공유 데이터 오퍼링에서column_type값으로 바뀝니다.join_custom: 모든 형식의 조인 가능한 열입니다. 조인 열에 대해 적절한 ``column_type``이 없는 경우 사용합니다. 원래 열 이름은 공유 데이터 오퍼링에서 사용됩니다.timestamp: 모든 이벤트의 타임스탬프를 지정하는 프로젝션 가능한 열입니다. 이 열의 이름은 공유 데이터 오퍼링에서 ``timestamp``로 바뀝니다.passthrough: 다른 유형의 프로젝션 가능한 열입니다. 원래 열 이름은 공유 데이터 오퍼링에서 사용됩니다.
- ``column_type: <format_type>``(ategory=join_standard인 경우 필수, 다른 카테고리 유형의 경우 무시됨)
데이터 형식입니다. 데이터가 이 형식을 따르지 않는 경우
REGISTER_DATA_OFFERING호출이 실패합니다.category = join_standard``인 열에는 이 필드를 제공합니다. ``category및column_type``에 따라 :ref:`분석 실행자에 노출되는 열 이름이 결정 <label-dcr_source_column_renaming>`됩니다. 동일한 테이블에서 여러 열에 동일한 ``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입니다. 원래 ID는device_id형식이어야 합니다.hashed_device_b64_encoded: base64로 인코딩된 해시 디바이스 ID입니다.ip_address: IPv4 형식의 원시 IP 주소 입니다.hashed_ip_address_sha256: SHA256으로 해시된 IPv4 주소입니다. 원래 ID는ip_address형식이어야 합니다.hashed_ip_address_b64_encoded: base64로 인코딩된 해시 IP 주소입니다.
- ``activation_allowed``(선택 사항)
이 열을 활성화 목적으로 사용할 수 있는지 여부입니다. 기본값은
false입니다.
다음 타입이 지원됩니다.
- ``aggregation_policy``(선택 사항)
단일 집계 정책 구성입니다.
name: 정규화된 정책 이름입니다.``entity_keys``(선택 사항): 집계 정책의 엔터티 키로 사용되는 열 이름의 목록입니다.
- ``join_policy``(선택 사항)
단일 조인 정책 구성입니다.
name: 정규화된 정책 이름입니다.``columns``(선택 사항): 이 정책이 적용되는 열 이름의 목록입니다.
- ``masking_policies``(선택 사항)
마스킹 정책 구성의 배열입니다.
name: 정규화된 정책 이름입니다.``columns``(선택 사항): 이 정책이 적용되는 열 이름의 목록입니다.
- ``projection_policies``(선택 사항)
프로젝션 정책 구성의 배열입니다.
name: 정규화된 정책 이름입니다.``columns``(선택 사항): 이 정책이 적용되는 열 이름의 목록입니다.
- ``row_access_policy``(선택 사항)
행 액세스 정책 구성의 배열입니다.
name: 정규화된 정책 이름입니다.``columns``(선택 사항): 이 정책이 적용되는 열 이름의 목록입니다.
템플릿 리소스 사양¶
공동 작업에서 사용할 단일 템플릿을 정의합니다. 공동 작업에서 사용할 템플릿을 등록하려면 ``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.0여야 합니다.spec_type사양 유형 식별자입니다.
template여야 합니다.name이 템플릿의 고유한 사용자 친화적인 이름입니다. Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`(최대 75자)을 따라야 합니다. :samp:`{name}_{version} 쌍은 이 계정의 모든 템플릿에 대해 고유해야 합니다.
version이 템플릿의 버전 식별자입니다(최대 20자). Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 합니다. ``VIEW_TEMPLATES` 및
VIEW_REGISTERED_TEMPLATES``에 대한 응답에서 버전 문자열에 별도의 열이 제공되므로 오름차순으로 정렬할 수 있는 값을 사용합니다. 예: ``V0type템플릿 유형입니다. 다음 값 중 하나입니다.
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 템플릿 </user-guide/cleanrooms/custom-templates>`이 포함됩니다. 자세한 내용은 :ref:`label-dcr_design_collaboration_template 섹션을 참조하십시오.
템플릿에 노출되는 열 이름은 데이터 오퍼링 정의<label-dcr_collaboration_data_yaml>`에 명시된 열의 ``category` 및
column_type값에 의해 결정됩니다. 자세한 내용은 소스 열 이름 바꾸기 섹션을 참조하십시오.
예:
api_version: 2.0.0
spec_type: template
name: trivial_template
version: 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. Populates the source_table array variable.
- <source_table_name> # One or more source table names...
<argument_name>: <view_name> # Custom argument to template view name mapping
local_view_mappings: # Optional: Mappings for local data
my_tables: # Optional: Tables from local data offerings. Populates the my_table array variable.
- <my_table_name> # One or more local table names...
<argument_name>: <view_name> # Custom argument to local template view name mapping
arguments: # Optional: Template arguments as key-value pairs
<argument_name>: <argument_value> # One or more argument key-value pairs...
activation: # Required for activation templates
snowflake_collaborator: <alias> # Collaborator alias for activation destination
segment_name: <segment_name> # Unique segment name for this activation
api_version사용되는 Collaboration API의 버전입니다.
2.0.0여야 합니다.spec_type사양 유형 식별자입니다.
analysis여야 합니다.template: template_name:ref:`템플릿YAML<label-dcr_collaboration_template_yaml>`에 정의된 대로 이 분석에 사용할 템플릿의 ID입니다. :doc:`Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`(최대 75자)을 따라야 합니다.
- ``name``(선택 사항)
이 분석의 고유하고 사용자 친화적인 이름입니다. :doc:`Snowflake 식별자 규칙</sql-reference/identifiers-syntax>`(최대 75자)을 따라야 하며, Snowflake 데이터 클린룸 계정 내에서 고유해야 합니다.
- ``version``(선택 사항)
이 분석 사양의 버전 식별자입니다(최대 20자). Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 하며, 계정 내의 분석 이름에 대해 고유해야 합니다. *YYYY_MM_DD_V#* 형식을 사용하는 것이 좋습니다. 예를 들어 ``2025_10_22_V1` 과 같습니다.
- ``description``(선택 사항)
이 분석이 수행하는 작업에 대한 간략한 설명입니다(최대 1,000자).
- ``template_configuration``(선택 사항)
지정된 템플릿을 실행할 때 사용되는 값입니다.
- ``view_mappings``(선택 사항)
공유 데이터 오퍼링에 대한 인자 이름 및 템플릿 뷰 이름 간의 매핑입니다.
- ``source_tables``(선택 사항)
source_table템플릿 변수를 채울 테이블 이름의 목록입니다. 데이터 오퍼링 사양에 지정된 테이블 별칭을 사용합니다. ``COLLABORATION.VIEW_DATA_OFFERINGS``를 호출하여 사용 가능한 테이블 목록을 가져올 수 있습니다. 각 항목의 형식은 :samp:`{collaborator alias}.{data offering ID}.{dataset alias}`입니다.argument_name: view_name인자 이름 및 템플릿 뷰 이름 간의 사용자 지정 매핑입니다(각각 최대 255자)
- ``local_view_mappings``(선택 사항)
비공개 데이터 세트에 대한 인자 이름 및 로컬 템플릿 뷰 이름 간의 매핑입니다.
- ``arguments``(선택 사항)
키-값 페어 형식의 템플릿 인자입니다. 인자 값은 템플릿 요구 사항에 따라 문자열, 숫자, 부울, 배열 또는 오브젝트일 수 있습니다.
- ``activation``(활성화 템플릿에 필요)
활성화 템플릿을 실행할 때 필요한 활성화별 구성입니다.
snowflake_collaborator활성화 대상의 공동 작업자 별칭입니다(최대 25자). 공동 작업 사양의
collaborator_identifier_aliases섹션에 정의된 별칭과 일치해야 하며, 공동 작업자가activation_destinations섹션에 나열되어 있어야 합니다.segment_name이 활성화의 고유 세그먼트 이름입니다(최대 255자). 활성화 결과를 식별하고 추적하는 데 사용됩니다. :doc:`Snowflake 식별자 규칙 </sql-reference/identifiers-syntax>`을 따라야 합니다.