ラベルの更新

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

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。タスクの実行に必要な権限（存在する場合）は、タスクの「必要な権限」セクションに記載されています。

データセットラベルの更新

データセットラベルは、次の方法で更新できます。

Google Cloud コンソールを使用する
SQL DDL ステートメントを使用する
bq コマンドラインツールの bq update コマンドを使用する
datasets.patch API メソッドを呼び出す
クライアントライブラリを使用する

必要な権限

データセットラベルを更新するには、bigquery.datasets.update IAM 権限が必要です。

次の各事前定義 IAM ロールには、データセットラベルの更新に必要な権限が含まれています。

roles/bigquery.dataOwner
roles/bigquery.admin

また、bigquery.datasets.create 権限がある場合は、作成したデータセットのラベルを更新できます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

データセットラベルの更新

データセットのラベルを更新するには、次のいずれかを選択します。

コンソール

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

SQL

既存のデータセットのラベルを設定するには、ALTER SCHEMA SET OPTIONS DDL ステートメントを使用します。ラベルを設定すると、データセット内の既存のラベルが上書きされます。次の例では、データセット mydataset に単一のラベルを設定します。

Google Cloud コンソールで [BigQuery] ページに移動します。

[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 ペアに対応します。既存のラベルと同じキーを指定した場合は、その既存ラベルの値が更新されます。キーは一意でなければなりません。
project_id はプロジェクト ID です。
dataset は更新するデータセットです。

例:

mydataset の departmentラベルを更新するには、bq update コマンドを入力し、ラベルキーとして department を指定します。たとえば、department:shipping ラベルを department:logistics に更新するには、次のコマンドを入力します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

出力は次のようになります。

Dataset 'myotherproject:mydataset' successfully updated.

API

既存のデータセットのラベルを追加または更新するには、datasets.patch メソッドを呼び出して、データセットリソースの labels プロパティを追加または更新します。

datasets.update メソッドはデータセットリソース全体を置き換えるため、datasets.patch メソッドの方が適切です。

Go

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

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

// 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 のリファレンスドキュメントをご覧ください。


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

テーブルとビューのラベルの更新

テーブルやビューを作成した後にラベルを更新するには、次の方法を使用できます。

Google Cloud コンソールを使用する
bq コマンドラインツールの bq update コマンドを使用する
tables.patch API メソッドを呼び出す
- ビューはテーブルリソースと同様に扱われるため、tables.patch メソッドを使用してビューとテーブルの両方を変更できます。
クライアントライブラリを使用する

必要な権限

テーブルまたはビューのラベルを更新するには、bigquery.tables.update IAM 権限が必要です。

次の各事前定義 IAM ロールには、それぞれテーブルまたはビューのラベルを更新するために必要な権限が含まれています。

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

また、bigquery.datasets.create 権限がある場合は、作成したデータセット内のテーブルとビューのラベルを更新できます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

テーブルまたはビューのラベルの更新

テーブルまたはビューのラベルを更新するには:

コンソール

Google Cloud コンソールで、テーブルまたはビューを選択します。
[詳細] タブをクリックしてから、[ラベル] の右側にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- 追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーは 1 つのテーブルまたはビューにつき 1 回だけ使用できますが、同じキーを別のデータセットのテーブルやビューでも使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- [更新] をクリックして、変更を保存します。

SQL

既存のテーブルにラベルを設定するには、ALTER TABLE SET OPTIONS DDL ステートメント、または既存のビューにラベルを設定するには、ALTER VIEW SET OPTIONS DDL ステートメントを使用します。ラベルを設定すると、テーブルまたはビューの既存のラベルが上書きされます。次の例では、テーブル mytable に 2 つのラベルを設定します。

Google Cloud コンソールで [BigQuery] ページに移動します。

[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 ペアに対応します。既存のラベルと同じキーを指定した場合は、その既存ラベルの値が更新されます。キーは一意でなければなりません。
project_id はプロジェクト ID です。
dataset は、更新するテーブルまたはビューが含まれるデータセットです。
table_or_view は、更新するテーブルまたはビューの名前です。

例:

mytable の department ラベルを更新するには、bq update コマンドを入力し、ラベルキーとして department を指定します。たとえば、mytable の department:shipping ラベルを department:logistics に更新するには、次のコマンドを入力します。mytable はデフォルトプロジェクトではなく myotherproject にあります。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

出力は次のようになります。

Table 'myotherproject:mydataset.mytable' successfully updated.

API

既存のテーブルまたはビューのラベルを追加または更新するには、tables.patch メソッドを呼び出して、テーブルリソースの labels プロパティを追加または更新します。

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

tables.update メソッドはデータセットリソース全体を置き換えるため、tables.patch メソッドの方が適切です。

Go

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 に送信します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

// 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

# 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

ジョブラベルの更新

現在、ジョブラベルの更新はサポートされていません。ジョブのラベルを更新するには、新しいラベルを指定してジョブを再送信してください。

ラベルをタグに変換する

値が空のキーを持つラベルはタグとして使用されます。新しいラベルを値なしで作成したり、既存のラベルをデータセット、表、ビューのタグに変換したりできます。ジョブラベルをタグに変換することはできません。

リソースにラベルを付ける場合で key:value の形式が必要ない場合に、タグを利用できます。たとえば、あるテーブルに格納されているテストデータを複数のグループ（サポート、開発など）で使用する場合に、test_data タグをテーブルに追加してそのことを示します。

必要な権限

ラベルをタグに変換するには、次の IAM 権限が必要です。

bigquery.datasets.update（データセットラベルを変換）
bigquery.tables.update（テーブルまたはビューラベルを変換）

次の各事前定義 IAM ロールには、データセットラベルを変換するために必要な権限が含まれています。

roles/bigquery.dataOwner
roles/bigquery.admin

次の事前定義 IAM ロールには、それぞれテーブルまたはビューのラベルを変換するために必要な権限が含まれています。

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

また、bigquery.datasets.create 権限がある場合は、作成したデータセットのラベルと、それらのデータセット内のテーブルとビューを更新できます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

タグへのラベルの変換

ラベルをタグに変換するには:

コンソール

Google Cloud コンソールで、データセット、テーブル、またはビューを選択します。
データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。
詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。
[ラベルの編集] ダイアログで、次の操作を行います。
- 既存のラベルの値を削除します。
- [更新] をクリックします。

bq

ラベルをタグに変換するには、bq update コマンドに set_label フラグを指定します。キーを指定して、後ろにコロンを付けますが、値は指定しません。これにより、既存のラベルがタグに更新されます。

bq update \
--set_label key: \
resource_id

ここで

key: はタグに更新するラベルキーです。
resource_id は、有効なデータセット、テーブル、またはビューの名前です。リソースがデフォルトプロジェクト以外のプロジェクトにある場合は、project_id:dataset の形式でプロジェクト ID を追加します。

例:

次のコマンドを入力して、mydataset の既存の test_data:development ラベルをタグに変更します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

bq update --set_label test_data: myotherproject:mydataset

出力は次のようになります。

Dataset 'myotherproject:mydataset' successfully updated.

API

既存のラベルをタグに変換するには、datasets.patch メソッドまたは tables.patch メソッドを呼び出し、データセットリソースまたはテーブルリソース内のラベル値を空の文字列（""）に置き換えます。

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

次のステップ

BigQuery リソースにラベルを追加する方法を学習する。
BigQuery リソースでラベルを表示する方法を学習する。
ラベルを使用してリソースをフィルタする方法を学習する。
BigQuery リソースでラベルを削除する方法を学習する。
Resource Manager ドキュメントでラベルの使用について読む。

ラベルの更新

始める前に

データセット ラベルの更新

必要な権限

データセット ラベルの更新

コンソール

SQL

bq

API

Go

Java

Node.js

Python

テーブルとビューのラベルの更新

必要な権限

テーブルまたはビューのラベルの更新

コンソール

SQL

bq

API

Go

Java

Node.js

Python

ジョブラベルの更新

ラベルをタグに変換する

必要な権限

タグへのラベルの変換

コンソール

bq

API

次のステップ

データセットラベルの更新

データセットラベルの更新