사용자 지정 Clean Room 템플릿 만들기¶

데이터 보호¶

템플릿은 공급자와 컨슈머가 Clean Room에 연결한 데이터 세트에만 액세스할 수 있습니다.

공급자와 컨슈머 모두 데이터에 대한 조인, 열 및 활성화 정책을 설정하여 조인할 수 있는 열을 보호하고, 활성화된 결과 세트에 투영하거나 투영할 수 있는 열을 보호할 수 있는 기능이 있습니다.

간단한 예¶

다음은 이메일을 통해 공급자와 컨슈머 테이블을 조인하고 도시별 중복 수를 보여주는 간단한 SQL 예제입니다.

SELECT COUNT(*), city FROM consumer_table
  INNER JOIN provider_table
  ON consumer_table.hashed_email = provider_table.hashed_email
  GROUP BY city;

다음은 호출자가 선택/그룹화 및 조인 열과 테이블을 선택할 수 있는 템플릿으로 쿼리가 표시되는 모습입니다.

SELECT COUNT(*), IDENTIFIER({{ group_by_col | column_policy }})
  FROM IDENTIFIER({{ my_table[0] }}) AS C
  INNER JOIN IDENTIFIER({{ source_table[0] }}) AS P
  ON IDENTIFIER({{ consumer_join_col | join_policy }}) = IDENTIFIER({{ provider_join_col | join_policy }})
  GROUP BY IDENTIFIER({{ group_by_col | column_policy }});

템플릿에 대한 참고 사항:

• {{ double bracket pairs }} 내의 값은 사용자 지정 변수입니다. group_by_col, my_table, source_table, consumer_join_col, provider_join_col, group_by_col 은 모두 호출자에 의해 채워지는 사용자 지정 변수입니다.

• source_table 과 my_table 은 호출자에 의해 채워지는 Snowflake 정의 문자열 배열 변수입니다. 배열 멤버는 Clean Room에 연결된 공급자 및 컨슈머 테이블의 정규화된 이름입니다. 호출자는 각 배열에 포함할 테이블을 지정합니다.

• 템플릿에서 공급자 테이블은 P, 컨슈머 테이블은 C 로 별칭을 지정해야 합니다. 테이블이 여러 개 있는 경우 P1, P2, C1, C2 등으로 인덱싱할 수 있습니다.

• {{ double brackets }} 의 변수는 유효한 식별자가 아닌 문자열 리터럴로 평가되므로 모든 열 및 테이블 이름에 IDENTIFIER 가 필요합니다.

• JinjaSQL 필터 를 변수에 적용할 수 있습니다. Snowflake는 각각 Clean Room에서 열이 조인 또는 열 정책을 준수하는지 여부를 확인하고 준수하지 않는 경우 쿼리를 실패시키는 사용자 지정 필터 join_policy 및 column_policy 를 구현합니다. 필터가 열 이름에 {{ column_name | filter_name }} 으로 적용됩니다.

이 모든 사항은 나중에 자세히 설명하겠습니다.

컨슈머가 이 템플릿을 코드에서 실행하는 방법은 다음과 같습니다. 템플릿에 선언된 테이블 별칭으로 열 이름이 한정되는 방식에 유의하십시오.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.RUN_ANALYSIS(
  $cleanroom_name,
  $template_name,
  ['my_db.my_sch.consumer_table],       -- Populates the my_table variable
  ['my_db.my_sch.provider_table'],      -- Populates the source_table variable
  OBJECT_CONSTRUCT(                     -- Populates custom named variables
    'consumer_join_col','c.age_band',
    'provider_join_col','p.age_band',
    'group_by_col','p.device_type'
  )
);

웹 애플리케이션에서 이 템플릿을 사용하려면 공급자가 템플릿에 대한 사용자 지정 UI 양식을 만들어야 합니다. UI 양식에는 템플릿 변수 이름에 해당하는 양식 요소가 명명되어 있으며 양식에 제공된 값은 템플릿으로 전달됩니다.

템플릿 명명 규칙¶

템플릿을 만들 때 이름은 모두 소문자, 숫자, 공백 또는 밑줄을 사용해야 합니다. 활성화 템플릿(컨슈머 실행 공급자 활성화는 예외)의 이름은 “activation”으로 시작해야 합니다. 템플릿 이름은 provider.add_custom_sql_template 또는 consumer.create_template_request 를 호출할 때 지정됩니다.

유효한 이름의 예:

• my_template

• activation_template_1

유효하지 않은 이름의 예:

• my template - 허용되지 않는 공백

• My_Template - 소문자 템플릿만 허용됨

템플릿 변수¶

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

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

필수 테이블 별칭¶

쿼리의 최상위 수준에서 모든 테이블 또는 하위 쿼리의 별칭을 P (공급자 테이블의 경우) 또는 C (컨슈머 테이블의 경우)로 지정해야 Snowflake가 쿼리에서 조인 및 열 정책의 유효성을 올바르게 검사할 수 있습니다. 조인 또는 열 정책에 대해 확인해야 하는 모든 열은 P 또는 C 로 별칭이 지정된 테이블에 속합니다. (P 또는 C 를 지정하면 백엔드에 각각 공급자 또는 컨슈머 정책에 대해 열의 유효성을 검사할지 여부를 알려줍니다.)

쿼리에 여러 공급자 또는 컨슈머 테이블을 사용하는 경우 첫 번째 테이블 별칭 뒤에 숫자 1을 기준으로 순차적으로 접미사를 추가합니다. 그래서 첫 번째, 두 번째, 세 번째 공급자 테이블의 경우 P, P1, P2 등이고 첫 번째, 두 번째, 세 번째 컨슈머 테이블의 경우 C, C1, C2 등이 됩니다. P 또는 C 인덱스는 간격 없이 순차적이어야 합니다(즉, P, P2, P4 가 아닌 P, P1, P2 라는 별칭을 생성해야 함).

예

SELECT col1 FROM IDENTIFIER({{ source_table[0] }}) AS P;

템플릿 필터¶

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

• join_policy: 테이블의 조인 정책에서 열이 허용되는지 확인하고 허용되지 않으면 실패합니다.

• column_policy: 템플릿의 열 정책에 따라 열이 허용되는지 확인합니다(투영이 허용됨).

• activation_policy: 필터링된 열이 Clean Room의 활성화 정책(provider.set_activation_policy 또는 consumer.set_activation_policy)에 의해 허용되는지 확인합니다.

• join_and_column_policy: 조인, 활성화 또는 열 정책에 의해 열이 허용되는지 여부를 확인합니다. 공동 작업자가 템플릿을 변경하지 않고도 조인 및 열 정책을 업데이트할 수 있도록 Clean Room에서 더 많은 유연성을 제공하는 데 사용됩니다.

• Snowflake 템플릿에서는 identifier JinjaSQL 필터가 지원되지 않습니다.

JinjaSQL 필터를 왼쪽에서 오른쪽으로 분석합니다.

• {{ my_col | column_policy }} 정답

• {{ my_col | sqlsafe | column_policy }} 정답

• {{ column_policy | my_col }} 오답

• {{ my_col | column_policy | sqlsafe }} 오답

Clean Room 정책 적용하기¶

Clean Rooms는 템플릿에 사용된 열에 대해 Clean Room 정책을 자동으로 확인하지 않습니다. 열에 대해 정책을 적용하려면 템플릿의 해당 열에 적절한 정책 필터 를 적용해야 합니다. 예:

JOIN IDENTIFIER({{ source_table[0] }}) AS p
  ON {{ c_join_col | sqlsafe | join_policy }} = {{ p_join_col | sqlsafe }}

이렇게 하면 c_join_col 에 전달된 열에 대해 조인 정책을 테스트하지만 p_join_col 에 대해서는 테스트하지 않습니다.

정책을 테스트할 때는 다른 SQL 사용법과 마찬가지로 열 이름이 모호해서는 안 된다는 점에 유의하십시오. 따라서 두 테이블에 같은 이름의 열이 있는 경우 해당 열에 대해 정책을 테스트하려면 열 이름을 한정해야 합니다.

사용자 지정 Python 코드 실행하기¶

템플릿은 Clean Room에 업로드된 Python 코드를 실행할 수 있습니다. 템플릿은 데이터 행에서 값을 받아 쿼리에서 사용하거나 투영할 값을 반환하는 Python 함수를 호출할 수 있습니다.

• 공급자 가 사용자 지정 Python 코드를 Clean Room에 업로드하면 템플릿은 cleanroom.function_name 구문으로 Python 함수를 호출합니다. 자세한 내용은 여기를 참조하십시오.

• 컨슈머 가 사용자 지정 Python 코드를 Clean Room에 업로드하면 템플릿은 순수한 function_name 값을 consumer.generate_python_request_template 에 전달하여 함수를 호출합니다(공급자 코드처럼 Clean Room 에 대한 범위가 지정되지 않음). 자세한 내용은 여기를 참조하십시오.

공급자 코드 예시:

-- Provider uploads a Python function that takes two numbers and returns the sum.
call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
  $cleanroom_name,
  'simple_addition',                        -- Function name to use in the template
  ['someval integer', 'added_val integer'], -- Arguments
  [],                                       -- No packages needed
  'integer',                                -- Return type
  'main',                                   -- Handler for function name
  $$

def main(input, added_val):
  return input + int(added_val)
    $$
);

-- Template passes value from each row to the function, along with a
-- caller-supplied argument named 'increment'
call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    'simple_python_example',
$$
    SELECT val, cleanroom.simple_addition(val, {{ increment | sqlsafe }})
    FROM VALUES (5),(8),(12),(39) AS P(val);
$$
);