클린룸에 사용자 지정 템플릿 추가¶

공급자 작성 템플릿 추가¶

공급자는 provider.add_custom_sql_template 을 호출하고 템플릿 JinjaSQL 을 문자열로 전달하여 한 번에 하나씩 사용자 지정 템플릿을 추가합니다. 사용자 지정 템플릿은 클린룸의 템플릿 목록에 표시되며 Snowflake에서 제공하는 템플릿과 동일하게 동작합니다. 클린룸에는 사용자 지정 템플릿과 Snowflake에서 제공하는 템플릿을 함께 포함할 수 있습니다.

템플릿이 호출할 사용자 지정 Python UDFs 를 업로드할 수도 있습니다.

다음 예제에서는 공급자가 클린룸에 사용자 지정 템플릿을 추가하는 방법을 보여줍니다.

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $basic_template_name,
    $$
    SELECT
      COUNT(*) AS total_count
    FROM IDENTIFIER({{ my_table[0] }}) AS c
      INNER JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON IDENTIFIER({{ consumer_id | join_policy }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
    WHERE {{ where_clause | sqlsafe }}
    {% endif %};
  $$
);

이전 예제를 포함한 대부분의 템플릿에서 열 이름 충돌을 방지하려면 열 이름을 테이블 이름으로 정규화해야 합니다. 테이블 이름 접두사를 접두사의 열 이름에 연결하고 유효한 식별자를 가져오는 것은 쉽지 않기 때문입니다( IDENTIFIER(p.{{col_name | sqlsafe }}) 는 오류임). 따라서 호출자가 열 이름뿐만 아니라 정규화된 테이블 이름을 제공해야 할 수도 있습니다. 테이블 이름은 승인된 p 및 c 별칭을 사용해야 합니다.

공급자가 작성한 템플릿 실행¶

클린룸 API 사용 시 컨슈머는 ``consumer.run_analysis``를 호출하여 템플릿을 실행하고, 공급자는 ``provider.submit_analysis_request``를 호출하여 공급자 실행 분석 을 수행합니다.

클린룸 UI에서 템플릿을 실행할 수 있도록 하려면, 공급자는 템플릿에 대한 사용자 입력 양식을 만들어야 합니다. 공급자가 작성한 템플릿만 클린룸 UI에서 실행할 수 있습니다.

공급자가 템플릿을 난독 처리 한 경우가 아니면, 클린룸 공동 작업자는 consumer.view_template_definition 을 호출하여 클린룸의 모든 템플릿에 대해 JinjaSQL을 볼 수 있습니다. 공급자가 작성한 템플릿만 난독 처리할 수 있습니다.

consumer.get_arguments_from_template 을 호출하여 템플릿에 사용된 변수를 구문 분석하고 나열할 수 있습니다. 그러나 크거나 복잡한 템플릿의 경우, 이 프로시저를 실행할 때 모든 템플릿 변수가 나열되지는 않을 수 있으므로 템플릿 사용자에게 유용한 설명서를 제공해야 합니다.

다음 예제에서는 이전에 표시된 공급자의 사용자 지정 템플릿을 컨슈머가 실행하는 방법을 보여줍니다.

 CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'basic_template',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the my_table array.
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the source_table array.
  OBJECT_CONSTRUCT(
  'consumer_id', 'c.hashed_email',  -- hashed_email column from the consumer's table.
  'provider_id', 'p.hashed_email',  -- hashed_email column from the provider's table.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- $$...$$ is used to stringify the column value.
  )
);

공급자 템플릿 예제 코드¶

다음은 공급자가 사용자 지정 템플릿을 추가하는 방법과 컨슈머가 템플릿을 실행하는 방법을 보여주는 전체 코드 예제입니다. 이 코드를 실행하려면 클린룸 API가 설치된 두 개의 별도 계정이 필요합니다. 한 계정은 공급자 역할을 하고 다른 계정은 컨슈머 역할을 합니다.

• 공급자 예제 코드

• 컨슈머 예제 코드

컨슈머 템플릿 예제¶

다음은 컨슈머가 사용자 지정 템플릿을 제출하고 실행하는 방법을 보여주는 전체 코드 예제입니다. 다음 통합 문서 파일을 Snowflake 계정에 업로드합니다. 이 코드를 실행하려면 클린룸 API가 설치된 두 개의 별도 계정이 필요합니다. 한 계정은 공급자 역할을 하고 다른 계정은 컨슈머 역할을 합니다.

• 공급자 예제 코드

• 컨슈머 예제 코드

source_table 및 my_table 채우기¶

표준 source_table 및 my_table 템플릿 변수는 다음과 같이 채울 수 있습니다.

• 기본 테이블 선택기 드롭다운 메뉴 활성화: 이러한 드롭다운 메뉴는 단일 선택입니다. render_provider_table_dropdown 및 render_consumer_table_dropdown 설정을 사용하여 표시하거나 숨길 수 있습니다. 이 드롭다운 메뉴는 정규화된 테이블 이름을 source_table 및 my_table 템플릿 변수에 각각 전달합니다.

열 이름 정규화¶

대부분의 템플릿에서는 열 이름의 모호성을 방지하기 위해 모든 열 이름을 정규화해야 합니다.

템플릿은 공급자 테이블인지 컨슈머 테이블인지에 따라 모든 테이블의 별칭을 p 또는 c 로 지정해야 합니다. 템플릿은 p 또는 c 별칭을 사용하여 모든 열을 참조해야 합니다. 별칭 지정에 대해 자세히 알아보세요.

드롭다운 열 선택기를 만드는 경우 드롭다운 메뉴의 choices 배열에 p 또는 c 테이블을 명시적으로 제공하거나 템플릿에 별칭을 추가해야 합니다.

다음 예제에서는 드롭다운 메뉴에 테이블 별칭을 제공하는 방법을 보여줍니다.

  'provider_join_col': {
    'display_name': 'Provider Join Column',
    'choices': ['p.HASHED_EMAIL', 'p.HASHED_SSN'],
    'type': 'dropdown',
    'description': 'Select the provider column to join users on.',
    'infoMessage': 'We recommend using HASHED_EMAIL.',
    'size': 'M',
    'group': 'Enable Provider Features'
}

그러나 이 방법은 모든 열 이름을 미리 알고 있어야 한다는 점에서 한계가 있습니다.

또는 references 속성을 제공하여 열 드롭다운 메뉴를 동적으로 채울 수 있습니다. 그러나 이러한 선택기는 p.hashed_email 등의 정규화된 열 이름이 아닌 hashed_email 등의 순수한 열 이름을 반환합니다. 순수한 열 이름이 반환되는 경우 명시적으로 템플릿에 열 범위를 테이블로 만들어야 합니다. 예를 들어, 다음 코드는 사용자가 공급자의 조인 정책에서 열을 선택할 수 있는 드롭다운 메뉴를 만듭니다.

'p_join_col': {
  'type': 'dropdown',
  'references': ['PROVIDER_JOIN_POLICY']
}

Copy

템플릿에서 열 이름을 사용하려면 다음 예제와 같이 열 이름 앞에 테이블 별칭을 하드 코딩해야 합니다.

SELECT p.{{ p_join_col | sqlsafe }} FROM table_col AS p;

Copy

클린룸 UI에서 실행할 수 있는 템플릿 개발을 위한 권장 사항¶

다음 단계는 클린룸 UI에서 실행할 수 있는 템플릿을 개발하기 위한 권장 워크플로를 보여줍니다.

SELECT {{ col1 | sqlsafe | column_policy }}, {{ col2 | sqlsafe | column_policy }}
  FROM IDENTIFIER({{ source_table[0] }}) AS p
  JOIN IDENTIFIER({{ my_table[0] }}) AS c

SELECT
  {{ col1 | default('Undefined')}},
  {{ col2 | default('Undefined') }},
  {{ source_table[0] | default('Undefined') }},
  {{ my_table[0] | default('Undefined') }},
  {{ provider_join_col | default('Undefined') }},
  {{ consumer_join_col | default('Undefined') }}
;