リソースへのラベルの追加
このページでは、BigQuery リソースにラベルを付ける方法について説明します。
始める前に
このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management(IAM)のロールを付与します。タスクの実行に必要な権限は、タスクの「必要な IAM のロール」に記載されています。
データセットへのラベルの追加
BigQuery データセットを作成するときにラベルを追加するには、bq コマンドライン ツールの bq mk
コマンドを使用するか、datasets.insert
API メソッドを呼び出します。現時点では、Google Cloud コンソールでデータセットを作成するときに、データセットにラベルを追加することはできません。
このページでは、作成したデータセットにラベルを追加する方法について説明します。データセットの作成時にラベルを追加する方法について詳しくは、データセットの作成をご覧ください。
データセットの作成後に、次の方法でラベルを追加できます。
- Google Cloud コンソールの使用
- SQL DDL ステートメントの使用
- bq コマンドライン ツールの
bq update
コマンドの使用 datasets.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
データセットにラベルを追加しても、データセット内のリソースには反映されません。データセット ラベルはテーブルまたはビューに継承されません。また、データセットにラベルを追加すると、そのデータセット ラベルはストレージの課金データとしてカウントされますが、ジョブ関連の課金データとしてはカウントされません。
ラベルの形式の詳細については、ラベルの要件をご覧ください。
必要な IAM のロール
既存のデータセットにラベルを追加するために必要な権限を取得するには、BigQuery データ編集者(roles/bigquery.dataEditor
)の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、既存のデータセットにラベルを追加するために必要な bigquery.datasets.update
権限が含まれています。
カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
データセットへのラベルの追加
作成したデータセットにラベルを追加するには:
コンソール
Google Cloud コンソールで、データセットを選択します。
データセットの詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- 変更を保存するには、[更新] をクリックします。
SQL
既存のデータセットのラベルを設定するには、ALTER SCHEMA SET OPTIONS
DDL ステートメントを使用します。ラベルを設定すると、データセット内の既存のラベルが上書きされます。次の例では、データセット mydataset
にラベルを設定しています。
Google Cloud コンソールで [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 のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
このサンプルは、Java 用の Google HTTP クライアント ライブラリを使用してリクエストを BigQuery API に送信します。
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
テーブルとビューへのラベルの追加
テーブルまたはビューの作成時に次の方法でラベルを追加できます。
- bq コマンドライン ツールの
bq mk
コマンドの使用 tables.insert
API メソッドを呼び出す
このページでは、既存のテーブルまたはビューにラベルを追加する方法について説明します。テーブルまたはビューの作成時にラベルを追加する方法について詳しくは、テーブルの作成またはビューの作成をご覧ください。
テーブルやビューの作成後に次の方法でラベルを追加できます。
- Google Cloud コンソールを使用する
- bq コマンドライン ツールの
bq update
コマンドの使用 tables.patch
API メソッドを呼び出す- クライアント ライブラリを使用する
ビューはテーブル リソースと同様に扱われるため、tables.patch
メソッドを使用してビューとテーブルの両方を変更できます。
必要な IAM のロール
既存のテーブルまたはビューにラベルを追加するために必要な権限を取得するには、BigQuery データ編集者(roles/bigquery.dataEditor
)の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、既存のテーブルまたはビューにラベルを追加するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
既存のテーブルまたはビューにラベルを追加するには、次の権限が必要です。
-
bigquery.tables.update
-
bigquery.tables.get
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
テーブルまたはビューへのラベルの追加
既存のテーブルまたはビューにラベルを追加するには:
コンソール
Google Cloud コンソールで、テーブルまたはビューを選択します。
[詳細] タブをクリックします。
[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値に変更を加えます。
- [更新] をクリックして、変更を保存します。
SQL
既存のテーブルにラベルを設定するには、ALTER TABLE SET OPTIONS
DDL ステートメント、または既存のビューのラベルを設定するには、ALTER VIEW SET OPTIONS
DDL ステートメントを使用します。ラベルを設定すると、テーブルまたはビューの既存のラベルが上書きされます。次の例では、テーブル mytable
に 2 つのラベルを設定しています。
Google Cloud コンソールで [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 のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
このサンプルは、Java 用の Google HTTP クライアント ライブラリを使用してリクエストを BigQuery API に送信します。
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
ジョブへのラベルの追加
bq コマンドライン ツールを使用してクエリジョブにラベルを追加するには、--label
フラグを使用します。bq ツールは、クエリジョブにのみラベルの追加をサポートしています。
jobs.insert
メソッドを呼び出すときにジョブ構成で labels
プロパティを指定することで、API でジョブを送信する際にジョブにラベルを追加することもできます。API を使用すると、どのジョブタイプにもラベルを追加できます。
ジョブが保留中、実行中、完了済みの場合は、ラベルの追加や更新を行えません。
ジョブにラベルを追加すると、そのラベルが課金データとしてカウントされます。
必要な IAM のロール
ジョブにラベルを追加するために必要な権限を取得するには、BigQuery ユーザー(roles/bigquery.user
)の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、ジョブにラベルを追加するために必要な bigquery.jobs.create
権限が含まれています。
カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
ジョブへのラベルの追加
ジョブにラベルを追加するには:
bq
クエリジョブにラベルを追加するには、--label
フラグを指定して bq query
コマンドを発行します。複数のラベルを追加するには、このフラグを繰り返します。--nouse_legacy_sql
フラグは、クエリが GoogleSQL 構文であることを示します。
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
以下を置き換えます。
KEY:VALUE
: クエリジョブに追加するラベルの Key-Value ペア。キーは一意でなければなりません。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。複数のラベルをクエリジョブに追加するには、--label
フラグを繰り返し、ラベルごとに一意のキーを指定します。QUERY
: 有効な GoogleSQL クエリ。
例:
クエリジョブにラベルを追加するには、次のように入力します。
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 ペア。複数の Key-Value ペアをカンマで区切って追加することもできます(例:
SET @@query_label = "key1:value1,key2:value2"
)。キーは一意にする必要があります。キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
例:
SET @@query_label = "cost_center:logistics";
API
API 呼び出しを使用してクエリを実行するときに、セッション内のクエリジョブにラベルを追加するには、jobs.insert
メソッドを呼び出し、connectionProperties
ジョブ構成の query_label
プロパティを設定します。
クエリラベルをセッションに関連付けて、セッション内でクエリを実行した後、そのクエリラベルを持つクエリの監査ログを収集できます。詳細については、BigQuery の監査ログ リファレンスをご覧ください。
値のないラベルの追加
値が空のキーを持つラベルは、タグと呼ばれることもあります。これは、タグリソースとは異なります。詳細については、ラベルとタグをご覧ください。値のない新しいラベルを作成することも、既存のラベルキーから値を削除することもできます。
リソースにラベルを付ける際に、Key-Value 形式が必要ない場合は、値のないラベルが便利です。たとえば、サポートや開発などの複数のグループで使用されるテストデータがテーブルに含まれている場合は、test_data
ラベルをテーブルに追加して識別できます。
値のないラベルを追加するには、次の手順を行ってください。
コンソール
Google Cloud コンソールで、適切なリソース(データセット、テーブル、ビュー)を選択します。
データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。
詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- 新しいキーを入力し、値を空白のままにします。追加のラベルを適用するには、[ラベルを追加] をクリックして手順を繰り返します。
- 変更を保存するには、[更新] をクリックします。
SQL
値のないラベルを追加するには、ALTER TABLE SET OPTIONS
DDL ステートメントを使用します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
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 ドキュメントでラベルの使用について読む。