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

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

概要

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

  • GCP Console、または従来のウェブ UI の検索バーを使用します。
  • CLI、API、またはクライアント ライブラリで使用するフィルタ指定を作成します。

制限事項

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

  • API、CLI、およびクライアント ライブラリは、データセットのみのフィルタリングをサポートします。
  • ジョブは、BigQuery ツールのラベルでフィルタできません。

必要な権限

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

  • bigquery.datasets.get(データセットをフィルタする)
  • bigquery.tables.get(テーブルとビューをフィルタする)

次の事前定義された Cloud IAM 役割には、bigquery.datasets.get 権限が含まれます。

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

次の事前定義された Cloud IAM 役割には、bigquery.tables.get 権限が含まれます。

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

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

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

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

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

Console

  1. ナビゲーション ペインで、[リソース] セクションを展開します。

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

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

    • key 値: department
    • value: shipping
    • key:value ペア: department:shipping

従来の UI

  1. ナビゲーション ウィンドウで、[Filter by ID or label] ボックスまでスクロールします。このボックスは、プロジェクトのリストのすぐ上に表示されています。

  2. 検索バーに、key、value、または Key-Value ペアを入力します。Key-Value ペアは、key:value 形式である必要があります。結果には、部分一致が含まれます。

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

    • key 値: department
    • value: shipping
    • key:value ペア: department:shipping

CLI または API でのデータセットのフィルタリング

現在、API、CLI、クライアント ライブラリではデータセットのみのフィルタリングがサポートされています。

CLI、API、またはクライアント ライブラリを使用してデータセットをフィルタするには、フィルタ指定を作成してから以下の方法でその指定を使用します。

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

フィルタ指定の制限

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

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

フィルタ指定の例

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

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

ここで

  • fieldlabels.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

CLI および API でのデータセットのフィルタリング

CLI、API、またはクライアント ライブラリを使用してデータセットをフィルタするには、次の手順を行います。

CLI

--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"

myotherproject 内のデータセットのうち department:shipping ラベルを持つもののリストを取得するには、次のコマンドを入力します。

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

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

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

API

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

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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)
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。