このページでは、BigQuery リソースにラベルを付ける方法について説明します。
データセット ラベルの追加
BigQuery データセットを作成するときにラベルを追加するには、bq
コマンドライン ツールの bq mk
コマンドを使用するか、API の datasets.insert
メソッドを呼び出します。現時点では、Cloud Console を使用してデータセットを作成するときに、データセットにラベルを追加することはできません。
このページでは、作成したデータセットにラベルを追加する方法について説明します。データセットの作成時にラベルを追加する方法について詳しくは、データセットの作成をご覧ください。
データセットの作成後に、次の方法でラベルを追加できます。
- Cloud Console の使用
bq
コマンドライン ツールのbq update
コマンドを使用するdatasets.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
データセットにラベルを追加しても、データセット内のリソースには反映されません。データセット ラベルはテーブルまたはビューに継承されません。データセットにラベルを追加すると、そのデータセット ラベルはストレージの課金データとしてカウントされますが、ジョブ関連の課金データとして表示されることはありません。
必要な権限
既存のデータセットにラベルを追加するには、少なくとも bigquery.datasets.update
権限が必要です。次の事前定義済みの IAM ロールには bigquery.datasets.update
権限が含まれています。
bigquery.dataOwner
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、ユーザーはデータセットにラベルを追加できます。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
データセットへのラベルの追加
作成したデータセットにラベルを追加するには:
Console
Cloud Console で、データセットを選択します。
データセットの詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- [更新] をクリックして、変更を保存します。
bq
既存のデータセットにラベルを追加するには、set_label
フラグを指定して bq update
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返し指定します。
データセットがデフォルト プロジェクト以外のプロジェクトにある場合は、PROJECT_ID:DATASET
の形式でプロジェクト ID をデータセットに追加します。
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
以下を置き換えます。
KEY:VALUE
: 追加するラベルの Key-Value ペア。キーは一意でなければなりません。PROJECT_ID
: プロジェクト ID。DATASET
: ラベルを付けるデータセット。
例:
部署を示すラベルを追加するには、bq update
コマンドを入力し、ラベルキーとして department
を指定します。たとえば、department:shipping
ラベルをデフォルト プロジェクト内の mydataset
に追加するには、次のように入力します。
bq update --set_label department:shipping mydataset
複数のラベルをデータセットに追加するには、set_label
フラグを繰り返し、ラベルごとに一意のキーを指定します。たとえば、department:shipping
ラベルと cost_center:logistics
ラベルをデフォルト プロジェクト内の mydataset
に追加するには、次のように入力します。
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
既存のデータセットにラベルを追加するには、datasets.patch
メソッドを呼び出して、データセット リソースの labels
プロパティを設定します。
datasets.update
メソッドはデータセット リソース全体を置き換えるので、datasets.patch
メソッドの方が適切です。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルは、Java 用の Google HTTP クライアント ライブラリを使用してリクエストを BigQuery API に送信します。
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
テーブルラベルとビューラベルの追加
テーブルまたはビューの作成時に次の方法でラベルを追加できます。
bq
コマンドライン ツールのbq mk
コマンドを使用するtables.insert
API メソッドを呼び出す
このページでは、既存のテーブルまたはビューにラベルを追加する方法について説明します。テーブルまたはビューの作成時にラベルを追加する方法について詳しくは、テーブルの作成またはビューの作成をご覧ください。
テーブルやビューの作成後に次の方法でラベルを追加できます。
- Cloud Console の使用
bq
コマンドライン ツールのbq update
コマンドを使用するtables.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
ビューはテーブル リソースと同様に扱われるため、tables.patch
メソッドを使用してビューとテーブルの両方を変更できます。
必要な権限
既存のテーブルまたはビューにラベルを追加するには、少なくとも bigquery.tables.update
権限と bigquery.tables.get
権限が必要です。次の事前定義済みの IAM ロールには bigquery.tables.update
権限と bigquery.tables.get
権限が含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、ユーザーはデータセット内のテーブルとビューにラベルを追加できます。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
テーブルまたはビューへのラベルの追加
既存のテーブルまたはビューにラベルを追加するには:
Console
Cloud Console で、テーブルまたはビューを選択します。
[詳細] タブをクリックします。
[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値に変更を加えます。
- [更新] をクリックして、変更を保存します。
SQL
データ定義言語(DDL)ステートメントを使用すると、標準 SQL クエリ構文を使用してテーブルとビューの作成と変更ができます。
データ定義言語ステートメントの使用をご覧ください。
Cloud Console で DDL ステートメントを使用してラベルを追加するには:
[クエリを新規作成] をクリックします。
[クエリエディタ] テキスト領域に DDL ステートメントを入力します。
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("department", "shipping"), ("cost_center", "logistics")] )
[実行] をクリックします。
bq
既存のテーブルまたはビューにラベルを追加するには、set_label
フラグを指定して bq update
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返し指定します。
テーブルまたはビューがデフォルト プロジェクト以外のプロジェクトにある場合は、project_id:dataset
の形式でプロジェクト ID をデータセットに追加します。
bq update \ --set_label KEY:VALUE \ PROJECT_ID:DATASET.TABLE_OR_VIEW
以下を置き換えます。
KEY:VALUE
: 追加するラベルの Key-Value ペア。キーは一意でなければなりません。PROJECT_ID
: プロジェクト ID。DATASET
: ラベルを付けるテーブルまたはビューを含むデータセット。TABLE_OR_VIEW
: ラベルを付けるテーブルまたはビューの名前。
例:
部署を示すテーブルラベルを追加するには、bq update
コマンドを入力し、ラベルキーとして department
を指定します。たとえば、department:shipping
ラベルをデフォルト プロジェクト内の mytable
に追加するには、次のように入力します。
bq update --set_label department:shipping mydataset.mytable
部署を示すビューラベルを追加するには、bq update
コマンドを入力し、ラベルキーとして department
を指定します。たとえば、department:shipping
ラベルをデフォルト プロジェクト内の myview
に追加するには、次のように入力します。
bq update --set_label department:shipping mydataset.myview
複数のラベルをテーブルまたはビューに追加するには、set_label
フラグを繰り返し、ラベルごとに一意のキーを指定します。たとえば、department:shipping
ラベルと cost_center:logistics
ラベルをデフォルト プロジェクト内の mytable
に追加するには、次のように入力します。
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset.mytable
API
既存のテーブルまたはビューにラベルを追加するには、tables.patch
メソッドを呼び出して、テーブル リソースの labels
プロパティを設定します。
ビューはテーブル リソースと同様に扱われるため、tables.patch
メソッドを使用してビューとテーブルの両方を変更できます。
tables.update
メソッドはデータセット リソース全体を置き換えるため、tables.patch
メソッドの方が適切です。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルは、Java 用の Google HTTP クライアント ライブラリを使用してリクエストを BigQuery API に送信します。
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
ジョブラベルの追加
bq
コマンドライン ツールを使用してクエリジョブにラベルを追加するには、--label
フラグを使用します。bq
ツールでは、クエリジョブにのみラベルを追加できます。
jobs.insert
メソッドを呼び出すときにジョブ構成で labels
プロパティを指定することで、API でジョブを送信する際にジョブにラベルを追加することもできます。API を使用すると、どのジョブタイプにもラベルを追加できます。
ジョブが保留中、実行中、完了済みの場合は、ラベルの追加や更新を行えません。
ジョブにラベルを追加すると、そのラベルが課金データとしてカウントされます。
必要な権限
ジョブにラベルを追加するための特別な権限は必要ありません。bigquery.jobs.create
権限がある場合、ジョブを送信するときにジョブにラベルを追加できます。
ジョブを実行するには、少なくとも bigquery.jobs.create
権限が必要です。bigquery.jobs.create
権限は、BigQuery によって自動的に作成されるジョブで必要とされ、ユーザーがプログラムで実行するジョブでも必要です。
次の事前定義済みの IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
ジョブへのラベルの追加
ジョブにラベルを追加するには:
Console
Cloud Console では、ジョブにラベルを追加できません。
bq
クエリジョブにラベルを追加するには、--label
フラグを指定して bq query
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返し指定します。--nouse_legacy_sql
フラグは、クエリが標準 SQL 構文であることを示します。
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
以下を置き換えます。
KEY:VALUE
: クエリジョブに追加するラベルの Key-Value ペア。キーは一意でなければなりません。複数のラベルをクエリジョブに追加するには、--label
フラグを繰り返し、ラベルごとに一意のキーを指定します。QUERY
: 有効な標準 SQL クエリ。
例:
クエリジョブにラベルを追加するには、次のように入力します。
bq query \
--label department:shipping \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
複数のラベルをクエリジョブに追加するには、--label
フラグを繰り返し、ラベルごとに一意のキーを指定します。たとえば、department:shipping
ラベルと cost_center:logistics
ラベルをクエリジョブに追加するには、次のように入力します。
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
ジョブにラベルを追加するには、jobs.insert
メソッドを呼び出して、ジョブ構成の labels
プロパティを設定します。API を使用して、任意のジョブタイプにラベルを追加できます。
タグの追加
値が空のキーを持つラベルはタグとして使用されます。新しいラベルを値なしで作成することも、既存のラベルをタグに変換することもできます。
リソースにラベルを付ける場合で key:value の形式が必要ない場合に、タグを利用できます。たとえば、あるテーブルに格納されているテストデータを複数のグループ(サポート、開発など)で使用する場合に、test_data
タグをテーブルに追加してそのことを示します。
タグを追加するには:
Console
Cloud Console で、適切なリソース(データセット、テーブル、ビュー)を選択します。
データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。
詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[ラベルを追加] をクリックして同じ手順を繰り返します。
- [更新] をクリックして、変更を保存します。
SQL
データ定義言語(DDL)ステートメントでは、標準 SQLクエリ構文を使用してテーブルとビューの作成と変更ができます。
データ定義言語ステートメントの使用をご覧ください。
Cloud Console で DDL ステートメントを使用してタグを追加するには:
[クエリを新規作成] をクリックします。
[クエリエディタ] テキスト領域に DDL ステートメントを入力します。
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("tag1", ""), ("tag2", "")] )
[実行] をクリックします。
bq
既存のリソースにタグを追加するには、set_label
フラグを指定して bq update
コマンドを使用します。キーを指定して、後ろにコロンを付けますが、値は指定しません。
bq update --set_label KEY: RESOURCE_ID
以下を置き換えます。
KEY:
: タグとして使用するラベルキー。RESOURCE_ID
: 有効なデータセット、テーブル、またはビュー名。リソースがデフォルト プロジェクト以外のプロジェクトにある場合は、PROJECT_ID:DATASET
の形式でプロジェクト ID を追加します。
例:
次のコマンドを入力して、mydataset.mytable
の test_data
タグを作成します。mydataset
はデフォルト プロジェクトにあります。
bq update --set_label test_data: mydataset
API
datasets.patch
メソッドまたは tables.patch
メソッドを呼び出して、データセット リソースまたはテーブル リソースに、値を空の文字列(""
)に設定したラベルを追加します。既存のラベルをタグに変換するには、その値を空の文字列で置き換えます。
ビューはテーブル リソースと同様に扱われるため、tables.patch
メソッドを使用してビューとテーブルの両方を変更できます。また、tables.update
メソッドはデータセット リソース全体を置き換えるため、tables.patch
メソッドを使用します。
次のステップ
- BigQuery リソースでラベルを表示する方法を学習する。
- BigQuery リソースでラベルを更新する方法を学習する。
- ラベルを使用してリソースをフィルタする方法を学習する。
- BigQuery リソースでラベルを削除する方法を学習する。
- Resource Manager ドキュメントでラベルの使用について読む。