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

環境の設定¶

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

結合ポリシーの設定¶

コンシューマーがデータに参加できるテンプレートをクリーンルームに追加する場合は、データに対して:ref:クリーンルームの結合ポリシー<label-dcr_join_policies>`を設定する必要があります。クリーンルームの結合ポリシーは、コラボレーターによって実行されたクエリでどの列が結合できるのかを指定:emph:`できます。データに結合ポリシーを設定しない場合、デフォルトですべての列が結合可能となっています。結合ポリシーで保護されている列は投影できません。独自の結合ポリシーは、独自のクエリを制約しません。

クリーンルームは、リンクされたデータ上で設定できる: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はいくつかの標準テンプレートを提供しますが、そのほとんどは UI でのみ使用可能です。したがって、コンシューマー（または自分自身）がAPIで実行できる独自のカスタムテンプレートを作成することになります。。

デフォルトでは、コンシューマーのみがテンプレートを実行できます。: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);

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

環境の設定¶

プロバイダーと同様に、コンシューマーは<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>');

データを追加してポリシーを設定する¶

クリーンルームテンプレートで、コンシューマーが自分のデータをクエリに含めることを許可している場合、コンシューマーはデータを登録し、データをリンクし、プロバイダーが行うのと同様のポリシーを設定します。次の例に示すように、これらのプロシージャについては``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
  )
);