基本的なコンシューマーが実行するデータ分析¶

環境の設定¶

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.

オブジェクトはクリーンルームレベルではなく、アカウントレベルで登録されます。オブジェクトはアカウントごとに1回だけ登録する必要があり、アカウント内の任意のクリーンルームにリンクできます。（自分のアカウントに登録されているオブジェクトのみをリンクできます。）オブジェクトを登録すると、そのアカウント内のどのクリーンルームでもそのオブジェクトをリンクすることができます。登録の詳細はこちら。

次の例は、サンプルデータベース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.

ポリシーは、リンクしたデータにのみ設定できます。他の関係者のデータにポリシーを設定することはできません。

次の例は、リンクされたテーブルの2つの列が結合可能となるように許可する結合ポリシーを設定する方法を示しています。

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.

設定したクリーンルームポリシーは、テンプレートにポリシーフィルターが含まれている場合にのみ強制されます。したがって、クリーンルームに追加するテンプレートにこれらのフィルターが確実に含まれるようにしてください。ポリシーの詳細については、 clean roomテーブルのポリシーを理解する をご参照ください。

デフォルトでは、コンシューマーのみがテンプレートを実行できます。:doc:`プロバイダーがテンプレートの実行を希望する</user-guide/cleanrooms/demo-flows/provider-run-analysis>`場合は、コンシューマーに権限を求める必要があります。同様に、:ref:`コンシューマーがテンプレートのアップロードを希望する<label-dcr_consumer_written_templates>`場合、プロバイダーに権限を求める必要があります。

カスタムテンプレートの作成について、詳細は:doc:/user-guide/cleanrooms/demo-flows/custom-templates`および:doc:/user-guide/cleanrooms/custom-templates`をご参照ください。

次の例は、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']);

コンシューマーと共有する¶

プロバイダーから招待されたコンシューマーのみがクリーンルームにアクセスできます。コンシューマーは、他のコンシューマーとクリーンルームを共有することはできません。指定されたコンシューマーは、クリーンルームが公開されるまでクリーンルームにアクセスできません。クリーンルームへの参加招待は、ユーザーレベルではなく、アカウントレベルです。

次の例は、2人のコンシューマーとクリーンルームを共有する方法を示しています。プロシージャは、コンシューマーアカウントロケーターと:ref:コンシューマーデータ共有アカウント IDs<label-account_name_data_sharing> の2つの並列のコンマ区切りリストを取得します。

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.

ポリシーを設定すると、テンプレートにテンプレートの列に対する join_policy または column_policy フィルターが含まれている場合にのみポリシーが強制されます。したがって、クリーンルームに追加するテンプレートには、ポリシーを強制するこれらのフィルターが確実に含まれるようにしてください。クリーンルームのテンプレートを調べるには、 consumer.view_added_templates を呼び出します。ポリシーの詳細については、 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
  )
);