데이터 오퍼링 스펙(Data offering specification)

제공자가 분석 실행자와 공유할 의향이 있는 테이블 집합과, 정책·컬럼 형식·템플릿 사용 여부 같은 공유 규칙을 정의해요.

출처: Data offering specification

본문

기능 — 일반 공개(Generally Available)

현재 지원 리전: 이 리전들에서 사용할 수 있어요.

정부 및 VPS 배포에서는 사용할 수 없어요.

제공자가 분석 실행자와 공유할 의향이 있는 테이블 집합과, 정책(policies), 컬럼 형식, 테이블을 템플릿과 함께 사용해야 하는지 같은 공유 규칙을 정의해요.

데이터 제공자는 REGISTER_DATA_OFFERING을 호출해 이 스펙을 제출해요. 이 호출은 콜라보레이션 스펙에서 사용할 수 있는 오퍼링 ID를 반환해요.

데이터 오퍼링을 등록한 계정이 콜라보레이션에 참여하기 전까지 그 데이터 오퍼링은 콜라보레이션에서 사용할 수 없어요.

데이터를 활성화할 수 있는 콜라보레이션(즉, 분석 실행자이고 콜라보레이션 스펙에 activation_destinations 필드가 있는 경우)에 참여하려면 REGISTER DATA OFFERING 계정 권한이 있어야 해요. 자세한 내용은 접근 관리 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, passthrough, or event_type
        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 POSSIBLY RENAMED 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 POSSIBLY RENAMED 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 POSSIBLY RENAMED 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 POSSIBLY RENAMED column names...
      row_access_policy:        # Optional: Row access policy
        name: <fully_qualified_policy_name>
        columns:              # Optional: Columns this policy applies to
          - <column_name>     # One or more POSSIBLY RENAMED 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이어야 해요.
name: data_offering_name — 콜라보레이터에게 노출할 테이블과 컬럼 집합의 이름이에요. 이 이름은 콜라보레이션 스펙에서 데이터 오퍼링 참조 값으로 사용돼요. 다양한 사용 사례를 위해 겹치는 테이블과 컬럼으로 여러 데이터 오퍼링을 만들 수 있어요. Snowflake 식별자 규칙을 따르고 최대 75자이며, Snowflake 데이터 클린룸 계정 안에서 고유해야 해요. name/version 쌍은 이 계정의 모든 데이터 오퍼링에서 고유해야 해요.
version — 이 데이터 오퍼링 스펙의 커스텀 버전 식별자예요(최대 20자). Snowflake 식별자 규칙을 따라야 해요. 버전 문자열은 VIEW_DATA_OFFERINGS와 VIEW_REGISTERED_DATA_OFFERINGS 응답에 고유한 컬럼으로 주어지므로, 증가하는 값으로 정렬할 수 있는 값을 사용하세요. 예: V0.
description: data_offering_description(선택) — 데이터 오퍼링 설명이에요(최대 1,000자).
datasets — 콜라보레이션에서 사용할 수 있게 할 하나 이상의 데이터셋 목록이에요.
alias: dataset_name — 이 데이터 객체의 이름으로, collaboration.run에서 사용돼요. Snowflake 식별자 규칙을 따르고 이 오퍼링 안에서 고유해야 해요. 최대 75자.
data_object_fqn: fully_qualified_table_name — 콜라보레이터에게 제공되는 단일 테이블을 설명해요. 계정에 있는 소스 객체의 전체 이름(database.schema.object_name)이에요. 최대 길이는 773자예요. 지원되는 객체 유형은 지원 객체 유형을 참고하세요.
allowed_analyses: allowed_analysis_type — 콜라보레이터가 이 테이블에 대해 실행할 수 있는 분석 유형이에요. 필수 필드이며 값은 다음과 같아요:
- template_only: 분석 실행자는 콜라보레이션 스펙에 나열된 템플릿으로만 이 테이블을 쿼리할 수 있어요.
- template_and_freeform_sql: 분석 실행자는 콜라보레이션 스펙에 나열된 템플릿을 사용하거나, 코드 환경에서 자유 형식 SQL 쿼리를 사용해 이 테이블을 쿼리할 수 있어요.
object_class(선택) — 객체 유형이에요. 다음 값 중 하나예요:
- ads_log: 여기에 나열된 테이블과 컬럼은 광고 로그(ad 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: 다른 유형의 프로젝션 가능한 컬럼이에요. 공유 데이터 오퍼링에서 원본 컬럼 이름이 사용돼요.
  - event_type: 이 행에 대한 이벤트 유형 분류를 기록하는 프로젝션 가능한 컬럼이에요. 예: "purchase(구매)", "sign-up(가입)", "impression(노출)", "click(클릭)" 등.
- 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나 CTV 기기 ID 같은 원본 기기 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 주소.
  - first_name: 원본 이름(first name).
  - hashed_first_name_sha256: SHA256 해시된 이름. 원본은 first_name 형식이어야 해요.
  - hashed_first_name_b64_encoded: base64 인코딩된 해시 이름.
  - last_name: 원본 성(last name).
  - hashed_last_name_sha256: SHA256 해시된 성. 원본은 last_name 형식이어야 해요.
  - hashed_last_name_b64_encoded: base64 인코딩된 해시 성.
- activation_allowed(선택) — 이 컬럼을 활성화 용도로 사용할 수 있는지 여부예요. 기본값은 false예요.
freeform_sql_policies(선택) — allowed_analyses가 template_and_freeform_sql이면, 이 선택 필드는 이 데이터 오퍼링에 대해 실행되는 자유 형식 SQL 쿼리에 적용해야 하는 Snowflake 정책을 나열해요. 자세한 내용은 데이터 오퍼링에 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 쿼리를 지원하는 데이터 소스를 링크하는 것을 막는 안전장치로 사용돼요.

데이터 오퍼링 스펙(Data offering specification)

데이터 오퍼링 스펙(Data offering specification)

본문

더 알아보기