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

환경 설정¶

To use the API, you must use a warehouse that SAMOOHA_APP_ROLE has privileges in. app_wh is one of a number of warehouses with access to the API. Choose the warehouse that is appropriate for your needs. (You can also use your own warehouse, if you choose.)

The SAMOOHA_APP_ROLE role is required to access the API.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

클린룸 만들기¶

The next step is to create a new clean room. This is done with a single API call that specifies whether the clean room is for internal or external use. Internal clean rooms can be accessed only by consumers within the same organization; external clean rooms can be used by consumers outside the organization. For both clean room types, consumers must be invited to use the clean room to be able to access it.

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

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

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

데이터를 클린룸에 연결¶

Both the provider and consumer can link (import) tables, views, and other supported data objects into a clean room. When you link data, the API creates a hidden, secure view inside the clean room that is based on the linked source object. You reference the linked object by its source name, not its internal view name, in all clean room procedures.

Data linked into the clean room can’t be accessed directly by any clean room collaborators. Linked data is accessed using a template imported into the clean room (unless you enable free-form SQL queries on your data).

Before an object can be linked into a clean room, the object must be registered. Registering an object grants proper access privileges to the SAMOOHA_APP_ROLE on the object. You can either register an object directly, or register a parent object (such as a database or schema) to access child objects. You can register an object in either the UI or the API.

Objects are registered at the account level, not the clean room level; you need to register an object only once per account, and it can be linked into any clean room in the account. (You can link only objects registered in your own account.) After you register an object, the object is available for linking by any clean room in the account. Learn more about registration.

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

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

조인 정책 설정¶

If you add a template to the clean room that allows the consumer to join on your data, you should set a clean room join policy on your data. A clean room join policy specifies which columns can be joined on in queries run by collaborators. Your own join policies don’t constrain your own queries.

Clean rooms support a few types of data policies that you can set on linked data. These policies are similar to, but not the same as, the equivalent Snowflake policies, and are applied only on the internal view, not on the source data. Any Snowflake policies that are set on the source data are propagated to the views linked into a clean room. Clean room policies are set on the linked data only, not on the source data.

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

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

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

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

클린룸에 템플릿 추가¶

A clean room template is a valid JinjaSQL template that typically evaluates to a SQL query. A template, sometimes called an analysis, can be passed arguments by the caller, and can access any data linked into the clean room. Both providers and consumers can add templates into a clean room and run them.

Snowflake provides a few standard templates, but you will probably write your own custom templates.

Any clean room policies that you set are enforced only if the template includes policy filters in the template, so make sure that the templates you add to a clean room include these filters. For more information about policies, see Clean Room 테이블 정책 이해.

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

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

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

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

열 정책 설정¶

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

Column policies, like all policies, are overwrite-only; this means that setting column policies completely overwrites any existing column policies set by that account. Both the provider and the consumer can set column policies on their data. Learn more about column policies.

다음 예제에서는 이전에 연결된 클린룸 샘플 데이터베이스에서 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']);

컨슈머와 공유¶

Only consumers invited by the provider can access the clean room. Consumers can’t share a clean room with other consumers. Designated consumers can’t access the clean room until it is published. Invitations to join a clean room are at the account level, not at the user level.

다음 예제에서는 두 컨슈머와 클린룸을 공유하는 방법을 보여줍니다. 이 프로시저는 쉼표로 구분된 컨슈머 계정 로케이터 목록 및 컨슈머 데이터 공유 계정 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);

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

환경 설정¶

Like the provider, the consumer must use a warehouse that SAMOOHA_APP_ROLE can access. However, unlike the provider, the consumer can either use the SAMOOHA_APP_ROLE role directly for full API access, or a clean room administrator in that account can grant a more limited role that gives privileges to run a subset of the API for consumers. This limited role, sometimes generically called a “run role,” is granted by a user with full clean room privileges. Learn how to grant limited API access.

실행 역할로는 클린룸을 설치할 수 없으므로 다음 예제와 같이 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>');

데이터 추가 및 정책 설정¶

If the clean room templates allow the consumer to include their own data in a query, the consumer registers data, links data, and sets policies like the provider does. Be sure to use the consumer versions of the procedures, as shown in the following example:

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

A provider needs the consumer’s approval to run a template in the clean room. As a result, most consumers don’t bother setting policies on the tables that they link in. Nevertheless, we recommend that you consider adding policies in case a provider asks to run a template later, because you might forget to add appropriate policies at that time.

If you do set policies, they are enforced only if the template includes a join_policy or column_policy filter to the column in the template, so make sure that the templates you add to a clean room include these filters to enforce your policies. To examine the templates in a clean room, call consumer.view_added_templates. For more information about policies, see 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
);

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