기본 소비자 주도 데이터 분석이에요

서비스 종료 공지

레거시 Provider 및 Consumer Data Clean Rooms는 지원이 중단될 예정이에요. 날짜와 마이그레이션 안내는 서비스 종료 타임라인을 참고하세요.

출처: 문서

본문

개요

이 항목에서는 clean rooms API를 사용한 기본적인 소비자 실행 분석을 보여드려요. 이 예시는 공급자가 프로그래밍 방식으로 clean room을 만들고 데이터와 함께 공유하는 방법과, 소비자가 공급자의 데이터에 대해 분석을 실행하는 방법을 보여줘요. 공급자는 자신의 데이터에 대해 실행할 수 있는 SQL 쿼리를 정의해요. 공급자는 공급자의 데이터만 조회하는 쿼리, 소비자의 데이터만 조회하는 쿼리, 또는 공급자와 소비자 데이터를 조인하는 쿼리를 정의할 수 있어요.

전체 코드 예시를 다운로드하여 Snowflake 계정에 업로드하고 실행할 수 있어요.

다음 다이어그램은 기본적인 소비자 실행 분석에서 주요 구성 요소를 통한 데이터 흐름을 보여줘요.

두 당사자가 참여하는 기본적인 소비자 실행 분석에서 공급자와 소비자는 데이터를 clean room에 링크해요. 이 데이터는 소비자 계정의 clean room 애플리케이션 패키지에 있는 소비자 DB에 저장된 보안 뷰를 통해 액세스돼요.

분석 중에 소비자 계정의 clean room 앱은 지정된 소비자 및 공급자 보안 뷰를 사용하며, 결과는 소비자와 공유돼요.

공급자 단계

다음 목록은 clean room을 만들고 게시하고 소비자와 공유하는 주요 단계를 보여줘요.

환경 설정
Clean room 만들기
Clean room에 데이터 링크
조인 정책 설정
Clean room에 템플릿 추가
열 정책 설정
소비자와 공유
기본 버전 설정
Clean room 게시

환경 설정

API를 사용하려면 SAMOOHA_APP_ROLE에 권한이 있는 웨어하우스를 사용해야 해요. app_wh는 API에 액세스할 수 있는 여러 웨어하우스 중 하나예요. 필요에 맞는 웨어하우스를 선택하세요. (원한다면 자체 웨어하우스를 사용할 수도 있어요.)

API에 액세스하려면 SAMOOHA_APP_ROLE 역할이 필요해요.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Clean room 만들기

다음 단계는 새 clean room을 만드는 거예요. 이 작업은 clean room이 내부용인지 외부용인지 지정하는 단일 API 호출로 수행돼요. 내부 clean room은 같은 조직 내 소비자만 액세스할 수 있고, 외부 clean room은 조직 외부의 소비자도 사용할 수 있어요. 두 clean room 유형 모두 소비자가 액세스하려면 clean room을 사용하도록 초대받아야 해요.

외부 clean room은 특정 작업이 수행될 때 추가 보안 검사를 트리거해요. 이 경우 보안 검사가 완료되는 시점을 확인하려면 provider.view_cleanroom_scan_status를 호출해야 하며, 그런 다음 다음 작업을 계속할 수 있어요.

다음 예시는 내부 clean room을 만들어요.

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

Clean room에 데이터 링크

공급자와 소비자 모두 테이블, 뷰 및 기타 지원되는 데이터 객체를 clean room에 링크(가져오기)할 수 있어요. 데이터를 링크하면 API는 링크된 소스 객체를 기반으로 clean room 내부에 숨겨진 보안 뷰를 만들어요. 모든 clean room 프로시저에서 링크된 객체는 내부 뷰 이름이 아닌 소스 이름으로 참조해요.

clean room에 링크된 데이터는 clean room 협업자 누구도 직접 액세스할 수 없어요. 링크된 데이터는 clean room에 가져온 템플릿을 사용하여 액세스해요 (데이터에 대해 자유 형식 SQL 쿼리를 활성화하지 않은 경우예요).

객체를 clean room에 링크하려면 먼저 객체를 등록해야 해요. 객체를 등록하면 해당 객체에 대한 적절한 액세스 권한이 SAMOOHA_APP_ROLE에 부여돼요. 객체를 직접 등록하거나, 하위 객체에 액세스하기 위해 상위 객체(예: 데이터베이스 또는 스키마)를 등록할 수 있어요. 객체는 UI 또는 API에서 등록할 수 있어요.

팁

등록은 API보다 UI에서 수행하고 관리하는 것이 더 쉬워요.

객체는 clean room 수준이 아니라 계정 수준에서 등록돼요. 계정당 객체를 한 번만 등록하면 되며, 해당 계정의 모든 clean room에 링크할 수 있어요. (자신의 계정에 등록된 객체만 링크할 수 있어요.) 객체를 등록하면 해당 객체는 계정의 모든 clean room에서 링크할 수 있게 돼요. 등록에 대해 자세히 알아보기.

다음 예시는 샘플 데이터베이스 SAMOOHA_SAMPLE_DATABASE의 CUSTOMERS 테이블을 링크해요. 이 데이터베이스는 계정에 clean room 환경을 설치할 때 자동으로 등록되므로 별도로 등록할 필요가 없어요. clean room에서 언제든지 객체를 링크하거나 링크를 해제할 수 있으며, 결과는 모든 협업자에게 빠르게 전파돼요.

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

조인 정책 설정

clean room에 소비자가 여러분의 데이터에 조인할 수 있는 템플릿을 추가한다면, 데이터에 clean room 조인 정책을 설정해야 해요. clean room 조인 정책은 협업자가 실행하는 쿼리에서 조인할 수 있는 열을 지정해요. 여러분 자신의 조인 정책은 여러분 자신의 쿼리를 제한하지 않아요.

clean room은 연결된 데이터에 설정할 수 있는 몇 가지 유형의 데이터 정책을 지원해요. 이러한 정책은 해당하는 Snowflake 정책과 유사하지만 동일하지는 않으며, 내부 뷰에만 적용되고 원본 데이터에는 적용되지 않아요. 원본 데이터에 설정된 Snowflake 정책은 clean room에 연결된 뷰로 전파돼요. clean room 정책은 연결된 데이터에만 설정되며 원본 데이터에는 설정되지 않아요.

중요

템플릿은 JinjaSQL 필터를 사용하여 정책을 적용할 책임이 있어요. 템플릿이 정책 필터를 사용하지 않으면 정책이 준수되지 않아요. 여러분이 작성하는 템플릿에는 항상 정책 필터를 넣고, 실행하는 템플릿이 clean room 정책을 적용하는지 확인하기 위해 템플릿을 검토하세요.

정책은 여러분이 연결하는 데이터에만 설정할 수 있어요. 다른 당사자의 데이터에는 정책을 설정할 수 없어요.

다음 예시는 연결된 테이블의 두 열을 조인 가능하게 허용하는 조인 정책을 설정하는 방법을 보여줘요:

CALL samooha_by_snowflake_local_db.provider.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
   'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_PHONE']);

조인 정책에 대해 자세히 알아보기.

clean room에 템플릿 추가

clean room 템플릿은 일반적으로 SQL 쿼리로 평가되는 유효한 JinjaSQL 템플릿이에요. analysis라고도 불리는 템플릿은 호출자가 인수를 전달할 수 있고, clean room에 연결된 모든 데이터에 접근할 수 있어요. 공급자와 소비자 모두 clean room에 템플릿을 추가하고 실행할 수 있어요.

Snowflake는 몇 가지 표준 템플릿을 제공하지만, 여러분은 아마 직접 커스텀 템플릿을 작성하게 될 거예요.

여러분이 설정한 clean room 정책은 템플릿에 정책 필터가 포함된 경우에만 적용돼요. 그러니 clean room에 추가하는 템플릿에 이러한 필터가 포함되어 있는지 확인하세요. 정책에 대한 자세한 내용은 Snowflake Data Clean Room 정책 이해를 참조하세요.

기본적으로 소비자만 템플릿을 실행할 수 있어요. 공급자가 템플릿을 실행하려면 소비자에게 허락을 받아야 해요. 마찬가지로 소비자가 템플릿을 업로드하려면 공급자에게 허락을 받아야 해요.

커스텀 템플릿 생성에 대한 자세한 내용은 clean room에 커스텀 템플릿 추가 및 커스텀 템플릿 설계를 읽어보세요.

다음 예시는 Snowflake 제공 템플릿을 clean room에 추가하는 방법을 보여줘요:

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['prod_overlap_analysis']);

열 정책 설정

clean room 열 정책은 협업자가 실행하는 쿼리에서 여러분의 테이블에서 프로젝션할 수 있는 열을 지정해요. 열 정책은 열과 템플릿 모두에 연결되므로, 템플릿에 따라 서로 다른 열을 프로젝션 가능하게 정의할 수 있어요. 특정 템플릿에 대한 열 정책을 설정하려면 먼저 해당 템플릿이 clean room에 존재해야 해요.

열 정책은 다른 모든 정책과 마찬가지로 overwrite-only(덮어쓰기 전용)이에요. 즉, 열 정책을 설정하면 해당 계정이 설정한 기존 열 정책을 완전히 덮어써요. 공급자와 소비자 모두 자신의 데이터에 열 정책을 설정할 수 있어요. 열 정책에 대해 자세히 알아보기.

다음 예시는 이전에 연결한 clean rooms 샘플 데이터베이스에서 네 개의 열을 프로젝션할 수 있도록 허용하는 방법을 보여줘요:

CALL samooha_by_snowflake_local_db.provider.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.CUSTOMERS:REGION_CODE']);

소비자와 공유

공급자가 초대한 소비자만 clean room에 접근할 수 있어요. 소비자는 다른 소비자와 clean room을 공유할 수 없어요. 지정된 소비자는 clean room이 게시될 때까지 접근할 수 없어요. clean room 참여 초대는 사용자 수준이 아니라 계정 수준으로 이루어져요.

다음 예시는 두 소비자와 clean room을 공유하는 방법을 보여줘요. 이 프로시저는 소비자 계정 로케이터와 소비자 데이터 공유 계정 ID의 두 개의 병렬 쉼표로 구분된 목록을 사용해요.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

다른 클라우드 호스팅 리전의 소비자와 공유

소비자와 공급자가 서로 다른 클라우드 리전에 있는 경우, 공급자와 소비자는 소비자를 clean room에 추가하기 전에 cross-cloud auto-fulfillment를 활성화해야 해요. 자신의 클라우드 리전은 SELECT CURRENT_REGION();을 실행해서 확인할 수 있어요. 일반적으로 소비자의 리전은 볼 수 없지만, 다른 리전에 있는 소비자를 추가하려고 하면 provider.add_consumers가 문제를 알리는 메시지와 함께 실패해요. 이 오류가 발생하면 provider.remove_consumers를 호출해서 다른 리전에 있는 계정을 제거한 다음, cross-cloud auto-fulfillment를 활성화하고, 다시 교차 리전 계정을 추가해야 해요.

기본 버전 설정

Clean room은 버전이 지정된 네이티브 애플리케이션이에요. clean room에 코드를 추가하는 것과 같은 특정 작업은 애플리케이션의 새로운 패치 버전을 생성해요. 소비자는 자신의 계정에 clean room을 설치해야 해요. 설치하는 버전은 사용자가 지정한 기본 버전 번호를 기준으로 해요. 나중에 clean room의 새 버전을 게시하고 기본 버전 번호를 올리면, 소비자가 설치한 모든 버전이 자동으로 업데이트되고, 새 설치도 새 버전을 기본값으로 사용하게 돼요. clean room 버전 관리에 대해 자세히 알아보기.

다음 예제는 아직 코드를 업로드하지 않은 경우 clean room의 기본 버전을 초기 버전인 V1.0.0으로 설정하는 방법을 보여줘요.

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

clean room 게시

다음 예제와 같이 clean room을 게시하거나 다시 게시해요. 이 프로시저를 처음 호출하면 clean room이 공유한 모든 소비자에게 표시되고 설치 가능해져요. 기본 버전을 업데이트하거나 clean room UI에 특정한 변경 사항을 만들 때처럼 중요한 변경을 할 때마다 이 프로시저를 호출해야 해요.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

이제 소비자는 다음에 설명된 대로 clean room을 설치하고, 데이터를 연결하고, 정책을 설정하고, 템플릿을 실행할 수 있어요.

팁

더 이상 clean room이 필요하지 않으면 공급자 및 소비자 계정에서 clean room을 삭제해야 해요 (provider.drop_cleanroom 및 consumer.uninstall_cleanroom). 계정당 clean room 및 협업자 수에는 제한이 있어요. 사용하지 않는 clean room을 계정에 많이 남겨두면 할당량에 도달할 수 있어요.

소비자 단계

공급자가 clean room을 게시하면 협업자로 추가된 모든 소비자는 UI 또는 API를 사용하여 clean room을 보고 설치할 수 있어요. 이 섹션에서는 소비자가 API를 사용하여 clean room을 설치하고 분석을 실행하는 방법을 보여줘요.

소비자가 clean room을 설치하고 분석을 실행하기 위해 수행하는 단계를 간략히 요약하면 다음과 같아요.

환경 설정
clean room 설치
데이터 추가 및 정책 설정
분석 실행

환경 설정

공급자와 마찬가지로 소비자도 SAMOOHA_APP_ROLE이 액세스할 수 있는 웨어하우스를 사용해야 해요. 하지만 공급자와 달리 소비자는 SAMOOHA_APP_ROLE 역할을 직접 사용하여 전체 API에 액세스하거나, 해당 계정의 clean room 관리자가 소비자에게 API의 일부를 실행할 수 있는 권한을 부여하는 더 제한된 역할을 부여할 수 있어요. 이 제한된 역할은 일반적으로 "실행 역할"이라고도 불리며, clean room 전체 권한을 가진 사용자가 부여해요. 제한된 API 액세스를 부여하는 방법 알아보기.

실행 역할로는 clean room을 설치할 수 없어요. 따라서 다음 예제와 같이 SAMOOHA_APP_ROLE을 사용해야 해요.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

clean room 설치

다음 스니펫은 설치된 clean room과 설치하도록 초대받은 clean room을 모두 나열하는 방법을 보여줘요.

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

다음 예제와 같이 공급자가 공유한 clean room을 설치해요. clean room을 설치할 때는 공급자의 계정 로케이터를 지정해야 해요.

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

팁

Clean room에는 이름과 ID가 모두 있어요. API를 사용하여 만든 clean room의 경우, API 프로시저에서 clean room 이름이 필요하면 clean room 이름을 사용해요. UI에서 만든 clean room의 경우, API 프로시저에서 clean room 이름이 필요하면 이름 대신 clean room ID를 사용해요.

clean room UI는 API를 사용하여 만든 clean room을 Supported with Developer APIs로 표시해요.

데이터 추가 및 정책 설정

clean room 템플릿에서 소비자가 쿼리에 자신의 데이터를 포함할 수 있다면, 소비자는 공급자와 마찬가지로 데이터를 등록하고, 데이터를 연결하고, 정책을 설정해요. 다음 예제와 같이 프로시저의 consumer 버전을 사용해야 해요.

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MY_DATABASE.PUBLIC.EXPOSURES'
  ]);

공급자의 조인 정책은 어떤 공급자 열을 조인할 수 있는지 보여줘요. 다음 예제는 조인할 수 있는 공급자 열을 확인하는 방법을 보여줘요.

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

공급자가 clean room에서 템플릿을 실행하려면 소비자의 승인이 필요해요. 그래서 대부분의 소비자는 연결한 테이블에 굳이 정책을 설정하지 않아요. 그렇지만 나중에 공급자가 템플릿 실행을 요청할 경우를 대비해 정책 추가를 고려해 보는 것이 좋아요. 그때 적절한 정책을 추가하는 것을 잊어버릴 수 있기 때문이에요.

정책을 설정하는 경우, 해당 정책은 템플릿에 join_policy 또는 column_policy 필터가 템플릿의 열에 포함되어 있을 때만 적용돼요. 따라서 clean room에 추가하는 템플릿에 이러한 필터가 포함되어 정책을 적용할 수 있도록 해야 해요. clean room의 템플릿을 살펴보려면 consumer.view_added_templates를 호출하세요. 정책에 대한 자세한 내용은 Understanding Snowflake Data Clean Room policies를 참조하세요.

분석 실행

템플릿을 실행하기 전에 일반적으로 템플릿이 수행하는 작업과 허용하는 변수를 확인한 다음, clean room에서 사용할 수 있는 provider 테이블을 확인해요.

템플릿 살펴보기

clean room에 있는 템플릿을 나열하고 각 템플릿의 코드를 살펴볼 수 있어요. 단, provider가 명시적으로 obfuscated the code하지 않은 경우에요. 이렇게 하면 쿼리를 더 잘 이해하는 데 도움이 될 수 있어요. 또한 clean room에 템플릿을 파싱하고 코드를 실행할 때 전달할 수 있는 변수를 표시하도록 요청할 수도 있어요.

템플릿 설계에 따라 쿼리에서 사용할 테이블 목록을 전달할 수 있어요. clean room에 연결된 모든 테이블을 템플릿에 전달할 수 있답니다.

많은 템플릿은 실행 시 지정할 수 있는 변수도 지원해요. 예를 들어 특정 값을 매칭하거나 표시할 열을 지정하는 데 사용할 수 있죠. 이상적으로는 provider가 템플릿이 수행하는 작업과 허용하는 인수를 알려줘야 해요. 하지만 일반적으로 템플릿 코드를 살펴보고 싶을 때도 있죠. 다음 스니펫은 clean room에 참여한 협력자가 추가한 템플릿을 나열하고, 특정 템플릿에서 지원하는 인수를 가져와요.

-- View the list of templates available in this clean room,
-- and the source code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

팁

템플릿에서 my_table 배열 변수를 보게 된다면, 이 변수는 템플릿을 실행할 때 전달하는 consumer 테이블 이름 목록을 보관해요. source_table 배열 변수를 보게 된다면, 이 변수는 템플릿을 실행할 때 전달하는 provider 테이블 이름 목록을 보관해요.

사용 가능한 데이터 확인하기

다음 예제와 같이 사용자와 provider가 clean room에 연결한 데이터셋을 나열할 수 있어요:

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

테이블 이름을 전달할 때는 이러한 프로시저의 결과에서 뷰 이름이 아닌 테이블 이름을 사용하세요.

템플릿 실행하기

앞의 두 단계에서 보유한 데이터와 전달할 수 있는 변수를 확인했어요. 이제 분석을 실행할 준비가 되었답니다.

쿼리와 데이터 크기에 따라 웨어하우스 크기를 something more appropriate로 변경하고 싶을 수도 있어요.

다음 예제는 consumer 테이블과 provider 테이블을 모두 사용하고 두 개의 변수, 즉 그룹화 열로 사용되는 dimensions와 쿼리의 WHERE 절에서 사용되는 선택적 where_clause를 받는 템플릿을 호출하는 방법을 보여줘요.

이 템플릿은 단일 provider 테이블에 대해 쿼리를 실행하므로 요청에서 consumer 테이블은 생략돼요.

다음 예제에서 dimensions 값이 p로 접두사가 붙은 열 이름임을 확인해 보세요. p는 이 열이 전달된 provider 테이블에서 온 것임을 나타내요. 열 이름은 일반적으로 provider 또는 consumer 중 어떤 테이블에서 왔는지 구분하기 위해 p 또는 c를 추가해야 해요. 하지만 이 요구 사항은 템플릿에 따라 매우 달라져요. 이러한 접두사가 필요한 시점을 이해하려면 템플릿 제공자와 소통하거나 템플릿 코드를 살펴봐야 해요.

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);

예제 코드

다음 워크시트 파일은 clean room 분석을 생성, 공유, 실행하는 방법을 보여줘요.

다음 예제를 다운로드한 다음 Snowflake 계정에 워크시트 파일로 업로드하세요. provider와 consumer 각각에 clean rooms API가 설치된 별도의 계정이 필요해요. SQL 워크시트를 Snowflake 계정에 업로드하는 방법은 See instructions to upload a SQL worksheet into your Snowflake account를 참조하세요.

기본 소비자 주도 데이터 분석이에요