ラベルを使用してリソースをフィルタするには、次のいずれかを行います。
- Cloud Console の検索バーを使用します。
- 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 のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
Cloud Console でのリソースのフィルタリング
フィルタされたリソースのリストを生成するには、Cloud Console を使用します。
コンソール
ナビゲーション ペインで、[リソース] セクションを展開します。
検索バーに、
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 のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
次のステップ
- BigQuery リソースにラベルを追加する方法を学習する。
- BigQuery リソースでラベルを表示する方法を学習する。
- BigQuery リソースでラベルを更新する方法を学習する。
- BigQuery リソースでラベルを削除する方法を学習する。
- Resource Manager ドキュメントでラベルの使用について読む。