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

環境の設定¶

APIを使用するには、SAMOOHA_APP_ROLEに権限があるウェアハウスを使用する必要があります。app_wh は、APIへのアクセス権がある:ref:`ウェアハウスの数 <label-cleanrooms_installation_details_warehouses>`のうちのひとつです。ニーズに適したウェアハウスを選択してください。（選択した場合は、: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']);

結合ポリシーの設定¶

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.

クリーンルームは、リンクされたデータ上で設定できる:doc:少数のデータポリシー </user-guide/cleanrooms/policies> をサポートします。これらのポリシーは、同等のSnowflakeポリシーと似ていますが、同じではありません。また、ソースデータではなく、内部ビューにのみ適用されます。ソースデータに設定されたすべてのSnowflakeポリシーは、データでリンクすると作成されるビューに伝播されます。クリーンルームのポリシーはリンクされたデータに対してのみ設定され、ソースデータには設定されません。

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

次の例は、リンクされたテーブルの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']);

結合ポリシーの詳細はこちら。

クリーンルームにテンプレートを追加する¶

クリーンルームテンプレートは、ほとんどの場合、SQLクエリに評価される有効なJinjaSQLです。テンプレート（分析 と呼ばれることもあります）は、呼び出し元によって引数が渡されることがあり、クリーンルームにリンクされた任意のデータにアクセスできます。プロバイダーもコンシューマーも、クリーンルームにテンプレートを追加して実行することができます。

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

Any clean room join or column policies that you set 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. For more information about policies, see 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);

これで、コンシューマーは次に説明するように、クリーンルームのインストール、データのリンク、ポリシーの設定、テンプレートの実行ができるようになります。

環境の設定¶

プロバイダーと同様に、コンシューマーは<label-cleanrooms_installation_details_warehouses>`にアクセスできる:ref:ウェアハウスSAMOOHA_APP_ROLEを使用する必要があります。ただし、プロバイダーとは異なり、コンシューマーはAPI に完全にアクセスするためにSAMOOHA_APP_ROLEロールを直接使用できます。または、そのアカウントのクリーンルーム管理者が、コンシューマー向けにAPIのサブセットを実行する権限を与える、より制限されたロールを付与できます。この制限されたロールは、一般的に「実行ロール」と呼ばれることもあり、クリーンルームの完全な権限を持つユーザーによって付与されます。:ref:`制限されたAPIアクセスを付与する方法について詳細はこちら<label-dcr_grant_limited_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);

プロバイダーがクリーンルームでテンプレートを実行するには、コンシューマーの承認が必要です。その結果、ほとんどのコンシューマーは、リンクするテーブルにポリシーを設定する手間がかかりません。

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