Snowflake Data Clean Rooms: 보안 Python UDTF 기반 템플릿¶

환경 설정¶

개발자 APIs를 사용하여 Snowflake Data Clean Room으로 작업하기 전에 다음 명령을 실행하여 Snowflake 환경을 설정합니다. SAMOOHA_APP_ROLE 역할이 없는 경우 계정 관리자에게 문의하십시오.

use role samooha_app_role;
use warehouse app_wh;

클린룸 만들기¶

클린룸의 이름을 지정합니다. 기존 클린룸 이름과 충돌하지 않도록 새 클린룸 이름을 입력합니다. 클린룸 이름에는 영숫자 만 사용할 수 있습니다. 클린룸 이름에는 공백과 밑줄 외의 특수문자를 사용할 수 없습니다.

set cleanroom_name = 'Custom Secure Python UDTF Demo Clean room';

위에서 설정한 클린룸 이름으로 새로운 클린룸을 만들 수 있습니다. 위에 설정한 클린룸 이름이 기존 클린룸으로 이미 존재하는 경우 이 프로세스는 실패합니다.

이 절차의 실행에는 약 45초가 걸립니다.

provider.cleanroom_init 의 두 번째 인자는 클린룸의 분포입니다. 이는 INTERNAL 또는 EXTERNAL일 수 있습니다. 테스트 목적으로 클린룸을 같은 조직의 계정과 공유하는 경우 INTERNAL을 사용하여 애플리케이션 패키지를 공동 작업자에게 릴리스하기 전에 수행해야 하는 자동화된 보안 검사를 우회할 수 있습니다. 그러나 이 클린룸을 다른 조직의 계정과 공유하는 경우에는 EXTERNAL 클린룸 배포를 사용해야 합니다.

call samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

보안 검사 상태를 보려면 다음을 사용합니다.

call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

클린룸을 만든 후에는 공동 작업자와 공유하기 전에 릴리스 지시문을 설정해야 합니다. 그러나 배포가 EXTERNAL로 설정된 경우에는 먼저 보안 검사가 완료될 때까지 기다린 후 릴리스 지시문을 설정해야 합니다. 스캔이 실행되는 동안 나머지 단계를 계속 실행하고 provider.create_cleanroom_listing 단계 전에 여기로 돌아올 수 있습니다.

릴리스 지시문을 설정하려면 다음을 호출합니다.

call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

리전 간 공유¶

사용자의 계정과 다른 리전에 있는 Snowflake 고객과 클린룸을 공유하려면 클라우드 간 자동 복제를 활성화해야 합니다. 다른 리전의 컨슈머와 협업하는 데 따른 추가 비용에 대한 자세한 내용은 클라우드 간 자동 복제 비용을 참조하십시오.

개발자 APIs를 사용할 때, 리전 간 공유를 활성화하는 것은 2단계 프로세스입니다.

1. ACCOUNTADMIN 역할이 있는 Snowflake 관리자는 Snowflake 계정에 대해 클라우드 간 자동 복제를 사용 설정할 수 있습니다. 자세한 지침은 다른 리전의 계정과 협업을 참조하십시오.

2. provider.enable_laf_for_cleanroom 명령을 실행하여 클린룸에 클라우드 간 자동 복제를 사용하도록 설정합니다. 예:

   call samooha_by_snowflake_local_db.provider.enable_laf_for_cleanroom($cleanroom_name);
   

   Copy

클린룸에 대해 클라우드 간 자동 복제를 활성화한 후에는 평소와 같이 provider.create_cleanroom_listing 명령을 사용하여 목록에 컨슈머를 추가할 수 있습니다. 목록은 필요에 따라 원격 클라우드 및 리전에 자동으로 복제됩니다.

데이터 세트를 연결하고 데이터 세트에 대한 조인 정책을 설정합니다.¶

클린룸에 Snowflake 테이블을 연결합니다. Snowflake 계정의 테이블 목록을 탐색하고 정규화된 테이블 이름(Database.Schema.Table)을 배열로 입력합니다. 이 절차를 사용하면 클린룸 내부에서 테이블을 안전하게 볼 수 있어 테이블에 자동으로 액세스할 수 있으므로 테이블 사본을 만들 필요가 없습니다.

call samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

use role accountadmin;
call samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
use role samooha_app_role;

다음 절차에 따라 클린룸에 연결된 데이터 세트를 볼 수 있습니다.

call samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

조인 정책으로 사용할 열을 파악하기 위해 데이터 집합을 보고 PII 열을 결정할 수 있습니다. 상위 10개 행을 보려면 다음 쿼리를 사용합니다.

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

클린룸 내에서 템플릿을 실행할 때 컨슈머가 어떤 열에 참여할 수 있는지 지정합니다. 이 절차는 이메일과 같은 ID 열에 대해 호출되어야 합니다. 조인 정책은 “바꾸기 전용”이므로 함수가 다시 호출되면 이전에 설정된 조인 정책이 새 정책으로 완전히 바뀝니다.

call samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

클린룸에 추가된 조인 정책을 보려면 다음 프로시저를 호출합니다.

call samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

사용자 지정 Python 코드를 UDFs로 클린룸에 기밀로 로드¶

이 섹션에서는 고객의 나이와 활동한 일수를 입력받아 나이를 10년으로, 일수를 연수로 변환하는 간단한 Python UDTF를 로드합니다

다음 API를 사용하면 Python 함수를 클린룸에 인라인 함수로 직접 정의할 수 있습니다. 또는 클린룸 스테이지에 업로드한 스테이징된 파일에서 Python을 로드할 수 있습니다. 예제는 API 참조 가이드를 참조하십시오.

call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'mod_days_and_age',                     -- Name of the UDF
    ['age integer', 'days integer'],        -- Arguments of the UDF, specified as (variable name, variable type)
    ['pandas', 'numpy'],                    -- Packages UDF will use
    'table(decade integer, years float)',   -- Return type of UDF
    'ModifyAgeAndDays',                     -- Handler
    $$
import pandas as pd
import numpy as np

class ModifyAgeAndDays:
    def __init__(self):
        self.year = 365

    def process(self, age, days):
        rounded_age = int(np.floor(age / 10)) * 10
        years = np.round(days / self.year)
        yield (rounded_age, years)
    $$
);

-- See the versions available inside the clean room
show versions in application package samooha_cleanroom_Custom_Secure_Python_UDTF_Demo_clean_room;

-- Once the security scan is approved, update the release directive to the latest version
call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '1');

UDTFs를 사용하여 사용자 지정 템플릿 추가¶

클린룸에 사용자 지정 분석 템플릿을 추가하려면 공급자 측과 컨슈머 측 모두에 테이블 이름을 위한 자리표시자와 공급자 측의 조인 열이 필요합니다. SQL Jinja 템플릿에서는 다음 자리 표시자가 항상 있어야 합니다.

• source_table: 공급자의 테이블 이름 배열

• my_table: 컨슈머의 테이블 이름 배열

테이블 이름은 이러한 변수를 사용하여 동적으로 만들 수 있지만, 원하는 경우 클린룸에 연결된 뷰의 이름을 사용하여 템플릿에 하드코딩할 수도 있습니다. 원하는 경우 열 이름을 템플릿에 하드코딩하거나 매개 변수를 통해 동적으로 설정할 수 있습니다. 매개 변수를 통해 설정한 경우 열 정책에 대해 확인하려면 배열이어야 하는 매개 변수 dimensions 또는 measure_column 을 호출해야 한다는 점을 기억하십시오. 이를 템플릿에 SQL Jinja 매개 변수로 추가하면 나중에 컨슈머가 쿼리할 때 전달할 수 있습니다. 조인 정책은 컨슈머가 권한이 있는 열 이외의 열에 조인할 수 없도록 보장합니다.

또는 사용자 지정 SQL Jinja 템플릿의 모든 인자가 다음 필터를 사용하여 조인 및 열 정책을 준수하는지 확인할 수 있습니다.

• join_policy: 문자열 값 또는 필터 절이 조인 정책을 준수하는지 확인합니다.

• column_policy: 문자열 값 또는 필터 절이 열 정책을 준수하는지 확인합니다.

• join_and_column_policy: 필터 절에서 조인에 사용된 열이 조인 정책을 준수하는지, 필터로 사용된 열이 열 정책을 준수하는지 확인합니다.

예를 들어, {{ provider_id | sqlsafe | join_policy }} 절에서, p.HEM 의 입력을 구문 분석하여 p.HEM 이 조인 정책에 있는지 확인합니다. 참고: sqlsafe 필터는 공동 작업자가 템플릿에 순수 SQL을 삽입할 수 있도록 허용하므로 주의해서 사용해야 합니다.

이 함수는 이름이 동일한 기존 템플릿을 모두 재정의합니다. 기존 템플릿을 업데이트하려면 업데이트된 템플릿으로 이 함수를 다시 호출하면 하면 됩니다.

이 템플릿은 고객 테이블을 간단히 스캔한 다음 수십 년 단위의 나이와 연 단위의 활동 일수를 반환합니다.

call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    'prod_custom_udtf_age_days',
$$
    select decade, years from identifier({{ source_table[0] }}) p, table(cleanroom.mod_days_and_age(identifier({{ dimensions[0] | column_policy }}), identifier({{ dimensions[1] | column_policy }})));
$$
);

OPTIONAL: UDTF를 사용하는 더 복잡한 사용자 지정 템플릿¶

이 템플릿은 먼저 컨슈머 테이블과 공급자 테이블의 추가 중첩을 수행한 다음, 내부 조인에 UDTF를 적용하고 중첩에서 추가 데이터를 가져옵니다.

call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    'prod_custom_udtf_age_days_with_overlap',
$$
    select 
        c.status,
        decade, 
        avg(years) as years,
        sum(c.days_active) as days_active_c
    from 
        identifier({{ source_table[0] }}) p 
        inner join 
        identifier({{ my_table[0] }}) c
        on p.hem = c.hem,
        table(cleanroom.mod_days_and_age(identifier({{ dimensions[0] | column_policy }}), identifier({{ dimensions[1] | column_policy }})))
    group by c.status, decade
    order by c.status, decade
$$
);

추가된 템플릿 보기¶

현재 클린룸에서 활성화된 템플릿을 보려면 다음 프로시저를 호출합니다.

call samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

각 테이블에 열 정책 설정¶

테이블의 내부에 있는 열을 확인하기 위해 연결된 데이터를 표시합니다. 상위 10개 행을 보려면 다음 프로시저를 호출합니다.

select * from SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS limit 10;

모든 테이블과 템플릿 조합에 대해 컨슈머가 그룹화하고 집계할 수 있는 열(예: SUM/AVG)을 설정하고 일반적으로 분석에 사용할 수 있습니다. 이를 통해 유연성이 제공되므로 기본 템플릿에 따라 동일한 테이블에서도 다른 열 선택을 허용할 수 있습니다. 이 작업은 템플릿을 추가한 후에만 호출해야 합니다.

열 정책은 바꾸기 전용 이므로 함수가 다시 호출되면 이전에 설정된 열 정책이 새 정책으로 완전히 바뀝니다.

컨슈머가 이러한 열을 기준으로 그룹화할 수 없도록 하려면 이메일, HEM 또는 RampID 등과 같은 ID 열에는 열 정책을 사용해서는 안 됩니다. 프로덕션 환경에서는 시스템이 지능적으로 PII 열을 추론하여 이 작업을 차단하지만 샌드박스 환경에서는 이 기능을 사용할 수 없습니다. 상태, 연령대, 채널, 활성 일수 등 컨슈머가 집계하고 그룹화할 수 있는 열에만 사용해야 합니다.

컨슈머 분석 요청에 대한 검사를 수행하기 위해 “column_policy” 및 “join_policy”가 SQL Jinja 템플릿에서 모든 열 이름을 dimensions 또는 measure_columns 로 참조해야 합니다. 사용자 지정 SQL Jinja 템플릿에서 확인할 열을 참조할 때 이 태그를 사용합니다.

call samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_custom_udtf_age_days:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_custom_udtf_age_days:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_custom_udtf_age_days_with_overlap:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND', 
    'prod_custom_udtf_age_days_with_overlap:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE'
]);

템플릿에 추가된 열 정책을 보려면 다음 프로시저를 호출합니다.

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

컨슈머와 공유¶

마지막으로, 아래와 같이 Snowflake 계정 로케이터와 계정 이름을 추가하여 클린룸에 데이터 컨슈머를 추가합니다. Snowflake 계정 이름은 <ORGANIZATION>.<ACCOUNT_NAME> 형식이어야 합니다.

show versions in application package samooha_cleanroom_Custom_Secure_Python_UDTF_Demo_clean_room;

call samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSMUMER_ACCOUNT_LOCATOR>');

여러 개의 컨슈머 계정 로케이터를 provider.add_consumers 함수에 쉼표로 구분된 문자열로 전달하거나 provider.add_consumers 에 대한 별도의 호출로 전달할 수 있습니다.

이 클린룸에 추가된 컨슈머를 보려면 다음 프로시저를 호출합니다.

call samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

다음 절차에 따라 최근에 생성된 클린룸을 확인합니다.

call samooha_by_snowflake_local_db.provider.view_cleanrooms();

다음 절차를 통해 최근 생성된 클린룸에 대한 더 많은 인사이트를 살펴볼 수 있습니다.

call samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

생성된 클린룸도 삭제할 수 있습니다. 다음 명령은 클린룸을 완전히 삭제하므로 이전에 클린룸을 사용할 수 있었던 모든 컨슈머는 더 이상 클린룸을 사용할 수 없습니다. 나중에 이름이 동일한 클린룸이 필요한 경우 위의 흐름을 사용하여 다시 초기화해야 합니다.

call samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

환경 설정¶

개발자 APIs를 사용하여 Snowflake Data Clean Room으로 작업하기 전에 다음 명령을 실행하여 Snowflake 환경을 설정합니다. SAMOOHA_APP_ROLE 역할이 없는 경우 계정 관리자에게 문의하십시오.

use role samooha_app_role;
use warehouse app_wh;

클린룸 설치¶

클린룸 공유가 설치되면 아래 명령을 사용하여 사용 가능한 클린룸 목록을 볼 수 있습니다.

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

공급자가 사용자와 공유한 클린룸의 이름을 지정합니다.

set cleanroom_name = 'Custom Secure Python UDTF Demo Clean room';

다음 명령은 연결된 공급자와 선택된 클린룸을 사용하여 컨슈머 계정에 클린룸을 설치합니다.

이 절차의 실행에는 약 45초가 걸립니다.

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

클린룸이 설치되면 공급자는 클린룸을 사용하기 전에 공급자 측에서 클린룸 설치를 완료해야 합니다. 아래 함수을 사용하면 클린룸의 상태를 확인할 수 있습니다. 해당 기능이 활성화되면 아래의 Run Analysis 명령을 실행할 수 있습니다. 일반적으로 클린룸이 활성화되려면 약 1분이 걸립니다.

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

분석 실행¶

이제 클린룸이 설치되었으므로 “run_analysis” 명령을 사용하여 공급자가 클린룸에 추가한 분석 템플릿을 실행할 수 있습니다. 아래 섹션에서 각 필드가 어떻게 결정되는지 확인할 수 있습니다.

전달 가능한 데이터 세트의 수는 공급자가 구현한 템플릿에 따라 제한됩니다. 일부 템플릿에는 특정 개수의 테이블이 필요합니다. 템플릿 작성자는 지원할 요구 사항을 적용할 수 있습니다.

call samooha_by_snowflake_local_db.consumer.run_analysis(
    $cleanroom_name,
    'prod_custom_udtf_age_days',
    [],                                         -- The consumer tables go here
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], -- The provider tables go here
    object_construct(
        'dimensions', ['p.age_band', 'p.days_active']  -- Any parameters the template needs will go here
    )
);

데이터 세트 필터링 “where_clause” 또는 차원 또는 measure_columns에서 참조해야 하는 각 열에 대해, 공급자 테이블의 필드를 참조하려면 p.를 사용하고, 컨슈머 테이블의 필드를 참조하려면 c.를 사용하면 됩니다. 두 개 이상의 공급자 테이블에는 p2, p3 등을 사용하고, 두 개 이상의 컨슈머 테이블에는 c2, c3 등을 사용합니다.

OPTIONAL: 분석 실행¶

다음 run_analysis 호출은 먼저 중첩을 실행하는 선택적 예제에 대한 결과를 가져옵니다. 먼저 다음 프로시저에 따라 데이터 세트를 클린룸에 연결해야 합니다.

call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

use role accountadmin;
call samooha_by_snowflake_local_db.consumer.register_db('<DATABASE_NAME>');
use role samooha_app_role;

이제 분석을 실행할 수 있습니다.

call samooha_by_snowflake_local_db.consumer.run_analysis(
    $cleanroom_name,
    'prod_custom_udtf_age_days_with_overlap',
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- The consumer tables go here
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], -- The provider tables go here
    object_construct(
        'dimensions', ['p.age_band', 'p.days_active']  -- Any parameters the template needs will go here
    )
);

데이터 세트 필터링 “where_clause” 또는 차원 또는 measure_columns에서 참조해야 하는 각 열에 대해, 공급자 테이블의 필드를 참조하려면 p.를 사용하고, 컨슈머 테이블의 필드를 참조하려면 c.를 사용하면 됩니다. 두 개 이상의 공급자 테이블에는 p2, p3 등을 사용하고, 두 개 이상의 컨슈머 테이블에는 c2, c3 등을 사용합니다.

run_analysis에 대한 입력을 결정하는 방법¶

분석을 실행하려면 run_analysis 함수에 몇 가지 매개 변수를 전달해야 합니다. 이 섹션에서는 전달할 매개 변수를 결정하는 방법을 설명합니다.

템플릿 이름

먼저, 다음 프로시저를 호출하여 지원되는 분석 템플릿을 볼 수 있습니다.

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

템플릿을 사용하여 분석을 실행하기 전에 어떤 인자를 지정해야 하는지, 어떤 유형이 예상되는지 알아야 합니다. 사용자 지정 템플릿의 경우 다음을 실행할 수 있습니다.

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_custom_udtf_age_days');

여기에는 많은 수의 다양한 SQL Jinja 매개 변수가 포함되는 경우가 많습니다. 다음 기능은 SQL Jinja 템플릿의 구문을 분석하고 run_analysis에 지정해야 하는 인자를 목록으로 추출합니다.

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_custom_udtf_age_days');

데이터 세트 이름

공급자가 클린룸에 추가한 데이터 세트 이름을 보려면 다음 프로시저를 호출합니다. 클린룸의 보안 속성으로 인해 공급자가 클린룸에 추가한 데이터 세트에 있는 데이터를 볼 수 없습니다.

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

다음 호출을 사용하면 클린룸에 연결한 테이블도 볼 수 있습니다.

call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

차원 및 측정 열

분석을 실행하는 동안 특정 열을 기준으로 필터링, 그룹화 및 집계를 수행할 수 있습니다. 공급자가 클린룸에 추가한 열 정책을 보려면 다음 프로시저를 호출합니다.

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

일반적인 오류

실행한 분석의 결과로 승인되지 않음: 권한이 없는 열이 사용됨 오류가 발생하는 경우 공급자가 설정한 조인 정책 및 열 정책을 다시 확인해 보십시오.

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

또한 개인정보 보호 예산이 소진되어 더 이상 쿼리를 실행할 수 없을 수도 있습니다. 잔여 개인정보 보호 예산은 아래 명령을 사용하여 볼 수 있습니다. 이는 매일 재설정되며, 원하는 경우 클린룸 공급자가 재설정할 수도 있습니다.

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

다음 API를 사용하여 클린룸에 대해 차등 개인정보 보호가 활성화되었는지 확인할 수 있습니다.

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);