사용자 지정 템플릿 디자인¶

Clean Room 템플릿 정보¶

클린룸 템플릿은 JinjaSQL 로 작성됩니다. JinjaSQL 은 Jinja 템플릿 언어의 확장 프로그램입니다. JinjaSQL 템플릿은 클린룸에서 실행할 때 SQL 문으로 평가됩니다. JinjaSQL 템플릿 언어는 논리 문과 런타임 변수 대체를 제공하여 런타임 시 템플릿을 사용자 지정할 수 있습니다. 예를 들어, 사용자는 템플릿을 실행할 때 테이블 및 열 이름을 제공할 수 있으며 템플릿은 전달된 값에 따라 자체적으로 조정할 수 있습니다.

템플릿에는 일반적으로 두 가지 유형이 있습니다.

분석 템플릿: 쿼리 결과를 템플릿 실행기에 즉시 반환하는 SQL DQL 문(SELECT 문)으로 평가됩니다.
활성화 템플릿: 결과를 즉각적인 환경에 표시하지 않고 Snowflake 계정에 활성화하는 데 사용됩니다. 활성화 템플릿은 몇 가지 추가 요구 사항 이 포함된 분석 템플릿과 매우 유사하며 DDL 문(CREATE TABLE)으로 평가됩니다.

사용자 지정 템플릿 구문¶

Snowflake Data Clean Rooms는 V3 JinjaSQL 을 지원하며, 몇 가지 확장 프로그램이 있습니다.

이 섹션에는 다음 항목이 포함되어 있습니다.

템플릿 명명 규칙¶

템플릿을 생성할 때 이름에는 문자, 숫자 또는 밑줄만 포함해야 합니다. 템플릿 이름은 템플릿을 등록할 때 템플릿 사양의 name 필드에 할당됩니다.

유효한 이름의 예:

my_template
activation_template_1

유효하지 않은 이름의 예:

my template - 허용되지 않는 공백
my_template! - 특수 문자는 허용되지 않음

템플릿 변수¶

템플릿 호출자는 템플릿 변수에 값을 전달할 수 있습니다. JinjaSQL 구문을 사용하면 {{ double_brackets }} 내의 모든 변수 이름에 대해 변수 바인딩을 사용할 수 있지만, 아래에 설명된 대로 재정의해서는 안 되는 몇 가지 변수 이름이 Snowflake에 예약되어 있습니다.

조심

모든 변수는 Snowflake 정의이든 사용자 지정이든 사용자가 채우므로 적절한 주의를 기울여 다루어야 합니다. 분석 템플릿은 단일 SELECT 문(활성화 템플릿은 스크립트 블록으로 해석됨)으로 해석되어야 합니다. 모든 변수는 호출자가 전달한다는 점을 기억해야 합니다.

Snowflake 정의 변수¶

모든 클린룸 템플릿은 Snowflake에 의해 정의되지만 분석 실행자가 전달한 다음 전역 변수에 액세스할 수 있습니다.

source_table:

템플릿에서 사용할 수 있는 LINK_DATA_OFFERING을 통해 공동 작업에 연결된 데이터 오퍼링의 테이블 및 뷰로 구성된 0부터 시작하는 문자열 배열입니다.

예: SELECT col1 FROM IDENTIFIER({{ source_table[0] }}) AS p;

my_table:

공동 작업 클린룸에서``my_table`` 은 Snowflake Standard Edition 사용자만 사용합니다. 이러한 사용자의 경우, my_table 은 분석 실행자가 LINK_LOCAL_DATA_OFFERING을 호출하여 연결한 데이터 세트의 0부터 시작하는 문자열 배열입니다.

예: SELECT col1 FROM IDENTIFIER({{ my_table[0] }}) AS c;

사용자 지정 변수¶

템플릿 생성자는 분석 실행자가 채울 수 있는 임의의 변수를 템플릿에 포함할 수 있습니다. 이러한 변수는 Snowflake 정의 변수 또는 테이블 별칭 이름을 제외하고 모든 Jinja 호환 이름을 포함할 수 있습니다. 필수 및 선택적 변수에 대한 지침은 템플릿의 매개 변수 섹션에서 제공해야 합니다.

사용자 지정 변수는 템플릿에서 액세스할 수 있습니다(예: 사용자 지정 변수 max_income).

SELECT income FROM my_db.my_sch.customers WHERE income < {{ max_income }};

분석 실행자는 분석 실행 사양 에 정의된 대로 RUN을 호출할 때 변수를 전달합니다.

변수를 올바르게 해결하기¶

템플릿에 전달된 문자열 값은 최종 템플릿에서 문자열 리터럴로 해석됩니다. 바인딩된 변수를 적절하게 처리하지 않으면 SQL 구문 분석 또는 논리적 오류가 발생할 수 있습니다.

SELECT {{ my_col }} FROM p; - SELECT 'my_col' from p; 로 해석되며, 이는 단순히 문자열 “my_col”을 반환합니다. 원하는 결과가 아닐 수 있습니다.
SELECT age FROM {{ source_table[0] }} AS p; - ``SELECT age FROM ‘somedb.somesch.source_table’ AS p;``로 해석되며, 테이블은 리터럴 문자열이 아닌 식별자여야 하므로 이로 인해 구문 분석 오류가 발생합니다.
SELECT age FROM IDENTIFIER({{ source_table[0] }}) AS p {{ where_clause }}; - “WHERE age < 50”을 전달하면 SELECT age FROM mytable AS p 'WHERE age < 50'; 으로 평가되며, 이는 리터럴 문자열 WHERE 절로 인한 구문 분석 오류입니다.

따라서 적절한 경우 변수를 해결해야 합니다. 템플릿에서 변수를 올바르게 해결하는 방법은 다음과 같습니다.

테이블 및 열 이름 확인하기

테이블 또는 열 이름을 지정하는 변수는 템플릿에서 두 가지 방법 중 하나를 사용하여 식별자로 변환해야 합니다.

IDENTIFIER: For example: SELECT IDENTIFIER({{ my_column }}) FROM p;
sqlsafe: 이 JinjaSQL 필터는 식별자 문자열을 SQL 텍스트로 해석합니다. 이전 글머리 기호에 해당하는 문은 SELECT {{ my_column | sqlsafe }} FROM p; 입니다.

특정 사용법에 따라 IDENTIFIER 또는 sqlsafe 를 사용해야 하는 시기가 결정됩니다. 예를 들어 p.{{ my_column | sqlsafe }} 는 IDENTIFIER를 사용하여 쉽게 재작성할 수 없습니다.

동적 SQL 확인하기

WHERE 절과 같이 리터럴 SQL 로 사용해야 하는 문자열 변수가 있는 경우 템플릿에서 sqlsafe 필터를 사용하십시오. 예:

SELECT age FROM IDENTIFIER({{ source_table[0] }}) AS p WHERE {{ where_clause }};

사용자가 “age < 50”을 where_clause 에 전달하면 쿼리는 리터럴 문자열 WHERE 조건 때문에 유효하지 않은 SQL인 SELECT age FROM sometable AS p WHERE 'age < 50'; 으로 해석됩니다. 이 경우 sqlsafe 필터를 사용해야 합니다.

SELECT age FROM IDENTIFIER( {{ source_table[0] }} ) as p {{ where_clause | sqlsafe }};

필수 테이블 별칭¶

Snowflake가 쿼리에서 조인 및 열 정책의 유효성을 올바르게 검사하기 위해 쿼리의 최상위 수준에서 모든 source_table 데이터 세트는 p 로 별칭을 지정하고 모든 my_table 데이터 세트는 c 로 별칭을 지정해야 합니다. 조인 또는 열 정책에 대해 확인해야 하는 모든 열은 소문자 나 p 또는 c 테이블 별칭으로 정규화되어야 합니다.

쿼리에 여러 source_table 또는 my_table 데이터 세트를 사용하는 경우 첫 번째 테이블 별칭 뒤에 숫자 1을 기준으로 순차적으로 접미사를 추가합니다. 그래서 첫 번째, 두 번째, 세 번째 source_table 데이터 세트의 경우 p, p1, p2, p3 등이고 첫 번째, 두 번째, 세 번째 my_table 데이터 세트의 경우 c, c1, c2, c3 등이 됩니다. p 또는 c 인덱스는 간격 없이 순차적이어야 합니다(즉, p1, p2, p4 가 아닌 p1, p2, p3 이라는 별칭을 생성해야 함).

예

SELECT p1.col1 FROM IDENTIFIER({{ source_table[0] }}) AS p1
UNION
SELECT p2.col1 FROM IDENTIFIER({{ source_table[1] }}) AS p2;

사용자 지정 클린룸 템플릿 필터¶

Snowflake는 모든 표준 Jinja 필터 및 대부분의 표준 JinjaSQL 필터 를 몇 가지 확장 프로그램과 함께 지원합니다.

join_policy:: 열이 데이터 소유자의 조인 정책에 있는 경우 성공합니다. 그렇지 않으면 실패합니다. 데이터 오퍼링에 데이터 보호 정책 적용하기 섹션을 참조하세요.
column_policy:: 열이 데이터 소유자의 열 정책에 있는 경우 성공합니다. 그렇지 않으면 실패합니다. 데이터 오퍼링에 데이터 보호 정책 적용하기 섹션을 참조하세요.
activation_policy:: 열이 데이터 소유자의 활성화 정책에 있는 경우 성공합니다. 그렇지 않으면 실패합니다. 데이터 오퍼링에 데이터 보호 정책 적용하기 섹션을 참조하세요.
join_and_column_policy:: 열이 데이터 소유자의 조인 또는 열 정책에 있는 경우 성공합니다. 그렇지 않으면 실패합니다. 데이터 오퍼링에 데이터 보호 정책 적용하기 섹션을 참조하세요.
identifier:: Snowflake 템플릿에서는 JinjaSQL 필터가 지원되지 않습니다.

팁

JinjaSQL 문은 왼쪽에서 오른쪽으로 평가됩니다.

{{ my_col | column_policy }} 정답
{{ my_col | sqlsafe | column_policy }} 정답
{{ column_policy | my_col }} 오답
{{ my_col | column_policy | sqlsafe }} 잘못됨: column_policy 는 문자열로 my_col 값과 비교되며, 이는 오류입니다.

Clean Room 정책 적용하기¶

클린룸은 템플릿에 사용된 열에 대해 클린룸 정책을 자동으로 확인하지 않습니다. 열에 대해 정책을 강제 적용하려면 다음을 수행합니다.

템플릿의 해당 열에 적절한 :ref:`정책 필터<label-dcr_template_filters>`를 적용해야 합니다. 예를 들면 다음과 같습니다.

FROM IDENTIFIER({{ source_table[0] }}) AS p1
JOIN IDENTIFIER({{ source_table[1] }}) AS p2
  ON IDENTIFIER({{ p1_join_col | join_policy }}) = IDENTIFIER({{ p2_join_col | join_policy }})

테이블의 별칭을 소문자 p 또는 c 로 지정해야 합니다. 필수 테이블 별칭 섹션을 참조하세요.

정책은 source_table 변수에서 참조되는 테이블의 열에 대해서만 확인되며, 이는 클린룸 내에서 공유되는 뷰를 참조합니다. 클린룸 내에서 공유되지 않는 로컬 테이블인 my_table 변수에서 참조되는 테이블의 열에 대해서는 정책이 확인되지 않습니다.

정책을 테스트할 때는 열 이름이 모호해서는 안 된다는 점에 유의하세요. 따라서 두 테이블에 같은 이름의 열이 있는 경우 해당 열에 대해 정책을 테스트하려면 열 이름을 한정해야 합니다.

액세스 고려 사항 및 모범 사례¶

템플릿은 항상 클린룸 애플리케이션 역할에 대한 컨텍스트에서 실행됩니다. 공동 작업자는 템플릿 액세스로만 제한된 클린룸 내의 어떤 데이터에도 직접 액세스할 수 없습니다. 모든 액세스는 네이티브 애플리케이션 역할과 템플릿 출력을 통해 이루어집니다.

클린룸에서 생성하거나 사용하는 템플릿에 대해 아래의 사항을 따르는 것이 모범 사례입니다.

템플릿에서 열 변수가 사용될 때마다 정책 필터가 적용되어 공동 작업자 정책이 준수되도록 합니다.
SQL 주입 공격에 대해 템플릿을 강화하기 위해 가능한 경우 IDENTIFIER()로 사용자 제공 변수를 래핑합니다.

활성화 템플릿¶

템플릿을 사용하여 쿼리 결과를 클린룸 외부의 테이블에 저장할 수도 있습니다. 이를 활성화 라고 합니다. 활성화 템플릿은 다음과 같은 추가 요구 사항이 있는 분석 템플릿입니다.

활성화 템플릿은 단순한 SELECT 문일 수 있는 분석 템플릿과 달리 SQL 스크립트 블록으로 평가되는 JinjaSQL 문입니다.
활성화 템플릿은 결과를 저장하기 위해 클린룸에 내부 테이블을 생성해야 합니다. 템플릿에서 생성된 테이블에는 cleanroom.activation_data_ 접두사가 있어야 합니다(예: cleanroom.activation_data_my_results).
내부 결과 테이블의 모든 열에는 데이터 오퍼링 사양의 activation_allowed: TRUE 값이 있어야 합니다.
스크립트 블록은 cleanroom.activation_data_ 접두사 없이 생성된 테이블의 이름을 반환하는 RETURN 문으로 끝나야 합니다(예: RETURN 'my_results').
템플릿 자체에는 명명 요구 사항이 없습니다.

다음은 활성화 템플릿 사양의 예제입니다.

api_version: 2.0.0
spec_type: template
name: my_activation_template
version: v0
type: sql_activation
description: Activation template that creates segment data
template: |
  BEGIN
      CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
      SELECT
          {{ group_by_column | sqlsafe }} AS bucket_label,
          {{ activation_column | sqlsafe | activation_policy }} AS activation_label,
          COUNT(DISTINCT {{ join_column | sqlsafe }}) AS overlap_count
      FROM IDENTIFIER({{ source_table[0] }}) AS p
      GROUP BY {{ group_by_column | sqlsafe }},
               {{ activation_column | sqlsafe }};
      RETURN 'analysis_results';
  END;
parameters:
  - name: join_column
    description: Join column name
    required: true
    default: "p.IP_ADDRESS"
  - name: group_by_column
    description: Group by column name
    required: true
    default: "p.CAMPAIGN_NAME"
  - name: activation_column
    description: Activation column name
    required: true
    default: "p.DEVICE_TYPE"

클린룸에서 활성화를 구현하는 방법을 알아보세요. 쿼리 결과 활성화하기

다음 단계¶

템플릿 시스템을 마스터한 후에는 템플릿 유형으로 Clean Room을 구현하기 위한 세부 사항을 읽어보십시오.

활성화 템플릿 은 성공적인 실행 후 결과 테이블을 생성하고 클린룸 외부에서 공유됩니다. 공동 작업 사양에 따라 결과 테이블을 분석 실행자 또는 다른 공동 작업자와 공유할 수 있습니다.
코드 번들 은 사용자 지정 Python UDFs 및 UDTFs를 공동 작업으로 업로드하는 데 사용됩니다. 협업의 템플릿은 이러한 함수를 실행하여 복잡한 데이터 작업을 수행할 수 있습니다.
내부 테이블 은 중간 또는 영구 결과를 저장하는 데 사용되며, 이는 다단계 워크플로를 지원하기 위해 다운스트림에 사용할 수 있습니다. 이러한 테이블은 클린룸 내부의 템플릿 또는 사용자 지정 업로드 코드에 액세스할 수 있습니다.

사용자 지정 템플릿 디자인¶

Clean Room 템플릿 정보¶

사용자 지정 템플릿 생성, 공유, 실행하기¶

1. JinjaSQL 템플릿¶

2. 공동 작업 템플릿¶

3. 템플릿 실행하기¶

사용자 지정 템플릿 개발¶

데이터 보호¶

사용자 지정 템플릿 구문¶

템플릿 명명 규칙¶

템플릿 변수¶

Snowflake 정의 변수¶

사용자 지정 변수¶

변수를 올바르게 해결하기¶

필수 테이블 별칭¶

사용자 지정 클린룸 템플릿 필터¶

Clean Room 정책 적용하기¶

액세스 고려 사항 및 모범 사례¶

활성화 템플릿¶

다음 단계¶

자세한 정보¶