リソースへのラベルの追加
このページでは、BigQuery リソースにラベルを付ける方法について説明します。
始める前に
このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management(IAM)のロールを付与します。タスクの実行に必要な権限(存在する場合)は、タスクの「必要な権限」セクションに記載されています。
データセットへのラベルの追加
BigQuery データセットを作成するときにラベルを追加するには、bq
コマンドライン ツールの bq mk
コマンドを使用するか、API の datasets.insert
メソッドを呼び出します。現時点では、コンソールでデータセットを作成するときに、データセットにラベルを追加することはできません。
このページでは、作成したデータセットにラベルを追加する方法について説明します。データセットの作成時にラベルを追加する方法について詳しくは、データセットの作成をご覧ください。
データセットの作成後に、次の方法でラベルを追加できます。
- コンソールの使用
- SQL DDL ステートメントの使用
bq
コマンドライン ツールのbq update
コマンドを使用するdatasets.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
データセットにラベルを追加しても、データセット内のリソースには反映されません。データセット ラベルはテーブルまたはビューに継承されません。また、データセットにラベルを追加すると、そのデータセット ラベルはストレージの課金データとしてカウントされますが、ジョブ関連の課金データとしてはカウントされません。
ラベルの形式の詳細については、ラベルの要件をご覧ください。
必要な権限
既存のデータセットにラベルを追加するには、bigquery.datasets.update
IAM 権限が必要です。
次の IAM 事前定義ロールには、既存のデータセットにラベルを追加するために必要な権限が含まれています。
roles/bigquery.dataOwner
roles/bigquery.admin
また、bigquery.datasets.create
権限がある場合は、作成するデータセットにラベルを追加できます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
データセットへのラベルの追加
作成したデータセットにラベルを追加するには:
コンソール
コンソールで、データセットを選択します。
データセットの詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- 変更を保存するには、[更新] をクリックします。
SQL
既存のデータセットのラベルを設定するには、ALTER SCHEMA SET OPTIONS
DDL ステートメントを使用します。ラベルを設定すると、データセット内の既存のラベルが上書きされます。次の例では、データセット mydataset
にラベルを設定しています。
コンソールで、BigQuery ページに移動します。
クエリエディタで次のステートメントを入力します。
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリの実行をご覧ください。
bq
既存のデータセットにラベルを追加するには、set_label
フラグを指定して bq update
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返し指定します。
データセットがデフォルト プロジェクト以外のプロジェクトにある場合は、PROJECT_ID:DATASET
の形式でプロジェクト ID をデータセットに追加します。
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
以下を置き換えます。
KEY:VALUE
: 追加するラベルの Key-Value ペア。キーは一意でなければなりません。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。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 メソッドを呼び出す
このページでは、既存のテーブルまたはビューにラベルを追加する方法について説明します。テーブルまたはビューの作成時にラベルを追加する方法について詳しくは、テーブルの作成またはビューの作成をご覧ください。
テーブルやビューの作成後に次の方法でラベルを追加できます。
- コンソールの使用
bq
コマンドライン ツールのbq update
コマンドを使用するtables.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
ビューはテーブル リソースと同様に扱われるため、tables.patch
メソッドを使用してビューとテーブルの両方を変更できます。
必要な権限
既存のテーブルまたはビューにラベルを追加するには、次の IAM 権限が必要です。
bigquery.tables.update
bigquery.tables.get
次の IAM 事前定義ロールには、既存のテーブルまたはビューにラベルを追加するために必要な権限が含まれています。
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
また、bigquery.datasets.create
権限がある場合は、作成したデータセット内のテーブルとビューにラベルを追加できます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
テーブルまたはビューへのラベルの追加
既存のテーブルまたはビューにラベルを追加するには:
コンソール
コンソールで、テーブルまたはビューを選択します。
[詳細] タブをクリックします。
[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値に変更を加えます。
- [更新] をクリックして、変更を保存します。
SQL
既存のテーブルにラベルを設定するには、ALTER TABLE SET OPTIONS
DDL ステートメント、または既存のビューのラベルを設定するには、ALTER VIEW SET OPTIONS
DDL ステートメントを使用します。ラベルを設定すると、テーブルまたはビューの既存のラベルが上書きされます。次の例では、テーブル mytable
に 2 つのラベルを設定しています。
コンソールで、BigQuery ページに移動します。
クエリエディタで次のステートメントを入力します。
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 ペア。キーは一意でなければなりません。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。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
IAM 権限が必要です。
次の IAM 事前定義ロールには、ジョブにラベルを追加するために必要な権限が含まれています。
roles/bigquery.user
roles/bigquery.jobUser
roles/bigquery.admin
BigQuery ジョブを実行するには、bigquery.jobs.create
IAM 権限が必要です。この権限により、プログラムでジョブを実行し、BigQuery がユーザーに代わって自動的に実行するジョブの権限を付与できます。
次の IAM 事前定義ロールには、ジョブの実行に必要な権限が含まれています。
roles/bigquery.user
roles/bigquery.jobUser
roles/bigquery.admin
また、ジョブを作成すると、そのジョブに対する次の権限が自動的に付与されます。
bigquery.jobs.get
bigquery.jobs.update
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
ジョブへのラベルの追加
ジョブにラベルを追加するには:
bq
クエリジョブにラベルを追加するには、--label
フラグを指定して bq query
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返します。--nouse_legacy_sql
フラグは、クエリが標準 SQL 構文であることを示します。
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
以下を置き換えます。
KEY:VALUE
: クエリジョブに追加するラベルの Key-Value ペア。キーは一意でなければなりません。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。複数のラベルをクエリジョブに追加するには、--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 を使用して、任意のジョブタイプにラベルを追加できます。
セッション内のジョブをラベルに関連付ける
セッションでクエリを実行する場合は、BigQuery 複数ステートメント クエリを使用して、セッション内の今後のすべてのクエリジョブにラベルを割り当てることができます。
SQL
次のクエリを実行して、セッションで @@query_label
システム変数を設定します。
SET @@query_label = "KEY:VALUE";
- KEY:VALUE: セッション内の今後のクエリすべてに割り当てるラベルの Key-Value ペア。キーは一意でなければなりません。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
例:
SET @@query_label = "cost_center:logistics";
API
API 呼び出しを使用してクエリを実行するときに、セッション内のクエリジョブにラベルを追加するには、jobs.insert
メソッドを呼び出し、connectionProperties
ジョブ構成の query_label
プロパティを設定します。
クエリラベルをセッションに関連付けて、セッション内でクエリを実行した後、そのクエリラベルを持つクエリの監査ログを収集できます。詳細については、BigQuery の監査ログ リファレンスをご覧ください。
タグの追加
値が空のキーを持つラベルはタグとして使用されます。新しいラベルを値なしで作成することも、既存のラベルをタグに変換することもできます。
タグは、リソースにラベルを付けたいものの、Key-Value 形式は必要ない場合に役立ちます。たとえば、あるテーブルに複数のグループ(サポート、開発など)で使用されているテストデータが含まれている場合、test_data
タグをテーブルに追加してそのことを示します。
タグを追加するには:
コンソール
コンソールで、適切なリソース(データセット、テーブル、ビュー)を選択します。
データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。
詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[ラベルを追加] をクリックして同じ手順を繰り返します。
- 変更を保存するには、[更新] をクリックします。
SQL
データ定義言語(DDL)ステートメントでは、標準 SQLクエリ構文を使用してテーブルとビューの作成と変更ができます。
データ定義言語ステートメントの使用をご覧ください。
コンソールで 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 ドキュメントでラベルの使用について読む。