ラベルを使用したリソースのフィルタリング
ラベルを使用してリソースをフィルタリングするには、次のいずれかを行います。
- 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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
次のステップ
- BigQuery リソースにラベルを追加する方法を学習する。
- BigQuery リソースでラベルを表示する方法を学習する。
- BigQuery リソースでラベルを更新する方法を学習する。
- BigQuery リソースでラベルを削除する方法を学習する。
- Resource Manager ドキュメントでラベルの使用について読む。