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

このページでは、ラベルを使用して BigQuery リソースをフィルタする方法について説明します。

概要

ラベルを使用してリソースをフィルタリングするには、次の手順に従います。

Cloud Console または従来のウェブ UI の検索バーを使用します。
API、bq コマンドラインツール、またはクライアントライブラリを使用してフィルタ仕様を作成します。

制限事項

現在、次の制限があります。

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

必要な権限

ラベルを使用してリソースをフィルタするには、リソースメタデータを取得できる必要があります。そのためには最低でも以下が必要です。

bigquery.datasets.get でデータセットをフィルタリングする
bigquery.tables.get でテーブルとビューをフィルタする

次の事前定義済みの IAM ロールには bigquery.datasets.get 権限が含まれています。

bigquery.user
bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

次の事前定義済みの IAM ロールには bigquery.tables.get 権限が含まれています。

bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権により、ユーザーは作成するリソースをフィルタリングできます。

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

UI でのリソースのフィルタリング

Cloud Console または従来のウェブ UI を使用してフィルタされたリソースのリストを生成するには、次の手順に従います。

Console

ナビゲーションペインで、[リソース] セクションを展開します。
検索バーに、key、value、または key:value のペアを入力します。結果には、部分一致が含まれます。

たとえば、ラベル department:shipping が付いたデータセットだけを表示するには、次のように入力します。
- key 値: department
- value: shipping
- key:value ペア: department:shipping

従来の UI

ナビゲーションウィンドウで、[Filter by ID or label] ボックスまでスクロールします。このボックスは、プロジェクトのリストのすぐ上に表示されています。
検索バーに、key、value、または Key-Value ペアを入力します。Key-Value ペアは key:value の形式です。結果には、部分一致が含まれます。

たとえば、ラベル department:shipping が付いたデータセットだけを表示するには、次のように入力します。
- key 値: department
- value: shipping
- key:value ペア: 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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

// 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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック


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 ドキュメントでラベルの使用について読む。

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

概要

制限事項

必要な権限

UI でのリソースのフィルタリング

Console

従来の UI

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

フィルタ指定の制限

フィルタ指定の例

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

bq

API

Go

Java

Node.js

Python

次のステップ

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

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