Collaboration Data Clean Roomsスキーマリファレンス¶

コラボレーション仕様¶

高レベルのコラボレーションを定義します。仕様では、どの分析実行者が招待されるか、各分析実行者について、どのデータとテンプレートにアクセスして実行できるかを定義します。ここにリストされているテンプレートやデータサービスについては、コラボレーション仕様に配置する前に登録する必要があります。

所有者は 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

使用するコラボレーション API のバージョン。2.0.0 である必要があります。

spec_type

仕様タイプ識別子。collaboration である必要があります。

name: collaboration_name

このコラボレーションのユーザーにわかりやすい名前。作成者のアカウントで一意であり、:doc:`Snowflake識別子ルール </sql-reference/identifiers-syntax>`（最大75文字）に従うようにする必要があります。

``version``（オプション）

このコラボレーションのバージョン識別子（最大20文字）。Snowflake識別子ルール に従う必要があります。使用に適した形式は*YYYY_MM_DD_V#*です。例: 2025_10_22_V1。

:samp:`description: {collaboration_description}`（オプション）

コラボレーターが読むための、コラボレーションに関する人間が読める説明（最大1,000文字）。

:samp:`owner: {owner_alias}`（オプション）

コラボレーション所有者のエイリアスまたは データ共有アカウント識別子。指定されていない場合は、この仕様を登録するアカウントが所有者として割り当てられます。

collaborator_identifier_aliases

コラボレーターのエイリアスの データ共有アカウント識別子 へのマッピング。コラボレーションに参加できるのは、ここにリストされているユーザーのみです。データ共有アカウントの識別子を直接使用するのではなく、ここで定義されたエイリアスを使用してすべてのコラボレーターを参照します。

analysis_runners

このコラボレーションで分析を実行できる人について説明します。各分析実行者に対して、一意のエイリアスによってキーが設定されます。少なくとも1つのアカウントがこのコラボレーションで分析を実行できるようにする必要があります。

<analysis_runner_alias>

このコラボレーションで分析を実行できるアカウントのエイリアス。エイリアスは collaborator_identifier_aliases リストで定義されています。

data_providers

この分析実行者がアクセスできるデータのデータプロバイダー。各プロバイダーに対して、collaborator_identifier_aliases で定義されているエイリアスによってキーが設定されます。

data_offerings

分析実行者がアクセスできるこのデータプロバイダーのデータ提供のリスト、または空の配列 []。アイテムが存在する場合、各アイテムには次のプロパティが設定されています。

• data_offering_id:データプロバイダーが``REGISTRY.REGISTER_DATA_OFFERING`` を呼び出すときに生成されるこのデータ提供用の参照 ID。

``templates``（オプション）

この分析実行者が使用できるテンプレート。各テンプレートはその ID によって参照されます。

``activation_destinations``（オプション）

分析結果のアクティベーション設定を定義します。

``snowflake_collaborators``（オプション）

アクティブ化された分析結果を受信できるコラボレーターのリスト。この仕様の collaborator_identifier_aliases リストにあるエイリアスを使用します。ここにリストされているすべてのコラボレーターは、クエリ結果のアクティブ化 に記載されている権限を付与されている必要があります。

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

使用するコラボレーション API のバージョン。2.0.0 である必要があります。

spec_type

仕様タイプ識別子。data_offering である必要があります。

version

このデータ提供仕様のカスタムバージョン識別子（最大20文字）。Snowflake識別子ルール に従う必要があります。バージョン文字列には、VIEW_DATA_OFFERINGS および VIEW_REGISTERED_DATA_OFFERINGS への応答で独自の列が指定されます。したがって、値を増やすことでソートできる値を使用します。例: V0

name: data_offering_name

コラボレーターに公開するテーブルと列のセットの名前。この名前は、コラボレーション定義のデータ提供参照値として使用されます。異なるユースケースのために、テーブルと列が重複する複数のデータ提供機能を作成できます。最大75文字で、Snowflakeデータクリーンルームアカウント内で一意である Snowflake識別子ルール に従う必要があります。name_version ペアは、このアカウントのすべてのデータ提供に対して一意である必要があります。

:samp:`description: {data_offering_description}`（オプション）

データ提供の説明（最大1,000文字）。

datasets

コラボレーションで利用できるようにする1つ以上のデータセットのリスト。

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 :ref:` は、分析実行者に公開される列名を決定します <label-dcr_source_column_renaming>`。次の値がサポートされています。

• 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。元の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 です。

``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

使用するコラボレーション API のバージョン。2.0.0 である必要があります。

spec_type

仕様タイプ識別子。template である必要があります。

name

このテンプレートの一意でユーザーにわかりやすい名前。最大75文字の Snowflake識別子ルール に従う必要があります。name_version ペアが、このアカウントのすべてのテンプレートで一意であることが必要です。

version

このテンプレートのバージョン識別子（最大20文字）。Snowflake識別子ルール に従う必要があります。バージョン文字列には、VIEW_TEMPLATES および VIEW_REGISTERED_TEMPLATES への応答で独自の列が指定されます。したがって、値を増やすことでソートできる値を使用します。例: V0

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: 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

使用するコラボレーション API のバージョン。2.0.0 である必要があります。

spec_type

仕様タイプ識別子。analysis である必要があります。

template: template_name

テンプレート YAML で定義されている、この分析に使用するテンプレートの ID。最大75文字の Snowflake識別子ルール に従う必要があります。

``name``（オプション）

この分析の一意でユーザーにわかりやすい名前。最大75文字で、Snowflakeデータクリーンルームアカウント内で一意である Snowflake識別子ルール に従う必要があります。

``version``（オプション）

この分析仕様のバージョン識別子（最大20文字）。Snowflake識別子ルール に従い、この分析名のアカウント内で一意であることが必要です。使用に適した形式は*YYYY_MM_DD_V#*です。例: 2025_10_22_V1。

``description``（オプション）

この分析によって行われる内容についての概略的な説明（最大1,000文字）。

``template_configuration``（オプション）

指定したテンプレートを実行するときに使用される値。

``view_mappings``（オプション）

共有されているデータ提供機能の引数名からテンプレートビュー名へのマッピング。

``source_tables``（オプション）

source_table テンプレート変数を入力するテーブル名のリスト。データ提供仕様で指定されたテーブルのエイリアスを使用します。COLLABORATION.VIEW_DATA_OFFERINGS を呼び出すと、使用可能なテーブルのリストを取得できます。各エントリの形式は、collaborator alias.data offering ID.dataset alias です。

argument_name: view_name

引数名からテンプレートビュー名へのカスタムマッピング（それぞれ最大255文字）。

``local_view_mappings``（オプション）

プライベートデータセットのローカルテンプレートビュー名への引数名のマッピング。

``my_tables``（オプション）

my_table テンプレート変数を入力するテーブル名のリスト。これは LINK_LOCAL_DATA_OFFERING を呼び出すことでリンクしたプライベートデータセットでのみ利用できます。各エントリの形式は、collaborator alias.data offering ID.dataset alias です。

argument_name: view_name

引数名からローカルテンプレートビュー名へのカスタムマッピング（それぞれ最大255文字）。

``arguments``（オプション）

キーと値のペアとしてのテンプレート引数。引数の値は、テンプレートの要件に応じて、文字列、数値、ブール値、配列、またはオブジェクトのいずれかです。

``activation``（アクティベーションテンプレートに必須）

アクティベーションテンプレートを実行する際に必須のアクティベーション固有の構成。

snowflake_collaborator

アクティベーション先のコラボレーターのエイリアス（最大25文字）。コラボレーション仕様の collaborator_identifier_aliases セクションで定義されているエイリアスと一致するとともに、コラボレーターが activation_destinations セクションにリストされている必要があります。

segment_name

このアクティベーションの一意のセグメント名（最大255文字）。アクティベーション結果の識別と追跡に使用されます。Snowflake識別子ルール に従う必要があります。