リソースへのラベルの追加

このページでは、BigQuery リソースにラベルを付ける方法について説明します。

データセットラベルの追加

BigQuery データセットを作成するときにラベルを追加するには、コマンドラインツールの bq mk コマンドを使用するか、API の datasets.insert メソッドを呼び出します。現時点では、GCP Console または従来の BigQuery ウェブ UI でデータセットを作成するときに、データセットにラベルを追加することはできません。

このページでは、作成したデータセットにラベルを追加する方法について説明します。データセットの作成時にラベルを追加する方法について詳しくは、データセットの作成をご覧ください。

ラベルは、データセットの作成後に次の方法で追加できます。

GCP Console または従来の BigQuery ウェブ UI
コマンドラインツールの bq update コマンドの使用
datasets.patch API メソッドの呼び出し
クライアントライブラリの使用

データセットにラベルを追加しても、データセット内のリソースには反映されません。データセットラベルはテーブルまたはビューに継承されません。データセットにラベルを追加すると、そのデータセットラベルはストレージの課金データとしてカウントされますが、ジョブ関連の課金データとして表示されることはありません。

必要な権限

既存のデータセットにラベルを追加するには、少なくとも bigquery.datasets.update 権限が必要です。事前定義された以下の Cloud IAM 役割には、bigquery.datasets.update 権限が含まれます。

bigquery.dataOwner
bigquery.admin

また、bigquery.datasets.create 権限があるユーザーがデータセットを作成すると、作成したデータセットに対する bigquery.dataOwner アクセス権がそのユーザーに付与されます。 bigquery.dataOwner アクセス権により、ユーザーはデータセットにラベルを追加できます。

BigQuery での Cloud IAM 役割と権限の詳細については、事前定義された役割と権限をご覧ください。

データセットへのラベルの追加

作成したデータセットにラベルを追加するには:

Console

GCP Console でデータセットを選択します。
データセットの詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- [更新] をクリックして、変更を保存します。

従来の UI

BigQuery ウェブ UI で、データセットを選択します。
[Dataset Details] ページの [Labels] の右にある [Edit] をクリックします。
[Edit Labels] ダイアログで:
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[Add Label] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- [OK] をクリックします。

CLI

既存のデータセットにラベルを追加するには、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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.DatasetMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

このサンプルは、Java 用の Google HTTP クライアントライブラリを使用してリクエストを BigQuery API に送信します。

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用の Java の設定手順に従ってください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用にある Python の設定手順に沿って設定を行ってください。詳細については、BigQuery Python API のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {"color": "green"}
dataset.labels = labels

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

テーブルラベルとビューラベルの追加

テーブルまたはビューの作成時に次の方法でラベルを追加できます。

コマンドラインツールの bq mk コマンドの使用
tables.insert API メソッドの呼び出し

このページでは、既存のテーブルまたはビューにラベルを追加する方法について説明します。テーブルまたはビューの作成時にラベルを追加する方法について詳しくは、テーブルの作成またはビューの作成をご覧ください。

テーブルやビューの作成後に次の方法でラベルを更新できます。

GCP Console または従来の BigQuery ウェブ UI
コマンドラインツールの bq update コマンドの使用
tables.patch API メソッドの呼び出し
クライアントライブラリの使用

ビューはテーブルリソースと同様に扱われるため、tables.patch メソッドを使用してビューとテーブルの両方を変更できます。

必要な権限

既存のテーブルまたはビューにラベルを追加するには、少なくとも bigquery.tables.update 権限と bigquery.tables.get 権限が必要です。次の定義済みの Cloud IAM の役割には、bigquery.tables.update 権限と bigquery.tables.get 権限が含まれています。

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

また、bigquery.datasets.create 権限があるユーザーがデータセットを作成すると、作成したデータセットに対する bigquery.dataOwner アクセス権がそのユーザーに付与されます。 bigquery.dataOwner アクセス権により、ユーザーはデータセット内のテーブルとビューにラベルを追加できます。

BigQuery での Cloud IAM 役割と権限の詳細については、事前定義された役割と権限をご覧ください。

テーブルまたはビューへのラベルの追加

既存のテーブルまたはビューにラベルを追加するには:

Console

GCP Console で、テーブルまたはビューを選択します。
[詳細] タブをクリックします。
[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値に変更を加えます。
- [更新] をクリックして、変更を保存します。

DDL

データ定義言語（DDL）ステートメントを使用すると、標準 SQL クエリ構文を使用してテーブルとビューを作成および変更できます。

データ定義言語ステートメントの使用をご覧ください。

GCP Console で DDL ステートメントを使用してラベルを追加するには:

[クエリを新規作成] をクリックします。

[クエリエディタ] テキスト領域に DDL ステートメントを入力します。

 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   labels=[("department", "shipping"), ("cost_center", "logistics")]
 )

[実行] をクリックします。

従来の UI

BigQuery ウェブ UI で、テーブルまたはビューを選択します。
詳細ページで、[Labels] の右にある [Edit] をクリックします。この例では、テーブルの詳細が表示されています。
[Edit Labels] ダイアログで:
- ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[Add Label] をクリックします。各キーは 1 つのテーブルまたはビューにつき 1 回だけ使用できますが、同じキーを別のデータセットのテーブルやビューでも使用できます。
- [OK] をクリックします。

CLI

既存のテーブルまたはビューにラベルを追加するには、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

GitHub で表示フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tbl := client.Dataset(datasetID).Table(tableID)
meta, err := tbl.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.TableMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

このサンプルは、Java 用の Google HTTP クライアントライブラリを使用してリクエストを BigQuery API に送信します。

GitHub で表示フィードバック

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Python

GitHub で表示フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

ジョブラベルの追加

コマンドラインツールを使用してクエリジョブにラベルを追加するには、--label フラグを使用します。コマンドラインツールでは、クエリジョブにのみラベルを追加できます。

jobs.insert メソッドを呼び出すときにジョブ構成で labels プロパティを指定することで、API でジョブを送信する際にジョブにラベルを追加することもできます。API を使用すると、どのジョブタイプにもラベルを追加できます。

ジョブが保留中、実行中、完了済みの場合は、ラベルの追加や更新を行えません。

ジョブにラベルを追加すると、そのラベルが課金データとしてカウントされます。

必要な権限

ジョブにラベルを追加するための特別な権限は必要ありません。bigquery.jobs.create 権限がある場合、ジョブを送信するときにジョブにラベルを追加できます。

ジョブを実行するには、少なくとも bigquery.jobs.create 権限が必要です。 bigquery.jobs.create 権限は、BigQuery によって自動的に作成されるジョブで必要とされ、ユーザーがプログラムで実行するジョブでも必要です。

bigquery.jobs.create 権限は、以下の事前定義された Cloud IAM 役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

BigQuery での Cloud IAM 役割と権限の詳細については、事前定義された役割と権限をご覧ください。

ジョブへのラベルの追加

ジョブにラベルを追加するには:

Console

GCP Console では、ジョブにラベルを追加できません。

従来の UI

ジョブへのラベルの追加は、従来の BigQuery ウェブ UI ではサポートされていません。

CLI

クエリジョブにラベルを追加するには、--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

GCP Console で、適切なリソース（データセット、テーブルまたはビュー）を選択します。
データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。
詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- [ラベルを追加] をクリックします。
- 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[ラベルを追加] をクリックして同じ手順を繰り返します。
- [更新] をクリックして、変更を保存します。

DDL

データ定義言語（DDL）ステートメントを使用すると、標準 SQL クエリ構文を使用してテーブルとビューを作成および変更できます。

データ定義言語ステートメントの使用をご覧ください。

GCP Console で DDL ステートメントを使用してタグを追加するには:

[クエリを新規作成] をクリックします。

[クエリエディタ] テキスト領域に DDL ステートメントを入力します。

 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   labels=[("tag1", ""), ("tag2", "")]
 )

[実行] をクリックします。

従来の UI

ウェブ UI で、該当するリソース（データセット、テーブルまたはビュー）を選択します。
データセットの場合は、[Dataset Details] ページが自動的に開きます。テーブルとビューの場合は、[Details] をクリックして詳細ページを開きます。
詳細ページで、[Labels] の右にある [Edit] をクリックします。
[Edit Labels] ダイアログで、次の操作を行います。
- 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[Add Label] をクリックします。
- [OK] をクリックします。

CLI

既存のリソースにタグを追加するには、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 ドキュメントでラベルの使用について読む。

データセット ラベルの追加

必要な権限

データセットへのラベルの追加

Console

従来の UI

CLI

API

Go

Java

Python

テーブルラベルとビューラベルの追加

必要な権限

テーブルまたはビューへのラベルの追加

Console

DDL

従来の UI

CLI

API

Go

Java

Python

ジョブラベルの追加

必要な権限

ジョブへのラベルの追加

Console

従来の UI

CLI

API

タグの追加

Console

DDL

従来の UI

CLI

API

次のステップ

フィードバックを送信...

データセットラベルの追加