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

環境の設定¶

API を使用するには、 SAMOOHA_APP_ROLE に権限があるウェアハウスを使用する必要があります。app_whは API へのアクセス権がある 多くのウェアハウス のうちの1つです。ニーズに適したウェアハウスを選択してください。（選択した場合は、 :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 はクリーンルーム内に、リンクされたソースオブジェクトに基づいて非表示のセキュアなビューを作成します。すべてのクリーンルームプロシージャにおいて、内部のビュー名ではなく、ソース名でリンクされたオブジェクトを参照します。

クリーンルームにリンクされたデータは、クリーンルームのコラボレーターが直接アクセスすることはできません。リンクされたデータには、クリーンルームにインポートされたテンプレートを使用してアクセスします（データについて フリーフォーム SQL クエリ を有効にしない限り）。

オブジェクトをクリーンルームにリンクする前に、オブジェクトを 登録 する必要があります。オブジェクトを登録すると、そのオブジェクトに対して SAMOOHA_APP_ROLEに適切なアクセス権限が付与されます。オブジェクトを直接登録することも、子オブジェクトにアクセスする親オブジェクト（データベースやスキーマなど）を登録することもできます。オブジェクトは UI または API のいずれかを使って登録できます。

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

次の例は、サンプルデータベース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:`できます `。独自の結合ポリシーは、独自のクエリを制約しません。

クリーンルームは、リンクされたデータについて設定できる いくつかのタイプのデータポリシー をサポートしています。これらのポリシーは、同等の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はいくつかの標準テンプレートを提供しますが、おそらく独自のカスタムテンプレートを作成することになります。

設定したクリーンルームポリシーは、テンプレートにポリシーフィルターが含まれている場合にのみ強制されます。したがって、クリーンルームに追加するテンプレートにこれらのフィルターが確実に含まれるようにしてください。ポリシーの詳細については、 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']);

列ポリシーを設定する¶

クリーンルームの列ポリシーは、コラボレーターが実行するクエリで、テーブルのどの列を投影できるかを指定します。列ポリシーは列とテンプレートの両方に関連付いているため、異なる列を異なるテンプレートで投影可能として定義できます。テンプレートは、そのテンプレートの列ポリシーを設定する前に、クリーンルームに存在する必要があります。

すべてのポリシーと同様に、列ポリシーは 上書き専用 です。これは、列ポリシーを設定すると、そのアカウントによって設定された既存の列ポリシーが完全に上書きされることを意味します。プロバイダーもコンシューマーも、データに列ポリシーを設定できます。列ポリシーの詳細はこちら。

次の例は、以前にリンクしたクリーンルームのサンプルデータベースから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);

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

環境の設定¶

プロバイダーと同様に、コンシューマーは SAMOOHA_APP_ROLE がアクセスできるウェアハウス を使用する必要があります。ただし、プロバイダーとは異なり、コンシューマーについては、SAMOOHA_APP_ROLE ロールを直接使用して完全な API アクセスを得るか、または、そのアカウントのクリーンルーム管理者から API のサブセットを実行する権限を与えるより制限されたロールを付与してもらうかのいずれかになります。この制限されたロールは、一般的に「実行ロール」と呼ばれることもあり、クリーンルームの完全な権限を持つユーザーによって付与されます。 制限された API アクセスを付与する方法をご確認ください。

実行ロールではクリーンルームをインストールできないため、次の例に示すように、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);

プロバイダーがクリーンルームでテンプレートを実行するには、コンシューマーの承認が必要です。その結果、ほとんどのコンシューマーには、リンクするテーブルにポリシーを設定する手間がかかりません。ただし、プロバイダーが後でテンプレートの実行を求めた場合に備えて、ポリシーの追加を検討することをお勧めします。その時点では適切なポリシーを追加することを忘れる可能性があるためです。

ポリシーを設定すると、テンプレートにテンプレートの列に対する 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
  )
);