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

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

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 コンソールを使用します。

Google Cloud コンソールで、[エクスプローラ] ペインに移動します。
検索バーに、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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

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

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

制限事項

始める前に

必要な権限

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

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

フィルタ指定の制限

フィルタ指定の例

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

bq

API

Go

Java

Node.js

Python

次のステップ

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

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