템플릿 스펙(Template specification)

콜라보레이션의 단일 템플릿을 정의해요. 템플릿은 템플릿 스펙과 함께 REGISTER_TEMPLATE를 호출해 등록해요.

출처: Template specification

본문

기능 — 일반 공개(Generally Available)

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

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

콜라보레이션의 단일 템플릿을 정의해요. 템플릿은 템플릿 스펙과 함께 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

code_specs:             # Optional: List of code specs used by this template
  - <code_spec_id>        # One or more code spec IDs.

preset_tables:                  # Optional: Datasets preset by the template author
  - alias: <dataset_alias>      # One or more preset tables...
    template_view_name: <collaborator_alias>.<data_offering_ID>.<dataset_alias>

template: |                     # Required: JinjaSQL template content
  <template_content>

api_version — 사용된 Collaboration API 버전이에요. 2.0.0이어야 해요.
spec_type — 스펙 유형 식별자예요. template이어야 해요.
name: template_name — 이 템플릿의 고유하고 사용자 친화적인 이름이에요. Snowflake 식별자 규칙을 따르고 최대 75자예요. name/version 쌍은 이 계정의 모든 템플릿에서 고유해야 해요.
version: version_string — 이 템플릿의 버전 식별자예요(최대 20자). Snowflake 식별자 규칙을 따라야 해요. 버전 문자열은 VIEW_TEMPLATES와 VIEW_REGISTERED_TEMPLATES 응답에 고유한 컬럼으로 주어지므로, 증가하는 값으로 정렬할 수 있는 값을 사용하세요. 예: V0.
type — 템플릿 유형이에요. 다음 값 중 하나예요:
- sql_analysis: 데이터 분석 작업용 템플릿이에요.
- sql_activation: 데이터 활성화 작업용 템플릿이에요.
description: template_description(선택) — 이 템플릿이 무엇을 하는지에 대한 높은 수준의 설명이에요(최대 1,000자).
methodology: methodology_description(선택) — 이 템플릿이 어떻게 작동하는지에 대한 더 자세한 설명이에요(최대 1,000자).
parameters(선택) — 이 템플릿의 모든 사용자 제공 파라미터 목록이에요. 각 항목은 다음 필드를 가질 수 있어요:
- name: 유효한 Snowflake 식별자로서의 파라미터 이름, 최대 255자.
- description(선택): 파라미터의 사람이 읽을 수 있는 설명(최대 500자).
- required(선택): 파라미터 필수 여부. 기본값은 false.
- default(선택): 파라미터의 기본값. 어떤 데이터 유형이든 될 수 있어요.
- type(선택): 파라미터의 예상 데이터 유형. string, integer, number, boolean, array, object 중 하나.
code_specs(선택) — 이 템플릿이 참조하는 함수를 정의하는 하나 이상의 코드 스펙이에요. 템플릿이 커스텀 함수를 호출할 때 필요해요. 코드 스펙 ID는 버전 관리되며, 함수의 새 버전에 접근하려면 여기서 코드 스펙 ID를 업데이트해야 해요. 템플릿 자체(비버전 함수 이름을 호출하는 곳)는 업데이트할 필요가 없어요. 코드 스펙 이름에는 밑줄이 있어야 하고 정규식 패턴 [A-Za-z]\w{0,74}_\w{1,20}과 일치해야 해요.
preset_tables(선택) — 미리보기 기능 — 공개: 모든 계정에서 사용할 수 있어요. 템플릿 작성자가 프리셋한 데이터셋이에요. 분석 실행자는 템플릿을 실행할 때 이 데이터셋을 전달하지 않아요. 분석 실행자가 공급하기로 선택한 데이터셋이 아니라 템플릿이 항상 특정 데이터셋을 읽어야 할 때 preset_tables를 사용하세요. 자세한 내용은 프리셋 테이블을 참고하세요. 각 항목은 다음 필드를 가져요:
- alias: 템플릿 본문에서 {{ preset_tables['alias'] }}로 이 데이터셋을 참조하는 데 사용되는 이름이에요. 최대 255자의 유효한 Snowflake 식별자여야 하고 템플릿 안에서 고유해야 해요. 그런 다음 템플릿 본문에서 이 데이터셋에 부여하는 SQL 별칭은 p, c, 또는 숫자가 뒤따르는 p나 c가 될 수 없어요. 그 별칭들은 source_table과 my_table 데이터셋용으로 예약되어 있거든요.
- template_view_name: 프리셋 테이블로, 형식은 collaborator_alias.data_offering_ID.dataset_alias예요. VIEW_DATA_OFFERINGS가 반환한 TEMPLATE_VIEW_NAME 컬럼의 값을 사용하세요.
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 }};

게시자 데이터셋을 고정(pin)하고 광고주 데이터셋은 분석 실행자에게서 받는 템플릿:

api_version: 2.0.0
spec_type: template
name: preset_overlap_template
version: V1
type: sql_analysis
description: Overlap count against a fixed publisher audience.
methodology: Joins the preset publisher audience to a runner-supplied table on hashed email.

parameters:
  - name: source_tables
    description: The advertiser table to compare against the publisher audience
    required: true

preset_tables:
  - alias: publisher
    template_view_name: pub.pub_audience_v2.AUDIENCE

template: |
    SELECT COUNT(DISTINCT publisher.hashed_email) AS overlap_count
    FROM IDENTIFIER({{ preset_tables['publisher'] }}) AS publisher
    INNER JOIN IDENTIFIER({{ source_table[0] }}) AS p1
    ON publisher.hashed_email = p1.hashed_email;

템플릿 스펙(Template specification)

템플릿 스펙(Template specification)

본문

예시

더 알아보기