クエリ テンプレートを使用する

BigQuery データ クリーンルームのクエリ テンプレートを使用すると、分析情報を得るまでの時間を短縮できます。また、セキュリティと制御のレイヤが追加されるため、データ漏洩の懸念を最小限に抑えることができます。データ クリーンルームで実行できるクエリを事前に定義して制限することで、次のことができます。

• 機密データの漏洩を防ぐ。クリーンルームでクエリを実行しているサブスクライバーに柔軟な探索権限が付与されると、データオーナーは機密情報の偶発的または意図的な漏洩のリスクが高まると感じます。

• 技術に詳しくないユーザーのオンボーディングと導入を簡素化します。多くのデータ プロバイダは、クリーンルームのサブスクライバーは技術的な熟練度が低いと想定しています。特に、プライバシー重視の SQL クエリの作成や、プライバシー バジェットの適切な割り当て方法の理解については、熟練度が低いと想定しています。

• データ サブスクライバーに一貫した分析結果を保証します。データ クリーンルームで実行されているクエリを制御する方法がない場合、特定のデータ分析ルールを適用し、プライバシー規制への準拠を確認することが難しくなります。

クエリ テンプレートを使用すると、データ所有者と投稿者は、データ クリーンルームのユースケースに合わせて調整された事前定義済みの承認済みクエリを作成し、サブスクライバーが使用できるように公開できます。事前定義されたクエリは、BigQuery のテーブル値関数（TVF）を使用して、テーブル全体または特定のフィールドを入力パラメータとして渡し、テーブルを出力として返します。

制限事項

• クエリ テンプレートでサポートされるデータ参照は最大 2 つです。つまり、TVF のクエリの定義に使用されるデータと、TVF で受け入れられるデータ パラメータ入力です。
  • TVF のクエリ定義内で複数のテーブルまたはビューを参照できますが、それらはすべて同じデータ所有者または当事者に属している必要があります。
• クエリ テンプレート TVF は、TABLE と VIEW の固定型のみをサポートします。
• クエリ テンプレート定義には、TVF と同じ制限が適用されます。

始める前に

次の手順で、 Cloud de Confiance プロジェクトの Analytics Hub API を有効にします。

gcloud services enable analyticshub.googleapis.com

必要なロール

このドキュメントのタスクの実行に必要な権限を取得するには、管理者に次の IAM のロールを付与するよう依頼してください。

• データ クリーンルームで TVF を作成または削除する:
  • プロジェクトに対する Analytics Hub パブリッシャー （roles/analyticshub.publisher）
  • プロジェクトに対する Analytics Hub サブスクライバー （roles/analyticshub.subscriber）
• TVF を承認する: プロジェクトに対する BigQuery データオーナー （roles/bigquery.dataOwner）
• データ クリーンルームで TVF リスティングを追加、更新、削除する:
  • プロジェクトに対する Analytics Hub パブリッシャー （roles/analyticshub.publisher）
  • プロジェクトに対する Analytics Hub サブスクライバー （roles/analyticshub.subscriber）
• クエリ テンプレートを作成します。
  • プロジェクトに対する Analytics Hub パブリッシャー （roles/analyticshub.publisher）
  • プロジェクトに対する Analytics Hub サブスクライバー （roles/analyticshub.subscriber）
• クエリ テンプレートを承認します。
  • プロジェクトに対する Analytics Hub パブリッシャー （roles/analyticshub.publisher）
  • プロジェクトに対する BigQuery データオーナー （roles/bigquery.dataOwner）
• クエリ テンプレートを使用してデータ クリーンルームに登録する:
  • プロジェクトに対する Analytics Hub サブスクライバー （roles/analyticshub.subscriber）
  • データ クリーンルームに登録するプロジェクトに対する Analytics Hub サブスクリプション オーナー （roles/analyticshub.subscriptionOwner）
• クエリ テンプレートで定義されたクエリを実行します。
  • プロジェクトに対する BigQuery データ閲覧者（roles/bigquery.dataViewer）
  • プロジェクトに対する BigQuery ユーザー（roles/bigquery.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、このドキュメントのタスクを実行するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

既存の TVF をデータ クリーンルームに追加する

Analytics Hub API を使用して、既存の TVF をデータ クリーンルームに追加できます。

projects.locations.dataExchanges.listings.create メソッドを使用します。

次の例は、curl コマンドを使用して projects.locations.dataExchanges.listings.create メソッドを呼び出す方法を示しています。

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d
    '{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/tables/ROUTINE_ID"}],},"displayName":LISTING_NAME"}'

次のように置き換えます。

• DCR_PROJECT_ID: データ クリーンルームが作成されたプロジェクトのプロジェクト ID。
• PROJECT_ID: ソース データセットが含まれていたプロジェクトのプロジェクト ID。
• DATASET_ID: ソース データセットの ID。
• LOCATION: データ クリーンルームのロケーション。
• CLEAN_ROOM_ID: データ クリーンルームの ID。
• LISTING_ID: リスティング ID。
• LISTING_NAME: リスティング名。
• ROUTINE_ID: ルーティン ID。

クエリ テンプレートのロール

データ クリーンルームのクエリ テンプレートを使用するには、主に 3 つのロールがあります。各ロールには特定のワークフローがあります。これについては、このドキュメントの後半で説明します。

• テンプレート作成者: クリーンルーム内で実行するクエリを定義するユーザー。このロールは、Analytics Hub 管理者、Analytics Hub パブリッシャー、Analytics Hub リスティング管理者のいずれかのロールに似ています。詳細については、テンプレート作成者のワークフローをご覧ください。

• テンプレート承認者: テンプレートを使用可能にする前に、クエリ テンプレートの参照を承認する必要があるデータのオーナー。このロールは、Analytics Hub 管理者、Analytics Hub パブリッシャー、Analytics Hub リスティング管理者のいずれかのロールに似ています。詳細については、テンプレート承認ワークフローをご覧ください。

• テンプレート サブスクライバー: クリーンルームに登録し、テンプレートで承認されたクエリのみを実行できるユーザー。このロールは、Analytics Hub サブスクライバーのロールに似ています。詳細については、テンプレート サブスクライバー ワークフローをご覧ください。

テンプレート作成者のワークフロー

クエリ テンプレートの作成者は、次の操作を行うことができます。

• クエリ テンプレートを作成する。
• クエリ テンプレートを更新する。
• 審査用にクエリ テンプレートを送信する。
• クエリ テンプレートを削除します。

データ クリーンルームにリスティングを追加する

クエリ テンプレートを作成する前に、データ クリーンルームにデータを追加する必要があります。データ クリーンルームにリスティングを作成する手順は次のとおりです。

1. [共有（Analytics Hub）] ページに移動します。

   [共有（Analytics Hub）] に移動

2. クエリ テンプレートを作成するデータ クリーンルームの表示名をクリックします。

3. [データを追加] をクリックし、手順に沿って分析ルールが構成されたビューを作成します。詳細な手順については、リスティングを作成する（データを追加する）をご覧ください。

   1. 他のユーザーのデータを追加するには、データ クリーンルームを別の信頼できる提供者と共有します。このデータ提供者は、クエリ テンプレートで使用できるように、クリーンルームにデータを追加する必要があります。

4. リスティングのデータ下り（外向き）制御を設定します。

5. リスティングのメタデータ制御を設定します。前の手順で追加したデータのスキーマと説明のみを共有する場合（共有データ自体は共有しない場合）は、[リンクされたデータセットからのリスティングへのアクセスを除外する] を選択します。

6. リスティングの詳細を確認します。

7. [Add Data] をクリックします。データのビュー用に作成されたメタデータがクリーンルームに追加されました。

クエリ テンプレートを作成する

次のオプションのいずれかを選択します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID -d
  'query_template {
  name: "query_template1",
  display_name: "query_template1",
  routine {
    definition_body: "QUERY_TEMPLATE_ID(TVF arguments) AS (TVF_DEFINITION)"
  }
}'

  query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

  CREATE OR REPLACE TABLE FUNCTION <approvers_dataset>.query_template1(t1 TABLE, y INT64)
  AS (SELECT * FROM t1 WHERE year > y)

クエリ テンプレートを更新する

クエリ テンプレートを更新できるのは、ステータスが [下書き] の場合のみです。クエリ テンプレートがすでに審査に送信されている場合、変更することはできません。

クエリ テンプレートを更新するには、次のいずれかのオプションを選択します。

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X PATCH https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID?updateMask=display_name -d
    'query_template {
    display_name: "query_template1"
  }'

審査のためにクエリ テンプレートを送信する

次のオプションのいずれかを選択します。

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:submit

クエリ テンプレートを削除する

クエリ テンプレートは、下書きステータスの場合にのみ削除できます。クエリ テンプレートがすでに審査に送信されている場合、削除することはできません。

次のオプションのいずれかを選択します。

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X DELETE https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID

テンプレートの承認者ワークフロー

クエリ テンプレート承認者は、クエリ テンプレートを承認できます。

TVF が所有していないデータ（他の投稿者のデータなど）を参照している場合、クエリ テンプレートは、そのデータのオーナーのみが承認できます。データを参照するだけの TVF（一方向の共有用）を作成する場合は、クエリ テンプレートを自分で承認できます。

クエリ テンプレートを承認する

次のオプションのいずれかを選択します。

クエリ テンプレートを拒否する

Cloud de Confiance コンソールで、次の方法でクエリ テンプレートを拒否できます。

• 送信されたクエリ テンプレートの審査を承認しないでください。
• クエリ テンプレートを削除して、クリーンルームから削除します。

テンプレートのサブスクライバー ワークフロー

クエリ テンプレートのサブスクライバーは、データ クリーンルームを表示して登録できます。クリーンルームにクエリ テンプレートのみが追加されている場合、クリーンルームに登録しても、基盤となる共有データではなく、対応する TVF へのアクセス権のみが付与されます。

クエリ テンプレートをサブスクライブする

次のオプションのいずれかを選択します。

SELECT * FROM `myproject.dcr_linked_dataset.mytvf`(TABLE myTable);

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID:subscribe  --data '{"destination":"projects/SUBSCRIBER_PROJECT_ID/locations/LOCATION","subscription":"SUBSCRIPTION"}'

SELECT * FROM `myproject.dcr_linked_dataset.mytvf`(TABLE myTable);

サンプル事例

クエリ テンプレートを使用すると、データ クリーンルーム内でさまざまな形式のデータ コラボレーションを促進できます。以降のセクションでは、シナリオの例について説明します。

一方向の共有シナリオ

データ パブリッシャーは、サブスクライブしているパートナーがパブリッシャーによって定義されたクエリのみを実行できることを確認するためのクエリ テンプレートを作成します。クリーンルームに他の投稿者が追加されていないため、クエリ テンプレートの作成者は最終的にクエリ テンプレートを自己承認します。

このシナリオでは、ユーザー A はデータ クリーンルームのオーナーであり、campaign_analysis というデータ クリーンルームを作成し、campaigns テーブルを含む my_campaign というデータセットを追加します。ユーザー A は、メタデータ スキーマのみが表示され、サブスクライバーがソースデータにアクセスできないことを確認するために、集計しきい値ポリシーとメタデータ制御を構成します。ユーザー A は、campaigns テーブルからテーブル値関数を定義し、リンクされたデータセットのすべてのサブスクライバーが TVF のみ実行するように制限して、クエリ テンプレートを作成します。

TVF の構文は次のとおりです。

campaigns_template(t1 TABLE campaign_ID <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM myproject.my_campaign.campaigns
group by company_id, company
);

ユーザー A は BigQuery データ所有者のロールでキャンペーン テーブルに対する適切な権限を持っているため、ユーザー A はクエリ テンプレートを審査に送信した後、すぐに自己承認できます。

複数当事者間のコラボレーション共有

クリーンルームのオーナーは、信頼できるデータ提供者を招待して、互いのデータに対して実行するクエリを提案します。両者は、基盤となる共有データにアクセスすることなく、メタデータ スキーマのみを表示して、安全にクエリを提案できます。クエリ定義がテンプレート提案者のデータではないデータを参照している場合、テンプレートはデータの所有者のみが承認できます。

このシナリオでは、ユーザー A がデータ クリーンルームの提供者であるユーザー B を campaign_analysis クリーンルームに招待します。ユーザー B は、テーブルのメタデータ スキーマを表示して、独自のデータを campaigns テーブルに結合するクエリ テンプレートを提案したいと考えています。

TVF の構文は次のとおりです。

campaigns_template(t1 TABLE campaign_ID <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

ユーザー B は campaigns テーブルを追加しておらず、所有者でもないため、クエリ テンプレートが承認のために送信されると、ユーザー A のみが承認できます。クエリ テンプレートを使用するには、ユーザー B がクリーンルームをサブスクライブし、TVF を呼び出す必要があります。ユーザー B は、campaign_ID というフィールドを含む独自のテーブルをテーブル パラメータとして渡し、クエリ テンプレートで定義された非公開 SQL を実行できます。ここで注意すべき点は、ユーザー B はデータをクリーンルームに追加する必要がないことです。

ユーザー B は、transactions テーブルと products テーブルを含む my_transactions という名前のデータセットをクリーンルームに追加します。ユーザー B は、メタデータ スキーマのみが表示され、サブスクライバーがソースデータにアクセスできないことを確認するために、集計しきい値ポリシーとメタデータ コントロールを構成します。

ユーザー A は、テーブルのメタデータ スキーマを表示して、独自のデータをトランザクション テーブルに結合するためのさまざまなクエリ テンプレートを提案できるようになりました。TVF の構文の例を次に示します。

transactions_template(t1 TABLE user_ID  <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, campaign_id, sku, category, date, sum(amount) FROM my_project.my_transactions.transactions
group by company_id, company, campaign_id, sku, category, date
);

transactions_template_with_join(t1 TABLE user_ID  <STRING> ) AS (
SELECT WITH AGGREGATION_THRESHOLD t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category, sum(t.amount) FROM myproject.my_transactions.transactions t
left join my_project.my_transactions.products p
on t.product_id = p.product_id
group by t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category
);

ユーザー A は transactions テーブルと products テーブルを追加しておらず、所有もしていないため、クエリ テンプレートが承認のために送信されると、ユーザー B のみが承認できます。クエリ テンプレートを使用するには、ユーザー A がクリーンルームに登録して TVF を呼び出す必要があります。ユーザー A は、user_ID という名前のフィールドを含む独自のテーブルをテーブル パラメータとして渡し、クエリ テンプレートで定義されたプライバシー SQL を実行できます。ここで注意すべき点は、ユーザー A はデータをクリーンルームに追加する必要がないことです。

料金

クエリ テンプレートを使用するデータ提供者は、データ ストレージに対してのみ課金されます。

クエリ テンプレートを使用するサブスクライバーは、クエリを実行した場合にのみ、コンピューティング（分析）に対して課金されます。

次のステップ

• データ クリーンルームの詳細については、データ クリーンルームを使用して機密データを共有するをご覧ください。
• サブスクリプションの詳細については、データ クリーンルームに登録するをご覧ください。
• TVF の詳細については、テーブル関数をご覧ください。
• データの下り（外向き）の詳細については、下り（外向き）データ オプション（BigQuery 共有データセットのみ）をご覧ください。