ラベルの更新

このページでは、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 のロールと権限については、事前定義ロールと権限をご覧ください。

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

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

コンソール

  1. Google Cloud コンソールで、データセットを選択します。

  2. データセットの詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。

    ラベル鉛筆

  3. [ラベルの編集] ダイアログで、次の操作を行います。

    • 追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 度しか使用できませんが、同じキーが同じプロジェクト内の複数のデータセットで使用できます。
    • ラベルを更新するには、既存のキーまたは値を変更します。
    • [更新] をクリックして、変更を保存します。

SQL

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

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

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    ALTER SCHEMA mydataset
    SET OPTIONS (labels = [('sensitivity', 'high')]);
    

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

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

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 は更新するデータセットです。

例:

mydatasetdepartmentラベルを更新するには、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 のリファレンス ドキュメントをご覧ください。

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

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

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

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

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


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 のロールと権限については、事前定義ロールと権限をご覧ください。

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

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

コンソール

  1. Google Cloud コンソールで、テーブルまたはビューを選択します。

  2. [詳細] タブをクリックしてから、[ラベル] の右側にある鉛筆アイコンをクリックします。

  3. [ラベルの編集] ダイアログで、次の操作を行います。

    • 追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーは 1 つのテーブルまたはビューにつき 1 回だけ使用できますが、同じキーを別のデータセットのテーブルやビューでも使用できます。
    • ラベルを更新するには、既存のキーまたは値を変更します。
    • [更新] をクリックして、変更を保存します。

SQL

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

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

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

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

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

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

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 は、更新するテーブルまたはビューの名前です。

例:

mytabledepartment ラベルを更新するには、bq update コマンドを入力し、ラベルキーとして department を指定します。たとえば、mytabledepartment: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

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

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

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

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

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

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

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

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

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

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

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

# 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 のロールと権限については、事前定義ロールと権限をご覧ください。

タグへのラベルの変換

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

コンソール

  1. Google Cloud コンソールで、データセット、テーブル、またはビューを選択します。

  2. データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。

    テーブルの詳細

  3. 詳細ページで、[ラベル] の右にある鉛筆アイコンをクリックします。

    ラベル鉛筆

  4. [ラベルの編集] ダイアログで、次の操作を行います。

    • 既存のラベルの値を削除します。
    • [更新] をクリックします。

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 メソッドを使用します。

次のステップ