ラベルを使用したリソースのフィルタリング

ラベルを使用してリソースをフィルタリングするには、次のいずれかを行います。

• Google Cloud コンソールの検索バーを使用します。
• API、bq コマンドライン ツール、またはクライアント ライブラリを使用してフィルタ指定を作成します。

制限事項

• API、bq コマンドライン ツール、クライアント ライブラリでは、データセットのみに対するフィルタリングがサポートされています。
• ジョブは、BigQuery ツールのラベルでフィルタできません。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。

必要な権限

ラベルを使用してリソースをフィルタするには、リソース メタデータを取得できる必要があります。ラベルを使用してリソースをフィルタするには、次の IAM 権限が必要です。

• bigquery.datasets.get（データセットをフィルタできます）
• bigquery.tables.get（テーブルとビューをフィルタできます）

次に挙げる各 IAM 事前定義ロールには、データセットをフィルタするために必要な権限が含まれています。

• roles/bigquery.user
• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

次に挙げる各 IAM 事前定義ロールには、テーブルとビューをフィルタするために必要な権限が含まれています。

• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

また、bigquery.datasets.create 権限がある場合は、作成したリソースをフィルタできます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

Google Cloud コンソールでのリソースのフィルタリング

フィルタリングされたリソースのリストを生成するには、Google Cloud コンソールを使用します。

1. Google Cloud コンソールで、[エクスプローラ] ペインに移動します。

2. 検索バーに、key ペアまたは key:value ペアを入力します。結果には、部分一致が含まれます。

   たとえば、department:shipping というラベルのデータセットのみを表示するには、department または department:shipping を入力します。

API または bq コマンドライン ツールでのデータセットのフィルタリング

現在、API、bq コマンドライン ツール、クライアント ライブラリでは、データセットのみに対するフィルタリングがサポートされています。

API、bq ツール、またはクライアント ライブラリを使用してデータセットをフィルタするには、フィルタ指定を作成して、その指定を以下のものとして使用します。

• bq ツールの --filter フラグのパラメータとして
• API の datasets.list メソッドの filter プロパティの値として

フィルタ指定の制限

フィルタ指定には次の制限があります。

• サポートされる論理演算子は、AND 演算子のみです。スペース区切りで条件を列挙すると、暗黙的に AND 演算子が指定されているものとして扱われます。
• 現在フィルタリングに使用できるフィールドは、唯一 labels.key のみです（key はラベルの名前）。
• フィルタには最大 10 個の条件を含めることができます。
• フィルタする際には大文字と小文字が区別されます。
• 現在、API、bq コマンドライン ツール、クライアント ライブラリでは、データセットのみに対するフィルタリングがサポートされています。

フィルタ指定の例

フィルタ指定では次の構文を使用します。

"field[:value][ field[:value]]..."

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

• field は labels.key と表現します（key はラベルキー）。
• value は省略可能なラベル値です。

次の例は、フィルタ式を生成する方法を示しています。

department:shipping ラベルを持つリソースをリストするには、次のフィルタ指定を使用します。

labels.department:shipping

複数のラベルを使用してリソースを一覧表示するには、key:value ペアをスペースで区切ります。このスペースは AND 論理演算子として扱われます。たとえば、department:shipping ラベルと location:usa ラベルを持つデータセットを一覧表示するには、次のフィルタ指定を使用します。

labels.department:shipping labels.location:usa

キーと値のペアを照合するのではなく、キーが存在するかどうかのみによってフィルタすることもできます。次のフィルタ指定を使用すると、値に関係なく department というラベルが付いたすべてのデータセットのリストが返されます。

labels.department

アスタリスクを使用して、これと同等のフィルタ指定を作成できます。アスタリスクは、department キーに関連付けられているすべての値を表します。

labels.department:*

フィルタ指定でタグを使用することもできます。たとえば、department:shipping ラベルと test_data タグを持つリソースを一覧表示するには、次のフィルタ指定を使用します。

labels.department:shipping labels.test_data

bq コマンドライン ツールと API でのデータセットのフィルタリング

API、bq コマンドライン ツール、またはクライアント ライブラリを使用してデータセットをフィルタするには:

bq

--filter フラグを指定して bq ls コマンドを発行します。デフォルト プロジェクト以外のプロジェクトにあるデータセットを一覧表示する場合は、--project_id フラグを指定します。

bq ls \
--filter "filter_specification" \
--project_id project_id

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

• filter_specification は、有効なフィルタ指定です。
• project_id は、プロジェクト ID です。

例:

次のコマンドを入力して、department:shipping ラベルを持つデフォルト プロジェクト内のデータセットを一覧表示します。

bq ls --filter "labels.department:shipping"

次のコマンドを入力して、department:shipping ラベルと test_data タグを持つデフォルト プロジェクト内のデータセットを一覧表示します。

bq ls --filter "labels.department:shipping labels.test_data"

次のコマンドを入力して、department:shipping ラベルを持つ myotherproject 内のデータセットを一覧表示します。

bq ls --filter "labels.department:shipping" --project_id myotherproject

これらの各コマンドの出力は、次のようなデータセットのリストを返します。

+-----------+
| datasetId |
+-----------+
| mydataset |
| mydataset2|
+-----------+

API

datasets.list API メソッドを呼び出して、filter プロパティを使用してフィルタ指定を指定します。

Go

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listDatasetsByLabel demonstrates walking the collection of datasets in a project, and
// filtering that list to a subset that has specific label metadata.
func listDatasetsByLabel(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	it := client.Datasets(ctx)
	it.Filter = "labels.color:green"
	for {
		dataset, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
	}
	return nil
}

Java

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get list of datasets by label
public class ListDatasetsByLabel {

  public static void runListDatasetsByLabel() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String filter = "MY_LABEL_FILTER";
    listDatasetsByLabel(projectId, filter);
  }

  public static void listDatasetsByLabel(String projectId, String filter) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Page<Dataset> datasets =
          bigquery.listDatasets(
              projectId,
              BigQuery.DatasetListOption.pageSize(100),
              BigQuery.DatasetListOption.labelFilter(filter)); // "labels.color:green"
      if (datasets == null) {
        System.out.println("Dataset does not contain any models");
        return;
      }
      datasets
          .iterateAll()
          .forEach(
              dataset -> System.out.printf("Success! Dataset ID: %s ", dataset.getDatasetId()));
    } catch (BigQueryException e) {
      System.out.println("Project does not contain any datasets \n" + e.toString());
    }
  }
}

Node.js

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function listDatasetsByLabel() {
  // Lists all datasets in current GCP project, filtering by label color:green.

  const options = {
    filter: 'labels.color:green',
  };
  // Lists all datasets in the specified project
  const [datasets] = await bigquery.getDatasets(options);

  console.log('Datasets:');
  datasets.forEach(dataset => console.log(dataset.id));
}

Python

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))  # Make an API request.

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:
        print("\t{}.{}".format(dataset.project, dataset.dataset_id))
else:
    print("No datasets found with this filter.")

次のステップ

• BigQuery リソースにラベルを追加する方法を学習する。
• BigQuery リソースでラベルを表示する方法を学習する。
• BigQuery リソースでラベルを更新する方法を学習する。
• BigQuery リソースでラベルを削除する方法を学習する。
• Resource Manager ドキュメントでラベルの使用について読む。