기본 컨슈머 실행 데이터 분석¶

환경 설정¶

API를 사용하려면 SAMOOHA_APP_ROLE에 권한이 있는 웨어하우스를 사용해야 합니다. ``app_wh``는 API에 대한 액세스 권한이 있는 웨어하우스 중 하나입니다. 요구 사항에 적합한 웨어하우스를 선택합니다. (선택하는 경우 :ref:`자체 웨어하우스를 사용<label-cleanrooms_admin_add_warehouse>`할 수도 있습니다.)

API에 액세스하려면 samooha_app_role 역할이 필요합니다.

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

클린룸 만들기¶

다음 단계는 새로운 클린룸을 만드는 것입니다. 이 작업은 클린룸이 내부용인지 외부용인지를 지정하는 단일 API 호출로 수행됩니다. 내부 클린룸은 같은 조직 내의 컨슈머만 액세스할 수 있습니다. 외부 클린룸은 조직 외부의 컨슈머가 사용할 수 있습니다. 두 유형 모두에서 컨슈머가 클린룸에 액세스하려면 초대를 받아야 합니다.

외부 클린룸은 특정 작업이 수행될 때 추가 보안 검사를 트리거합니다. 이 경우 ``provider.view_cleanroom_scan_status``를 호출하여 보안 검사가 완료된 시점을 확인하고, 다음 작업을 계속할 수 있습니다.

다음 예에서는 내부 클린룸을 만듭니다.

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

데이터를 클린룸에 연결¶

공급자와 컨슈머 모두 테이블, 뷰 및 :ref:`지원되는 기타 데이터 오브젝트<label-dcr_supported_linkable_objects>`를 클린룸으로 *연결*(가져오기)할 수 있습니다. 데이터를 연결하면 API는 지정된 원본 오브젝트를 기준으로 클린룸 내부에 뷰를 만듭니다. 그러나 모든 클린룸 프로시저에서는 연결된 오브젝트를 내부 뷰 이름이 아닌 원본 이름으로 참조해야 합니다.

클린룸에 연결된 데이터는 클린룸 공동 작업자가 직접 액세스할 수 없으며, 클린룸 내의 템플릿을 사용해야만 액세스할 수 있습니다.

오브젝트를 클린룸에 연결하려면 먼저 해당 오브젝트를 *등록*해야 합니다. 오브젝트를 등록하면 SAMOOHA_APP_ROLE에 오브젝트에 대한 적절한 액세스 권한이 부여됩니다. 오브젝트를 직접 등록하거나 포함하는 오브젝트(예: 데이터베이스 또는 스키마)를 등록하여 하위 오브젝트에 액세스할 수 있습니다. UI또는 API에서 오브젝트를 등록할 수 있으며, 등록은 클린룸 수준이 아닌 계정 수준에서 이루어집니다. UI에서 등록을 더 쉽게 수행하고 관리할 수 있습니다. 오브젝트를 등록하면 계정의 모든 클린룸에서 해당 오브젝트에 연결할 수 있습니다. 등록에 대해 자세히 알아보세요.

다음 예제는 샘플 데이터베이스 SAMOOHA_SAMPLE_DATABASE의 CUSTOMERS 테이블에 연결합니다. 이 데이터베이스는 계정에 클린룸 환경을 설치할 때 자동으로 등록되므로 등록할 필요가 없습니다. 클린룸에서 언제든지 오브젝트를 연결하거나 연결 해제할 수 있으며, 결과는 모든 공동 작업자에게 빠르게 전파됩니다.

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

조인 정책 설정¶

컨슈머가 데이터를 조인할 수 있는 템플릿을 클린룸에 추가하는 경우 데이터에 대해 :ref:`클린룸 조인 정책<label-dcr_join_policies>`을 설정해야 합니다. 클린룸 조인 정책은 공동 작업자가 실행하는 쿼리에서 조인 :emph:`가능`한 열을 지정합니다. 데이터에 조인 정책을 설정하지 않으면 기본적으로 모든 열을 조인할 수 있습니다. 조인 정책으로 보호되는 열은 프로젝션할 수 없습니다. 자체 조인 정책은 자체 쿼리를 제한하지 않습니다.

클린룸은 연결된 데이터에 설정할 수 있는 :doc:`몇 가지 데이터 정책</user-guide/cleanrooms/policies>`을 지원합니다. 이러한 정책은 해당하는 Snowflake 정책과 유사하지만 동일하지는 않으며, 원본 데이터가 아닌 내부 뷰에만 적용됩니다. 원본 데이터에 설정된 모든 Snowflake 정책은 데이터에 연결할 때 만들어지는 뷰에 전파됩니다. 클린룸 정책은 원본 데이터가 아닌 연결된 데이터에만 설정됩니다.

연결하는 데이터에 대해서만 정책을 설정할 수 있으며 다른 당사자의 데이터에 대해서는 정책을 설정할 수 없습니다.

다음 예에서는 연결된 테이블의 두 열을 조인할 수 있도록 허용하는 조인 정책을 설정하는 방법을 보여줍니다.

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']);

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

클린룸에 템플릿 추가¶

클린룸 템플릿은 거의 항상 SQL 쿼리로 평가되는 유효한 JinjaSQL 템플릿입니다. *분석*이라고도 하는 템플릿은 호출자를 통해 인자를 전달할 수 있으며, 클린룸에 연결된 모든 데이터에 액세스할 수 있습니다. 공급자와 컨슈머 모두 클린룸에 템플릿을 추가하고 실행할 수 있습니다.

Snowflake는 몇 가지 표준 템플릿을 제공하지만, 대부분은 UI에서만 사용할 수 있습니다. 따라서 컨슈머(또는 사용자 본인)가 API에서 실행할 수 있는 자체 사용자 지정 템플릿을 작성할 것입니다.

기본적으로 컨슈머만 템플릿을 실행할 수 있습니다. 공급자가 템플릿을 실행하려고 하는 경우 컨슈머에게 권한을 요청해야 합니다. 마찬가지로, 컨슈머가 템플릿을 업로드하려고 하는 경우 공급자에게 허가를 요청해야 합니다.

사용자 지정 템플릿을 만드는 방법에 대한 자세한 내용은 클린룸에 사용자 지정 템플릿 추가 및 사용자 지정 클린룸 템플릿 참조 섹션을 참조하세요.

다음 예제에서는 Snowflake에서 제공하는 템플릿을 클린룸에 추가하는 방법을 보여줍니다.

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

열 정책 설정¶

클린룸 열 정책은 공동 작업자가 실행하는 쿼리에 프로젝션할 수 있는 테이블의 열을 지정합니다. 열 정책은 열과 템플릿 모두에 연결되므로, 서로 다른 열을 프로젝션 가능하도록 정의하려면 서로 다른 템플릿을 사용하면 됩니다. 해당 템플릿에 대한 열 정책을 설정하려면 먼저 템플릿이 클린룸에 있어야 합니다.

모든 정책과 마찬가지로 열 정책은 *덮어쓰기 전용*입니다. 즉, 열 정책을 설정하면 해당 계정에서 설정한 기존 열 정책을 완전히 덮어씁니다. 공급자와 컨슈머 모두 자신의 데이터에 열 정책을 설정할 수 있습니다. 데이터에 대한 열 정책을 지정하지 않으면 모든 열이 프로젝션될 수 있습니다. 열 정책에 대해 자세히 알아보세요.

다음 예제에서는 이전에 연결된 클린룸 샘플 데이터베이스에서 4개의 열을 프로젝션하도록 하는 방법을 보여줍니다.

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']);

컨슈머와 공유¶

공급자는 컨슈머 역할로 클린룸에 액세스할 수 있는 사용자를 정의합니다. 지정된 컨슈머는 클린룸이 게시될 때까지 클린룸에 액세스할 수 없습니다. 공급자가 추가한 계정만 클린룸에 액세스할 수 있습니다. 컨슈머는 다른 컨슈머와 클린룸을 공유할 수 없습니다.

다음 예제에서는 두 컨슈머와 클린룸을 공유하는 방법을 보여줍니다. 이 프로시저는 쉼표로 구분된 컨슈머 계정 로케이터 목록 및 컨슈머 데이터 공유 계정 IDs 목록을 나란히 사용합니다.

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');

기본 버전 설정¶

클린룸은 버전이 지정된 네이티브 애플리케이션입니다. 클린룸에 코드를 추가하는 등의 특정 작업은 애플리케이션의 새 패치 버전을 생성합니다. 컨슈머는 자신의 계정에 클린룸을 설치해야 합니다. 컨슈머가 설치하는 버전은 사용자가 지정하는 기본 버전 번호를 기준으로 합니다. 나중에 클린룸의 새 버전을 게시하고 기본 버전 번호를 증분하면 컨슈머가 설치한 모든 버전이 자동으로 업데이트되며, 새 설치 시 기본적으로 새 버전이 적용됩니다. 클린룸 버전 관리에 대해 자세히 알아보세요.

다음 예제에서는 코드를 업로드하지 않은 경우 클린룸의 기본 버전을 클린룸의 초기 버전인 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.
  );

클린룸 게시¶

다음 예제와 같이 클린룸을 게시하거나 다시 게시합니다. 이 프로시저를 처음 호출하면 사용자가 클린룸을 공유한 모든 컨슈머가 클린룸을 보고 설치할 수 있습니다. 기본 버전을 업데이트하거나 클린룸 UI를 변경할 때와 같이 중요한 변경을 할 때마다 이 프로시저를 호출해야 합니다.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

이제 컨슈머는 다음에 설명된 대로 클린룸을 설치하고, 데이터를 연결하고, 정책을 설정하고, 템플릿을 실행할 수 있습니다.

환경 설정¶

공급자와 마찬가지로 컨슈머는 SAMOOHA_APP_ROLE에서 액세스할 수 있는 웨어하우스

실행 역할로는 클린룸을 설치할 수 없으므로 다음 예제와 같이 SAMOOHA_APP_ROLE을 사용해야 합니다.

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

클린룸 설치¶

다음 코드 조각은 설치된 클린룸 중 설치하도록 요청받은 클린룸을 모두 나열하는 방법을 보여줍니다.

-- 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;

다음 예제와 같이 공급자가 사용자에게 공유한 클린룸을 설치합니다. 클린룸을 설치할 때 공급자의 계정 로케이터를 지정해야 합니다.

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

데이터 추가 및 정책 설정¶

클린룸 템플릿이 컨슈머가 쿼리에 자신의 데이터를 포함하도록 허용하는 경우 컨슈머는 공급자가 수행하는 방식과 유사한 방식으로 데이터를 등록하고 데이터를 연결하며 정책을 설정합니다. 다음 예제와 같이 해당 프로시저의 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);

공급자가 클린룸에서 템플릿을 실행하려면 컨슈머의 승인이 필요합니다. 결과적으로, 대부분의 컨슈머는 연결하는 테이블에 대해 정책을 설정하지 않아도 됩니다.

그럼에도 불구하고 공급자가 나중에 템플릿을 실행하도록 요청할 때 적절한 정책을 추가하는 것을 잊어버릴 수 있으므로 미리 정책을 추가하는 것이 좋습니다. 데이터에 조인 또는 열 속성을 설정하지 않으면 모든 열을 조인하고 프로젝션할 수 있습니다.

분석 실행¶

템플릿을 실행하기 전에 일반적으로 템플릿을 검사하여 어떤 작업을 수행하고 어떤 변수를 수락하는지 확인한 다음, 클린룸에서 사용할 수 있는 공급자 테이블을 검사합니다.

-- View the templates available in this clean room.
-- Also shows the template 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
);

-- 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);

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
  )
);