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

このページでは、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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

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));
}

Node.js

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

GitHub で表示フィードバック

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

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

GitHub で表示フィードバック


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

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

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

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

GitHub で表示フィードバック

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

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));
}

Node.js

GitHub で表示フィードバック

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

GitHub で表示フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.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

ジョブラベルの追加

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 ドキュメントでラベルの使用について読む。

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

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

必要な権限

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

Console

bq

API

Go

Java

Node.js

Python

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

必要な権限

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

Console

SQL

bq

API

Go

Java

Node.js

Python

ジョブラベルの追加

必要な権限

ジョブへのラベルの追加

Console

bq

API

タグの追加

Console

SQL

bq

API

次のステップ

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