保存済みクエリを管理する

このドキュメントでは、保存済みクエリと従来の保存済みクエリを管理する方法と、Dataplex で保存したクエリのメタデータを管理する方法について説明します。

保存済みクエリは、Dataform によって可能となる BigQuery Studio コードアセットです。

始める前に

BigQuery Studio の保存済みクエリを管理し、従来の保存済みクエリを BigQuery Studio の保存済みクエリに移行するには、次の操作を行います。

  1. プロジェクトで BigQuery Studio を有効にします。

  2. 省略可: 移行時に、公開設定が一般公開またはプロジェクトに設定されている移行された従来の保存済みクエリに IAM 権限を設定するには、BigQuery Studio の保存済みクエリを作成または選択し、その保存済みクエリに選択した Identity and Access Management（IAM）権限を付与します。

    公開設定が一般公開またはプロジェクトに設定されている従来の保存済みクエリを BigQuery Studio の保存済みクエリに移行する際に、BigQuery Studio の保存済みクエリを選択して、そのクエリに付与されている権限を移行された保存済みクエリにコピーします。

  3. Dataplex で保存済みクエリ メタデータを管理するには、Google Cloud プロジェクトで Dataplex API が有効になっていることを確認します。

必要なロール

保存済みクエリを管理するために必要な権限を取得するには、保存済みクエリを管理したいプロジェクトにおいて、次の IAM ロールを付与するよう管理者に依頼してください。

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

これらの事前定義ロールには、保存済みクエリの管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

保存済みクエリを管理するには、次の権限が必要です。

  • Google Cloud コンソールで BigQuery Studio の保存済みクエリを管理するには: bigquery.config.get, bigquery.jobs.create, dataform.locations., resourcemanager.projects.get, resourcemanager.projects.list, bigquery.readsessions., dataform.repositories., dataform.workspaces.
  • BigQuery API を使用して BigQuery Studio の保存済みクエリを管理するには: dataform.locations., dataform.repositories., dataform.workspaces.*, resourcemanager.projects.get, resourcemanager.projects.list
  • プロジェクトの従来の保存済みクエリを BigQuery Studio の保存済みクエリに移行するには: bigquery.savedqueries.get, bigquery.savedqueries.list, bigquery.savedqueries.update, bigquery.savedqueries.delete, bigquery.savedqueries.create
  • 認証済みユーザーが公開アクセスクエリを閲覧できるようにするには: dataform.locations.*, dataform.repositories.computeAccessTokenStatus, dataform.repositories.fetchHistory, dataform.repositories.fetchRemoteBranches, dataform.repositories.get, dataform.repositories.getIamPolicy, dataform.repositories.list, dataform.repositories.queryDirectoryContents, dataform.repositories.readFile, dataform.workspaces.fetchFileDiff, dataform.workspaces.fetchFileGitStatuses, dataform.workspaces.fetchGitAheadBehind. dataform.workspaces.get, dataform.workspaces.getIamPolicy, dataform.workspaces.list, dataform.workspaces.queryDirectoryContents, dataform.workspaces.readFile, dataform.workspaces.searchFiles, resourcemanager.projects.get, resourcemanager.projects.list

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

BigQuery IAM の詳細については、IAM でのアクセス制御をご覧ください。

Dataplex で保存済みクエリ メタデータを管理するには、必要な Dataplex ロールと dataform.repositories.get 権限があることを確認します。

保存済みクエリを共有する

保存済みクエリをユーザーと共有するには、まずそのユーザーに保存済みクエリへのアクセス権を付与し、適切な IAM ロールに追加します。次に、保存済みクエリへのリンクを生成し、そのリンクをユーザーと共有します。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。アクセス権を付与したい保存済みクエリを見つけてクリックします。

  3. [共有]、[権限を管理] の順にクリックします。

  4. [権限を管理] ペインで、[ユーザー / グループを追加] をクリックします。

  5. [新しいプリンシパル] フィールドに、プリンシパルを入力します。

  6. [ロール] リストで、次のいずれかのロールを選択します。

  7. 省略可: ロールと詳細な共有設定の完全なリストを表示するには、[詳細な共有] をクリックします。

  8. [保存] をクリックします。

  9. 保存済みクエリの情報に戻るには、[閉じる] をクリックします。

  10. 保存済みクエリへのリンクを生成するには、 [共有]、[リンクを取得] の順にクリックします。

    リンクがクリップボードにコピーされます。

保存済みクエリへの公開アクセス権を付与する

BigQuery Studio の保存済みクエリへの公開アクセス権を付与するには、保存済みクエリのコード閲覧者（roles/dataform.codeViewer）ロールを allAuthenticatedUsers プリンシパルに付与します。

allAuthenticatedUsers プリンシパルに IAM ロールを割り当てると、サービス アカウントと、Google アカウントで認証されたすべてのインターネット ユーザーにそのロールが付与されます。これには、個人用 Gmail アカウントなど、Google Workspace アカウントまたは Cloud Identity のドメインに接続していないアカウントも含まれます。認証されていないユーザー（匿名の訪問者など）は含まれません。詳細については、認証済みのすべてのユーザーをご覧ください。

たとえば、sales 保存済みクエリのコード閲覧者ロールを allAuthenticatedUsers に付与すると、Google アカウントで認証されたすべてのサービス アカウントとインターネット ユーザーに sales 保存済みクエリへの読み取り専用権限が与えられます。

BigQuery Studio の保存済みクエリに公開アクセス権を付与するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。公開アクセス権を付与する保存済みクエリを見つけます。

  3. 保存済みクエリの横にある [アクションを表示] をクリックし、[共有] > [権限を管理] をクリックします。

  4. [権限を管理] ペインで、[ユーザー / グループを追加] をクリックします。

  5. [新しいプリンシパル] フィールドに「allAuthenticatedUsers」と入力します。

  6. [ロール] リストで、[コード閲覧者] ロールを選択します。

  7. [保存] をクリックします。

  8. 保存済みクエリの情報に戻るには、[閉じる] をクリックします。

保存済みクエリへの公開アクセスを防止する

BigQuery Studio の保存済みクエリへの公開アクセス権が付与されないようにするには、プロジェクトで allAuthenticatedUsers プリンシパルを制限します。

プロジェクトで allAuthenticatedUsers を制限するには、iam.allowedPolicyMemberDomains ポリシーを設定し、allowed_values のリストから allAuthenticatedUsers を削除します。

iam.allowedPolicyMemberDomains ポリシーで allAuthenticatedUsers を制限すると、allAuthenticatedUsers プリンシパルをプロジェクトの IAM ポリシーで使用できないため、BigQuery Studio の保存済みクエリを含むすべてのリソースへの公開アクセス権を付与できなくなります。

iam.allowedPolicyMemberDomains ポリシーとその設定手順の詳細については、ドメイン別の ID の制限をご覧ください。

すべての保存済みクエリを表示する

プロジェクトに保存されているすべてのクエリのリストを表示するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、[クエリ] の横にある （アクションを表示）をクリックし、次のいずれかを行います。

  • 現在のタブでリストを開くには、[すべて表示] をクリックします。
  • リストを新しいタブで開くには、[すべてを表示] > [新しいタブ] をクリックします。
  • 分割タブでリストを開くには、[すべてを表示] > [タブを分割] をクリックします。

保存済みクエリのメタデータを表示する

保存済みクエリのメタデータを表示するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。メタデータを表示する保存済みクエリの名前をクリックします。

  3. [概要] ペインで、使用されているリージョンや最終更新日など、保存済みクエリに関する情報を確認します。

保存済みクエリのバージョンを操作する

以降のセクションでは、保存したクエリのバージョンを表示、比較、復元する方法について説明します。

保存済みクエリのバージョンを表示する

保存済みクエリのバージョンを表示するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。アクティビティを表示する保存済みクエリの名前をクリックします。

  3. [アクティビティ] タブをクリックすると、保存済みクエリのバージョンの一覧が日付の降順で表示されます。

保存済みクエリのバージョンを比較する

保存済みクエリのバージョンを比較するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。バージョン情報を比較する保存済みクエリの名前をクリックします。

  3. [アクティビティ] タブで、保存済みクエリのバージョンの横にある [アクションを表示] をクリックし、[比較] をクリックします。比較ペインが開き、選択した保存済みクエリのバージョンと現在の保存済みクエリのバージョンが比較されます。

  4. 省略可: 現在の保存済みクエリのバージョンには、保存されていない変更も表示されます。変更内容を保存するには、[上書き] をクリックします。

  5. 省略可: 個別のペインではなくインラインでバージョンを比較するには、[比較]、[インライン] の順にクリックします。

保存済みクエリのバージョンを復元する

保存済みクエリのバージョンを復元するには、次のいずれかのオプションを使用します。比較ペインから復元すると、復元するかどうかを選択する前に、保存済みクエリの以前のバージョンを現在のバージョンと比較できます。

アクティビティ ペイン

  1. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。以前のバージョンを復元する保存済みクエリの名前をクリックします。
  2. [アクティビティ] ペインを選択します。
  3. 復元する保存したクエリのバージョンの横にある （アクションを表示）をクリックし、[復元] をクリックします。
  4. [確認] をクリックして、操作を確定します。

比較ペイン

  1. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。以前のバージョンを復元する保存済みクエリの名前をクリックします。
  2. [アクティビティ] ペインを選択します。
  3. 保存済みクエリのバージョンの横にある [アクションを表示] をクリックし、[比較] をクリックします。比較ペインが開き、選択した保存済みクエリのバージョンと最新の保存済みクエリのバージョンを比較します。
  4. 比較後に以前の保存済みクエリのバージョンを復元する場合は、[復元] をクリックします。
  5. [確認] をクリックして、操作を確定します。

保存済みクエリをダウンロードする

保存済みクエリをダウンロードするには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。保存済みクエリの名前をクリックして開きます。

  3. [ダウンロード] をクリックします。

保存済みクエリを削除する

保存済みクエリを削除するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [クエリ] フォルダを開き、必要に応じて [共有クエリ] フォルダを開きます。削除する保存済みクエリを見つけます。

  3. 保存したクエリの横にある [ アクションを表示] をクリックし、[削除] をクリックします。

  4. 削除を確定するには、ダイアログで「delete」と入力します。

  5. [削除] をクリックします。

従来の保存済みクエリ

従来の保存済みクエリの管理方法については、以降のセクションをご覧ください。

従来の保存済みクエリを共有する

共有できる従来の保存済みクエリは、公開設定がプロジェクトまたは一般公開に設定されているクエリです。プロジェクトの公開設定を指定すると、必要な権限を持つプリンシパルがクエリを表示、更新、削除できます。一般公開の公開設定では、クエリリンクを知っているすべての人がクエリを表示できますが、更新や削除はできません。

従来の保存済みクエリを他のユーザーと共有するには、このクエリへのリンクを生成して共有します。

従来の共有クエリを実行するには、クエリがアクセスするデータへのアクセス権が必要です。詳細については、データセットへのアクセス権を付与するをご覧ください。

従来の保存済みクエリを共有する場合は、その目的を説明するコメントをクエリに含めることを検討してください。

  1. [エクスプローラ] ペインで、プロジェクトと [（従来）クエリ] フォルダを開き、共有する従来の保存済みクエリを見つけます。
  2. クエリの横にある （アクションを表示）をクリックし、[リンクを取得] をクリックします。
  3. クエリへのアクセス権を付与するユーザーとリンクを共有します。

従来のクエリを保存済みクエリとして保存する

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [（従来）クエリ] フォルダを開き、必要に応じて [プロジェクト クエリ] フォルダを開きます。

  3. 従来の保存済みクエリの名前をクリックして開きます。

  4. [クエリ（従来）を保存] > [クエリに名前を付けて保存...] をクリックします。

  5. [クエリを保存] ダイアログで、クエリの名前を入力してロケーションを選択します。

  6. [保存] をクリックします。

従来の保存済みクエリを移行する

従来の保存済みクエリを一括で移行するには、必要なロールが付与されている必要があります。これらのロールによって付与される権限によって、移行できる従来の保存済みクエリの種類が決まります。

次の従来の保存済みクエリは、一括で移行できます。

個人の従来の保存済みクエリ
個人の従来の保存済みクエリは、それを作成したユーザーにのみ表示されます。これらのクエリは アイコンで区別できます。個人の従来の保存済みクエリは、オーナーのみが移行できます。
一般公開される従来の保存済みクエリ

一般公開される従来の保存済みクエリは、クエリへのリンクを持つすべてのユーザーに表示されます。これらのクエリは アイコンで区別できます。一般公開される従来の保存済みクエリは、オーナーのみが移行できます。

一般公開される従来の保存済みクエリに対する IAM 権限は、BigQuery Studio の保存済みクエリに対する権限にマッピングされません。つまり、一般公開される従来の保存済みクエリから移行された BigQuery Studio の保存済みクエリは、デフォルトでは公開されません。移行された BigQuery Studio の保存済みクエリに対する IAM 権限は、移行中または移行後に設定する必要があります。

移行された BigQuery Studio の保存済みクエリに対する IAM 権限を移行中に設定するには、移行された保存済みクエリに適用する権限を持つ既存の BigQuery Studio の保存済みクエリを選択します。BigQuery は、選択された BigQuery Studio の保存済みクエリに付与されている権限をコピーし、移行された保存済みクエリに適用します。移行された保存済みクエリを共有するユーザーまたはグループを手動で追加することもできます。

移行中に IAM 権限を設定しない場合、移行された BigQuery Studio の保存済みクエリにアクセスできるのは移行を行ったユーザーのみです。

プロジェクトの従来の保存済みクエリ

プロジェクト レベルの保存済みクエリは、必要な権限を持つプリンシパルに表示されます。これらのクエリは アイコンで区別できます。プロジェクトに含まれるプロジェクトの従来の保存済みクエリは、すべて一括で移行できます。

プロジェクトの従来の保存済みクエリに対する IAM 権限は、BigQuery Studio の保存済みクエリに対する権限に直接マッピングされません。移行された BigQuery Studio の保存済みクエリに対する IAM 権限は、移行中または移行後に設定する必要があります。

移行された BigQuery Studio の保存済みクエリに対する IAM 権限を移行中に設定するには、移行された保存済みクエリに適用する権限を持つ既存の BigQuery Studio の保存済みクエリを選択します。BigQuery は、選択された BigQuery Studio の保存済みクエリに付与されている権限をコピーし、移行された保存済みクエリに適用します。移行された保存済みクエリを共有するユーザーまたはグループを手動で追加することもできます。

移行中に IAM 権限を設定しない場合、移行された BigQuery Studio の保存済みクエリにアクセスできるのは移行を行ったユーザーのみです。

従来の保存済みクエリを一括で移行する際に、BigQuery は次の処理を行います。

  • 移行される従来の保存済みクエリをすべて BigQuery Studio の保存済みクエリとして保存し、選択されたリージョンに格納します。
  • 移行される従来の保存済みクエリをすべて読み取り専用の従来の保存済みクエリに変換します。

移行後、個人、一般公開、プロジェクトの従来の保存済みクエリには、BigQuery Studio の保存済みクエリとしても、読み取り専用の従来の保存済みクエリとしてもアクセスできます。

移行のリスク

一括移行の後、移行された従来の保存済みクエリを変更することはできません。移行された個人、一般公開、プロジェクトの従来の保存済みクエリは、読み取り専用になります。

BigQuery は、Dataform API を使用して、移行された BigQuery Studio の保存済みクエリを Google Cloud プロジェクトに追加します。これらの変更を元に戻すには、手動でクリーンアップする必要があります。

従来の保存済みクエリを一括で移行する

プロジェクト内の従来の保存済みクエリを BigQuery Studio の保存済みクエリに一括で移行するには、次の操作を行います。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開き、[（従来の）クエリ] の横にある [アクションを表示] をクリックし、[従来の保存済みクエリを移行] をクリックします。

  3. [従来の保存済みクエリの移行] ペインの [移行の準備状況のチェック] セクションで、[次へ] をクリックして、必要な権限があることを確認します。

    IAM 権限によって、移行できる従来の保存済みクエリの種類と [従来の保存済みクエリの移行] ペインに表示されるセクションが決まります。

  4. [リージョン] セクションの [リージョン] プルダウンで、移行された保存済みクエリをBigQuery によって保存するリージョンを選択します。

    BigQuery Studio コードアセットのデフォルトのリージョンを選択することをおすすめします。詳細については、コードアセットにデフォルトのリージョンを設定するをご覧ください。

  5. 個人の従来の保存済みクエリをすべて移行するには、[個人用クエリの移行] セクションで [すべての個人用クエリを移行する] チェックボックスをオンにして、[次へ] をクリックします。

  6. プロジェクト内の一般公開される従来の保存済みクエリをすべて移行するには、[公開クエリを移行する] セクションで次の操作を行います。

    1. [すべての一般公開クエリを移行する] チェックボックスをオンにします。
    2. [SQL] プルダウンで、移行された保存済みクエリに適用する IAM ポリシーを含む BigQuery Studio の保存済みクエリを選択します。

    3. 省略可: 移行された保存済みクエリを共有するユーザーまたはグループを追加するには、[ユーザー / グループを追加] をクリックします。

      移行された保存済みクエリを一般公開するには、allAuthenticatedUsers をプリンシパルとして設定し、コード閲覧者ロールを付与します。詳細については、公開アクセス権を付与するをご覧ください。

    4. [次へ] をクリックします。

  7. プロジェクト レベルの従来の保存済みクエリを移行するには、[プロジェクト クエリの移行] セクションで次の操作を行います。

    1. [すべてのプロジェクト クエリを移行する] チェックボックスをオンにします。
    2. [SQL] プルダウンで、移行された保存済みクエリに適用する IAM ポリシーを含む BigQuery Studio の保存済みクエリを選択します。
    3. 省略可: 移行された保存済みクエリを共有するユーザーまたはグループを追加するには、[ユーザー / グループを追加] をクリックします。
    4. [次へ] をクリックします。

  8. 移行のリスクを理解したうえで、従来の保存済みクエリを一括で移行することを確認するため、[確認] セクションの [確認] フィールドに「confirm」と入力し、[次へ] をクリックします。

  9. [送信] をクリックします。

移行するクエリの数によっては、移行に 15 分以上かかることがあります。

従来の保存済みクエリを削除する

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトと [（従来）クエリ] フォルダを開き、必要に応じて [プロジェクト クエリ] フォルダを開きます。

  3. 削除する従来の保存済みクエリを見つけます。

  4. クエリの横にある [ アクションを表示] をクリックし、[削除] をクリックします。

  5. 削除を確定するには、ダイアログで「delete」と入力します。

  6. [削除] をクリックします。

Dataplex でメタデータを管理する

Dataplex では、保存済みクエリのメタデータを保存して管理できます。保存済みクエリは、追加の設定なしでデフォルトで Dataplex で使用できます。

Dataplex を使用すると、すべての保存済みクエリのロケーションで保存済みクエリを管理できます。Dataplex で保存したクエリの管理には、Dataplex の割り当てと上限と Dataplex の料金が適用されます。

Dataplex は、保存したクエリから次のメタデータを自動的に取得します。

  • データアセット名
  • データアセットの親
  • データアセットのロケーション
  • データアセットのタイプ
  • 対応する Google Cloud プロジェクト

Dataplex は、保存済みクエリをエントリとしてログに記録します。エントリの値は次のとおりです。

システム エントリ グループ
保存済みクエリのシステム エントリ グループは @dataform です。Dataplex で保存されたクエリ エントリの詳細を表示するには、dataform システム エントリ グループを表示する必要があります。エントリ グループ内のすべてのエントリのリストを表示する方法については、Dataplex ドキュメントのエントリ グループの詳細を表示するをご覧ください。
システム エントリタイプ
保存されたクエリのシステム エントリタイプは dataform-code-asset です。保存したクエリの詳細を表示するには、dataform-code-asset システム エントリタイプを表示し、アスペクトに基づくフィルタで結果をフィルタし、dataform-code-asset アスペクト内の type フィールドを SQL_QUERY に設定する必要があります。次に、選択した保存済みクエリのエントリを選択します。選択したエントリタイプの詳細を表示する手順については、Dataplex ドキュメントのエントリタイプの詳細を表示するをご覧ください。選択したエントリの詳細を表示する手順については、Dataplex ドキュメントのエントリの詳細を表示するをご覧ください。
システム アスペクト タイプ
保存済みクエリのシステム アスペクト タイプは dataform-code-asset です。保存済みクエリのエントリにアスペクトをアノテーションすることで、Dataplex で保存したクエリにさらなるコンテキストを追加するには、dataform-code-asset アスペクト タイプを表示し、アスペクトに基づくフィルタで結果をフィルタし、dataform-code-asset アスペクト内の type フィールドを SQL_QUERY に設定します。エントリにアスペクトをアノテーションする方法については、Dataplex ドキュメントのアスペクトを管理してメタデータを拡充するをご覧ください。
タイプ
保存したクエリのタイプは SQL_QUERY です。このタイプでは、アスペクトに基づくフィルタで aspect:dataplex-types.global.dataform-code-asset.type=SQL_QUERY クエリを使用することで、dataform-code-asset システム エントリタイプと dataform-code-asset アスペクト タイプの保存済みクエリをフィルタできます。

Dataplex でアセットを検索する方法については、Dataplex ドキュメントの Dataplex でデータアセットを検索するをご覧ください。

次のステップ