Snowflake Data Clean Rooms: 컨슈머 API 참조 가이드

아래 콘텐츠는 Snowflake Data Clean Rooms에서 컨슈머를 위해 제공하는 모든 개발자 APIs에 대한 세부 정보입니다. 모든 함수는 다음 스키마 내부에 있습니다.

samooha_by_snowflake_local_db.consumer
Copy

환경 설정

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

use role samooha_app_role;
use warehouse app_wh;
Copy

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

set cleanroom_name = 'Test Cleanroom 1';
Copy

클린룸 설치

다음 명령을 통해 공급자가 공유한 클린룸을 설치합니다.

consumer.install_cleanroom

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

인자: cleanroom_name (string), provider_account_locator (string)

반환: 성공 메시지 (string)

예제:

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

consumer.is_enabled

설명: 클린룸이 설치되면 공급자 측에서 설정을 완료하고 활성화하는 데 약 1분이 걸립니다. 이 함수를 사용하면 사용자가 클린룸의 상태를 확인하고, 활성화되어 있는지 여부를 확인할 수 있습니다. 일반적으로 클린룸을 설치한 후 약 1분 후에 플래그가 True로 전환됩니다.

인자: cleanroom_name (string)

반환: 활성화됨 (boolean)

예제:

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
Copy

consumer.uninstall_cleanroom

설명: 컨슈머 계정에서 클린룸을 제거합니다. 이렇게 하면 공유 클린룸 데이터베이스를 포함하여 클린룸과 관련된 모든 데이터베이스가 제거됩니다. 클린룸은 언제든지 consumer.install_cleanroom 을 사용하여 다시 설치할 수 있습니다.

인자: cleanroom_name (string)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Copy

Provider Run Analysis 설정

library.is_provider_run_enabled

설명: 이 클린룸에 Provider Run Analysis가 활성화되어 있는지 확인합니다. 참고: consumer.enable_templates_for_provider_run 을 호출하여 명시적인 승인을 획득해야 합니다(아래 참조).

인자: cleanroom_name (string)

반환: 활성화된 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
Copy

library.is_consumer_run_enabled

설명: 이 클린룸에서 Consumer Run Analysis가 활성화되었는지 확인합니다. 이 플래그는 클린룸 컨슈머(설치 관리자)가 분석을 실행할 수 있는지, 아니면 공동 작업에 대한 데이터 기여자 역할을 할 수 있는지 여부를 결정합니다.

인자: cleanroom_name (string)

반환: 활성화된 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
Copy

consumer.enable_templates_for_provider_run

설명: 클린룸에 Provider Run Analysis가 활성화된 경우(즉, 클린룸 공급자가 분석을 실행할 수 있도록 클린룸을 표시한 경우), 컨슈머가 이 프로시저를 호출하여 이를 활성화해야 합니다. 이 프로시저는 분석을 실행할 공급자에 템플릿별로 명시적인 승인을 제공하는 데 필요합니다.

마지막 부울 매개 변수를 TRUE로 설정하면 컨슈머가 공급자의 분석에 대해 차등 개인정보 보호를 활성화할 수 있습니다.

인자:

  • cleanroom_name (string) - 클린룸의 이름.

  • template_names (array of strings) - 공급자 분석을 위해 활성화해야 하는 클린룸의 하나 이상의 템플릿 배열입니다

  • enable_differential_privacy (boolean) - TRUE 인 경우, template_names 에 나열된 모든 템플릿에 대해 차등 개인정보 보호를 활성화합니다. 클린룸 자체에 차등 개인정보 보호가 활성화된 경우에만 이러한 템플릿에 대해 차등 개인정보 보호를 활성화할 수 있습니다. 클린룸의 차등 개인정보 보호 상태는 consumer.is_dp_enabled 에서 확인할 수 있습니다.

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
Copy

데이터 등록 및 등록 취소

다음 명령을 사용하여 데이터베이스, 스키마, 오브젝트를 등록하고 등록을 취소합니다. 테이블과 뷰는 클린룸에 연결하기 전에 등록되어야 합니다. 데이터베이스나 스키마를 등록하면 해당 데이터베이스나 스키마에 있는 모든 오브젝트가 등록됩니다.

consumer.register_db

설명: 클린룸에 데이터베이스를 추가하면 데이터베이스의 모든 데이터 세트를 연결할 수 있습니다. 이것이 호출되지 않으면 samooha_app_role에 개별적으로 권한을 부여해야 합니다.

인자: db_name (string)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.register_schema

설명: register_db 와 유사하지만, 스키마 수준에서 작동합니다. 정규화된 스키마 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여를 선택하면 사용자가 스키마의 오브젝트를 클린룸에 연결할 수 있습니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)를 등록하려면 library.register_managed_access_schema 를 대신 사용합니다.

인자: schema_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_managed_access_schema

설명: register_schema 와 유사하지만, WITH MANAGED ACCESS 매개 변수를 사용하여 생성한 스키마를 등록합니다. 정규화된 스키마 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여를 선택하면 사용자가 스키마의 오브젝트를 클린룸에 연결할 수 있습니다.

인자: schema_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_objects

설명: 클린룸에 모든 유형의 테이블 및 뷰에 대한 액세스 권한을 부여하여 consumer.link_datasets 를 호출하여 클린룸에 연결할 수 있도록 합니다. library.register_schema, library.register_managed_access_schema 또는 consumer.register_db 를 호출하여 더 광범위한 오브젝트 그룹을 등록할 수 있습니다.

인자:

  • object_names (array) - 정규화된 오브젝트 이름의 배열입니다. 그런 다음 이러한 오브젝트를 클린룸에 연결할 수 있습니다.

반환: 성공 메시지 (string)

테이블과 뷰를 등록하려면 다음을 수행합니다.

call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.register_table_or_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.register_objects를 사용하십시오.

설명: 모든 유형의 테이블과 뷰를 등록합니다.

인자: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

출력: success message (string)

테이블을 등록하려면:

call samooha_by_snowflake_local_db.library.register_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);
Copy

Iceberg 테이블을 등록하려면:

call samooha_by_snowflake_local_db.library.register_table_or_view(
        ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], 
        false, 
        true,
        false,
        false);
Copy

library.register_table – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.register_objects를 사용하십시오.

설명: register_db 와 유사하지만 테이블 수준에서 작동합니다. 정규화된 테이블 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여가 이루어지면 사용자가 테이블을 클린룸에 연결할 수 있습니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)에 테이블을 등록하려면 대신 library.register_managed_access_table 을 사용합니다.

인자: table_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_managed_access_table – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.register_objects를 사용하십시오.

설명: register_table 과 유사하지만, WITH MANAGED ACCESS 매개 변수로 생성된 스키마에 테이블을 등록합니다. 정규화된 테이블 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여가 이루어지면 사용자가 테이블을 클린룸에 연결할 수 있습니다.

인자: table_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.register_objects를 사용하십시오.

설명: register_db 와 유사하지만, 뷰 수준에서 작동합니다. 정규화된 뷰 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여를 선택하면 사용자가 뷰를 클린룸에 연결할 수 있습니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 만든 스키마)에 보기를 등록하려면 대신 library.register_managed_access_view 를 사용합니다.

인자: view_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_managed_access_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.register_objects를 사용하십시오.

설명: register_view 와 유사하지만, WITH MANAGED ACCESS 매개 변수로 생성된 스키마에 뷰를 등록합니다. 정규화된 뷰 이름을 나타내는 배열 또는 문자열을 전달하고 SAMOOHA_APP_ROLE 역할에 대한 권한 부여를 선택하면 사용자가 뷰를 클린룸에 연결할 수 있습니다.

인자: view_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_db

설명: register_db 프로시저를 되돌리고 SAMOOHA_APP_ROLE 역할 및 Snowflake Data Clean Room 기본 애플리케이션에 부여된 데이터베이스 수준 부여를 제거합니다. 이렇게 하면 UI 드롭다운 요소에서 모든 데이터베이스도 제거됩니다.

인자: db_name (string)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.unregister_schema

설명: 스키마의 등록을 취소하여 사용자가 해당 테이블과 뷰를 클린룸에 연결하는 것을 방지합니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)를 등록 해지하려면 library.unregister_managed_access_schema 를 대신 사용합니다.

인자: schema_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_managed_access_schema

설명: unregister_schema 와 유사하지만, WITH MANAGED ACCESS 매개 변수를 사용하여 생성한 스키마를 등록 취소합니다.

인자: schema_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_objects

설명: 모든 유형의 테이블 및 뷰에 대한 클린룸 액세스를 취소합니다. 이 계정으로 관리되는 모든 클린룸의 사용자는 더 이상 오브젝트를 사용할 수 없게 됩니다.

인자:

  • object_names (array) - 액세스를 취소해야 하는 정규화된 오브젝트 이름의 배열입니다.

반환: 성공 메시지 (string)

테이블 및 뷰 등록을 취소하려면 다음을 수행합니다.

call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.unregister_table_or_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.unregister_objects를 사용하십시오.

설명: 모든 유형의 테이블과 뷰를 등록 취소합니다.

인자: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

출력: success message (string)

테이블 등록을 취소하려면:

call samooha_by_snowflake_local_db.library.unregister_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);
Copy

library.unregister_table – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.unregister_objects를 사용하십시오

설명: unregister_db 와 유사하지만, 테이블 수준에서 작동합니다. 완전히 정규화된 테이블 이름을 나타내는 배열이나 문자열을 전달하여 테이블의 등록을 취소할 수 있습니다. 사용자는 등록되지 않은 테이블을 클린룸에 연결할 수 없습니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)에 테이블을 등록 취소하려면 대신 library.unregister_managed_access_table 을 사용합니다.

인자: table_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_managed_access_table – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.unregister_objects를 사용하십시오

설명: unregister_table 과 유사하지만, 관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)의 테이블 등록을 취소합니다.

인자: table_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.unregister_objects를 사용하십시오

설명: unregister_db 와 유사하지만, 뷰 수준에서 작동합니다. 완전히 정규화된 뷰 이름을 나타내는 배열이나 문자열을 전달하여 뷰의 등록을 취소할 수 있습니다. 사용자는 등록되지 않은 뷰를 클린룸에 연결할 수 없습니다.

관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 만든 스키마)에 보기를 등록 취소하려면 대신 library.unregister_managed_access_view 를 사용합니다.

인자: view_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_managed_access_view – 사용 중단됨

주의

이 명령은 이제 더 이상 사용되지 않습니다. 대신 library.unregister_objects를 사용하십시오

설명: unregister_view 와 유사하지만, 관리되는 액세스 스키마(즉, WITH MANAGED ACCESS 매개 변수로 생성된 스키마)의 뷰 등록을 취소합니다.

인자: view_name (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

공급자 실행 분석

consumer.set_join_policy

설명: Provider Run Analysis를 사용하여 클린룸 내에서 템플릿을 실행할 때 공급자가 조인을 수행할 수 있는 열을 지정합니다. 열 정책은 바꾸기 전용 이므로 함수가 다시 호출되면 이전에 설정된 열 정책이 현재 정책으로 완전히 바뀝니다.

이 검사는 승인되지 않은 열이 있는지 데이터에 대해 실행할 SQL 쿼리를 구문 분석하는 방식으로 수행됩니다. 와일드카드가 포함된 쿼리는 이러한 검사를 통해 포착되지 않을 수 있으며, 분석 템플릿을 설계할 때는 여전히 신중해야 합니다.

인자: cleanroom_name (string), table_and_col_names (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);
Copy

consumer.set_column_policy

설명: 공급자가 작업을 수행할 수 있는 데이터의 열을 설정합니다. 이 작업은 템플릿을 추가한 후에만 호출해야 합니다. 이 함수도 템플릿의 함수이므로 입력은 template_name:full_table_name:column_name 형식이어야 합니다. 열 정책은 바꾸기 전용 이므로 함수가 재호출되면 이전에 설정된 열 정책이 현재 정책으로 완전히 바뀝니다.

이메일과 같은 ID 열에서는 열 정책을 호출해서는 안 됩니다. 이는 집계 및 그룹화 열에만 사용해야 합니다.

이 검사는 승인되지 않은 열이 있는지 데이터에 대해 실행할 SQL 쿼리를 구문 분석하는 방식으로 수행됩니다. 와일드카드가 포함된 쿼리는 이러한 검사를 통해 포착되지 않을 수 있으며, 분석 템플릿을 설계할 때는 여전히 신중해야 합니다.

확인은 차원 또는 measure_columns 라는 SQL Jinja 인자에 대해 수행됩니다. 이 검사를 활성화하려면 이러한 태그를 사용해야 합니다.

인자: cleanroom_name (string), analysis_and_table_and_columns (array)

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:CAMPAIGN']);
Copy

템플릿

다음 명령을 사용하면 클린룸에서 사용 가능한 템플릿으로 작업할 수 있습니다.

consumer.view_template_definition

설명: 클린룸 템플릿 정의는 템플릿에 전달해야 할 매개 변수를 결정하는 데 도움이 됩니다.

참고

모든 Samooha 프로시저는 암호화되어 있으며 기본적으로 볼 수 없습니다. 하지만 사용자가 추가한 사용자 지정 템플릿은 모두 표시됩니다.

인자: cleanroom_name (string), template_name (string)

반환: 템플릿 정의 (string)

예제:

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

consumer.get_arguments_from_template

설명: 데이터를 구성하는 방법과 각 템플릿에 필요한 데이터를 정의하여 출력을 쉽게 수집할 수 있도록 합니다.

인자: cleanroom_name (string), template_name (string)

반환: 인자 목록 및 사양 (table)

예제:

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

템플릿 체인

다음 명령을 사용하면 사용자는 클린룸에서 사용할 수 있는 템플릿 체인을 사용하여 작업할 수 있습니다. 템플릿 체인 사용에 대한 일반적인 정보는 개발자 APIs를 사용하여 템플릿을 순차적으로 실행하기를 참조하십시오.

consumer.view_added_template_chains

설명: 클린룸에서 현재 활성화된 템플릿 체인을 봅니다.

인자: cleanroom_name (string)

반환: 추가된 템플릿 체인 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);
Copy

consumer.view_template_chain_definition

설명: 템플릿 체인의 특성을 반환합니다.

인자: cleanroom_name (string), template_chain_name (string)

반환: 템플릿 체인 정의 (string)

예제:

call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');
Copy

consumer.get_arguments_from_template_chain

설명: 템플릿 체인의 모든 템플릿에 대한 예상 인자를 반환합니다.

인자: cleanroom_name (string), template__chain_name (string)

반환: 인자 목록 및 사양 (table)

예제:

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template_chain($cleanroom_name, 'insights_chain');
Copy

분석 실행

다음 명령은 지정된 템플릿을 기반으로 특정 분석이나 활성화를 실행합니다.

consumer.run_analysis

설명: 템플릿 또는 템플릿 체인을 사용하여 분석을 실행하고 결과 테이블을 반환합니다.

차등 개인정보 보호를 사용하도록 설정한 경우 이 템플릿의 예산 한도에 도달하면 쿼리가 실패할 수 있습니다.

인자:

  • cleanroom_name (string) - 실행할 템플릿이 있는 클린룸의 이름입니다.

  • template_name (string) - 클린룸에서 실행할 템플릿 또는 템플릿 체인의 이름입니다.

  • consumer_tables (array of strings) - 정규화된 컨슈머 테이블 이름의 배열입니다. my_table 템플릿 변수에 할당됩니다. 이러한 테이블은 이미 클린룸에 링크되어 있어야 합니다. consumer.view_consumer_datasets 를 호출하여 사용 가능한 테이블을 확인하십시오. 예를 들어, [‘mytable1’,’mytable2’,’mytable3’]을 전달하면 템플릿은 각각 {{my_table[0]}}, {{my_table[1]}}{{my_table[2]}} 로 이 값에 액세스할 수 있습니다.

  • provider_tables (array of strings) - 정규화된 공급자 테이블 이름의 배열입니다. source_table 템플릿 변수에 할당됩니다. 이러한 테이블은 이미 클린룸에 링크되어 있어야 합니다. consumer.view_provider_datasets 를 호출하여 사용 가능한 테이블을 확인하십시오. 예를 들어, [‘sourcetable1’,’sourcetable2’,’sourcetable3’]을 전달하면 템플릿은 각각 {{source_table[0]}}, {{source_table[1]}}{{source_table[2]}} 로 이 값에 액세스할 수 있습니다.

  • analysis_arguments (object) - 템플릿에 전달된 키-값 페어가 있는 오브젝트입니다. 템플릿은 키 이름으로 변수에 액세스할 수 있습니다. {'age': 20} 을 전달하면 템플릿은 {{age}} 로 값에 액세스합니다. 요구 사항이 없는 경우 빈 오브젝트를 전달합니다. 어떤 값이 필요한지 확인하려면 consumer.view_template_definition 을 호출하여 해당 템플릿을 살펴봅니다. 이 오브젝트에는 1개의 선택적 예약 값이 있습니다.

  • use_cache(부울, 선택 사항) - 동일한 쿼리에 캐시된 결과를 사용할지 여부입니다. 기본값은 TRUE 입니다. 템플릿을 테스트하고 편집할 때 FALSE 로 설정하여 매번 최신 버전의 템플릿을 사용하여 쿼리가 다시 실행되도록 합니다.

반환: (Table) 쿼리 결과.

예제:

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'],      -- Provider tables
  object_construct(
    'max_age', 30
  )
);
Copy

활성화

결과 활성화에 대한 자세한 내용은 개발자 APIs 를 사용하여 활성화를 위해 Snowflake 계정으로 결과 보내기를 참조하십시오.

consumer.set_activation_policy

설명: 활성화 템플릿 내에서 사용할 수 있는 열을 정의합니다. 이렇게 하면 컨슈머가 승인한 열만 활성화 템플릿과 함께 사용할 수 있습니다.

입력: cleanroom_name (string), columns (array)

인자는 <template_name>:<fully_qualified_table_name>:<column_name> 형식으로 전달됩니다.

출력: Success message

예제:

call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [ 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',  
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
Copy

consumer.run_activation

설명: 결과를 다시 Snowflake 계정으로 푸시하여 활성화하는 템플릿을 실행합니다.

인자: cleanroom_name (string), segment_name (string), template_name (string), consumer_tables (array), provider_tables (array), activation_arguments (object), consumer_direct_activation (boolean), application_id (string)

컨슈머가 활성화를 위해 자신의 Snowflake 계정으로 결과 세트를 푸시하는 경우, consumer_direct_activation 인자를 TRUE 로 설정합니다.

application_id 에 빈 문자열을 인자로 전달합니다.

반환: 성공 메시지

예제:

call samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  'my_activation_segment',
  'activation_custom_template',
  ['consumer_source_table'], 
  ['provider_source_table'],
  object_construct(                 -- Custom arguments needed for the template
    'dimensions', ['p.CAMPAIGN'],   -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
    'where_clause', 'p.EMAIL=c.EMAIL'
  ));
Copy

컨슈머 정의 템플릿

다음 APIs 을 사용하면 클린룸에 컨슈머 정의 템플릿을 추가할 수 있습니다. 자세한 내용은 개발자 API를 사용하여 컨슈머 정의 템플릿 추가하기 섹션을 참조하십시오.

consumer.create_template_request

설명: 클린룸 공급자에게 사용자 지정 템플릿을 클린룸에 추가할 수 있도록 승인해 달라는 요청을 보냅니다.

인자: cleanroom_name (string), template_name (string), template_definition (string)

반환: 성공 메시지 (string)

예제:

  CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom', 
  'my_analysis', 
  $$
  SELECT 
      identifier({{ dimensions[0] | column_policy }}) 
  FROM 
      identifier({{ my_table[0] }}) c 
    INNER JOIN
      identifier({{ source_table[0] }}) p 
        ON   
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }}) 
        {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);
Copy

consumer.generate_python_request_template

설명: 사용자 정의 Python 코드가 포함된 컨슈머 클린룸 템플릿을 생성합니다. 생성된 템플릿에는 Python 코드와 JinjaSQL 템플릿의 자리 표시자가 포함됩니다. 최종 템플릿을 consumer.list_template_requests 로 전달합니다.

컨슈머 정의 템플릿에 대해 자세히 알아보십시오.

인자:

  • function_name (string) - SQL 템플릿이 함수를 실행하기 위해 호출해야 하는 Python 함수의 이름입니다.

  • 인자 (array of strings) - 각 인자가 “<argument_name> <argument_type>” 형식의 공백으로 구분된 문자열 쌍인 Python 함수에 대한 인자 목록입니다. 예를 들어, ['데이터 베리언트', '소수 자릿수 정수'] .

  • packages (array of strings) - Python 코드에 필요한 패키지 이름의 배열입니다. 없는 경우 빈 배열을 지정합니다. 예: ['pandas','numpy'] .

  • imports (array of strings) - Python 코드에 필요한 모든 사용자 정의 Python 라이브러리입니다. 0개 이상의 스테이지 주소로 구성된 배열이어야 합니다. 예: ['@db.schema.stage/my_python_sproc.py']

  • rettype (string) - 함수의 SQL 반환 유형입니다. 예: '정수' , 'varchar' .

  • 처리기 (string) - Python 코드에서 기본 처리기 함수의 이름입니다. 일반적으로 이는 'main' 입니다.

  • 코드 (string) - Python 코드 구현입니다. 가져오기를 포함하고 지정된 처리기가 가져오기 내에 정의되어 있는 경우 빈 문자열일 수 있습니다.

반환: 생성된 Python 템플릿 (string). 자리 표시자를 SQL 코드로 바꿉니다.

예제:

간단한 Python 예제를 통해 도우미 함수를 호출해 보십시오.

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
  'my_func',                         // SQL should use this name to call your function
  ['data variant', 'index integer'], // Arguments and types for the function
  ['pandas', 'numpy'],               // Standard libraries used
  [],                                // No custom libraries needed.
  'integer',                         // Return type integer
  'main',                            // Standard main handler
// Python implementation as UDF  
  $$
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    $$
);
Copy

이전 호출에 대한 응답은 다음과 같습니다. 자리 표시자에 표시된 대로 JinjaSQL 을 삽입하고 consumer.create_template_request 에 전달합니다.

BEGIN

-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')

HANDLER = 'main'
AS '
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    ';
        

-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';

-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);

END;
Copy

consumer.list_template_requests

설명: 컨슈머가 클린룸에 템플릿을 추가하기 위해 요청한 내용을 나열합니다.

인자: cleanroom_name (string)

반환값: request_id (string), provider_identifier (string), template_name (string), template_definition (string), request_status (string), reason (string)

예제:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');
Copy

클린룸 메타데이터 getter 메서드

다음 메서드는 클린룸의 관련 속성을 보여줍니다.

consumer.describe_cleanroom

설명: 템플릿, 데이터 세트, 정책 등 클린룸에 추가된 항목에 대한 모든 정보가 포함된 텍스트 요약을 만듭니다.

인자: cleanroom_name (string)

반환: 클린룸의 광범위한 설명 문자열 (table)

예제:

call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
Copy

consumer.view_provider_datasets

설명: 공급자가 클린룸에 추가한 모든 데이터 세트를 봅니다.

인자: cleanroom_name (string)

반환: 클린룸의 모든 공급자 데이터 세트 이름 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
Copy

consumer.view_join_policy

설명: 컨슈머가 컨슈머 데이터 세트에 설정한, 클린룸 내부에서 사용자가 안전하게 참여할 수 있는 열을 간략하게 설명합니다.

인자: cleanroom_name (string)

반환: 조인 정책 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
Copy

consumer.view_provider_join_policy

설명: 공급자가 공급자 데이터 세트에 설정한 클린룸 내에서 사용자가 안전하게 조인할 수 있는 열을 간략하게 설명합니다.

인자: cleanroom_name (string)

반환: 조인 정책 (table)

예제:

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

consumer.view_added_templates

설명: 클린룸에 있는 모든 활성 템플릿을 봅니다.

인자: cleanroom_name (string)

반환: 추가된 템플릿 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
Copy

consumer.view_column_policy

설명: 컨슈머가 클린룸에 적용한 모든 열 정책을 봅니다.

인자: cleanroom_name (string)

반환: 열 정책 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
Copy

consumer.view_provider_column_policy

설명: 공급자가 클린룸에 적용한 모든 열 정책을 봅니다.

인자: cleanroom_name (string)

반환: 열 정책 (table)

예제:

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

consumer.view_cleanrooms

설명: 이 계정이 조인(설치)했거나 조인 가능한 모든 클린룸을 표시합니다. 실패한 클린룸은 표시되지 않습니다. 결과 테이블에서:

  • IS_ALREADY_INSTALLED: 클린룸에 조인되어 있으면 True(웹 앱의 조인 탭), 클린룸에 초대를 받았지만 조인하지 않은 경우 False(웹 앱의 초대 탭)입니다.

    알려진 문제: - 이 방법은 때때로 제거된 클린룸을 표시하지 않을 수 있습니다. 공유된 클린룸을 알고 있지만 목록에 표시되지 않는 경우 consumer.describe_cleanroom 을 호출하여 해당 클린룸의 조인 가능 여부를 확인하십시오.

인자: 없음

반환: 생성 날짜별로 주문된 모든 기존 클린룸 (table)

예제:

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Copy

차등 개인정보 보호

이 명령은 클린룸의 차등 개인정보 보호를 제어합니다. consumer.enable_templates_for_provider_run 을 호출할 때 템플릿 수준에서 차등 개인정보 보호를 지정할 수도 있습니다.

차등 개인정보 관리에 대해 자세히 알아보기

consumer.is_dp_enabled

설명: 클린룸에서 차등 개인정보 보호가 활성화되었는지 확인합니다.

인자: cleanroom_name (string)

반환: 클린룸에 DP 활성화 여부 (boolean)

예제:

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
Copy

consumer.view_remaining_privacy_budget

설명: 클린룸에서 쿼리를 수행하는 데 사용할 수 있는 잔여 개인정보 보호 예산을 봅니다. 예산이 재설정될 때까지 run_analysis에 대한 추가 호출은 허용되지 않습니다. 예산은 매일 재설정됩니다.

SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;

인자: cleanroom_name (string)

반환: 남은 개인정보 보호 예산(부동 소수점)

예제:

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Copy

일반 도우미 메서드

일반적인 클린룸 기능을 지원하려면 다음 방법을 사용하십시오.

consumer.set_cleanroom_ui_accessibility

설명: 현재 계정의 컨슈머를 위해 웹 앱에서 클린룸을 표시하거나 숨깁니다.

인자:

  • cleanroom_name (string) - 클린룸의 이름입니다.

  • visibility_status (string) - 대소문자를 구분하는 다음 값 중 하나입니다.

    • HIDDEN - 웹 앱에서 지정된 클린룸을 현재 컨슈머 계정의 모든 사용자로부터 숨깁니다. 클린룸은 API 호출을 통해 계속 액세스할 수 있습니다.

    • EDITABLE - 웹 앱에서 클린룸을 표시합니다.

반환: 성공 메시지 (string)

예제:

call samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
Copy

library.enable_local_db_auto_upgrades

설명: 새 버전이 릴리스될 때 Snowflake Data Clean Rooms용 Snowflake Native App을 자동으로 업그레이드하는 작업 samooha_by_snowflake_local_db.admin.expected_version_task 를 활성화합니다.

인자: 없음

반환: 성공 메시지 (string)

예제:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
Copy

library.disable_local_db_auto_upgrades

설명: 새 버전이 릴리스될 때 Snowflake Data Clean Rooms용 Snowflake Native App을 자동으로 업그레이드하는 작업 samooha_by_snowflake_local_db.admin.expected_version_task 를 비활성화합니다.

인자: 없음

반환: 성공 메시지 (string)

예제:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();
Copy