ラベルの追加と使用

BigQuery リソースを整理するために、データセット、テーブル、ビューにラベルを追加できます。ラベルとは、リソースに添付可能な Key-Value ペアです。BigQuery のリソースを作成するとき、ラベルは必須ではありません。

リソースにラベルを付けると、ラベル値に基づいてそのリソースを検索できるようになります。たとえば、ラベルを使用してデータセットを目的別、環境別、部署別などにグループ分けできます。

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

ラベルの管理については、ラベルの管理をご覧ください。

ラベルとは

ラベルとは、Google Cloud Platform の BigQuery リソースの整理に役立つ Key-Value ペアのことです。各リソースにラベルを設定し、そのラベルに基づいてリソースをフィルタリングできます。ラベルに関する情報は課金システムに転送されるため、ラベルを基準に請求料金を分析することもできます。

ラベルの一般的な用途

次に、ラベルの一般的な使用例を示します。

  • チームまたはコストセンターのラベル: 各チームが所有する BigQuery のリソースを区別するために、チームやコストセンターに基づいてラベルを追加します(team:researchteam:analytics など)。このタイプのラベルは、費用計算または予算作成に使用できます。

  • コンポーネント ラベル: component:rediscomponent:frontendcomponent:ingestcomponent:dashboard など。

  • 環境やステージのラベル: environment:productionenvironment:test など。

  • 状態のラベル: state:activestate:readytodeletestate:archive など。

ラベルの要件

リソースに適用するラベルは、次の要件を満たす必要があります。

  • 1 つのリソースには、最大 64 個のラベルを適用できます。
  • ラベルは、Key-Value ペアでなければなりません。
  • キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
  • キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
  • ラベルのキー部分は一意でなければなりません。ただし、複数のリソースで同じキーを使用できます。
  • キーは、小文字または国際文字で始める必要があります。

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

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

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

データセットにラベルを追加すると、そのデータセット ラベルはストレージの課金データとしてカウントされますが、ジョブ関連の課金データとして表示されることはありません。

必要な権限

既存のデータセットにラベルを追加するには、データセット レベルで OWNER アクセス権が付与されているか、bigquery.datasets.update 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。次の定義済みのプロジェクト レベルの IAM 役割には bigquery.datasets.update 権限が含まれます。

また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のデータセットを更新できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。 データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

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

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

Console

  1. BigQuery ウェブ UI で、データセットを選択します。

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

    ラベルの鉛筆

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

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

従来の UI

  1. BigQuery ウェブ UI で、データセットを選択します。

  2. [Dataset Details] ページの [Labels] の右にある [Edit] をクリックします。

    ラベル編集

  3. [Edit Labels] ダイアログで、次の操作を行います。

    • ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[Add Label] をクリックします。各キーはデータセットごとに 1 回だけ使用できますが、同じキーを同じプロジェクト内の複数のデータセットで使用できます。
    • ラベルを更新するには、既存のキーまたは値に変更を加えます。
    • [OK] をクリックします。

      新しいラベル

コマンドライン

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

// 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 にリクエストを送信します。
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 のリファレンス ドキュメントをご覧ください。

# 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 コマンドを使用するか、API の tables.insert メソッドを呼び出します。

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

テーブルまたはビューの作成後にラベルを追加するには、GCP Console、従来の BigQuery ウェブ UI、コマンドライン ツールの bq update コマンドを使用するか、API の tables.patch メソッドを呼び出します。ビューはテーブル リソースと同様に扱われるため、tables.patch メソッドを使用してビューとテーブルの両方を変更できます。

必要な権限

既存のテーブルまたはビューにラベルを追加するには、データセット レベルで OWNER アクセス権が付与されているか、bigquery.tables.update 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.tables.update 権限が含まれているものは次のとおりです。

また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のデータセット内のテーブルまたはビューを更新できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるテーブルとビューを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

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

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

Console

  1. BigQuery ウェブ UI で、テーブルまたはビューを選択します。

  2. [詳細] タブをクリックします。

    テーブルの詳細

  3. [ラベル] の右にある鉛筆アイコンをクリックします。

    ラベルの鉛筆

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

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

従来の UI

オプション 1: ラベルを手動で編集する 1. BigQuery ウェブ UI で、テーブルまたはビューを選択します。

  1. 詳細ページで、[Labels] の右にある [Edit] をクリックします。この例では、テーブルの詳細が表示されています。

    ラベル編集

  2. [Edit Labels] ダイアログで、次の操作を行います。

    • ラベルを追加するには、キーと値を入力します。追加のラベルを適用するには、[Add Label] をクリックします。各キーは 1 つのテーブルまたはビューにつき 1 回だけ使用できますが、同じキーを別のデータセットのテーブルやビューでも使用できます。
    • [OK] をクリックします。

      新しいラベル

オプション 2: DDL ステートメントを使用する

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

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

は、
  1. [COMPOSE QUERY] をクリックします。

  2. [New Query] テキスト領域に DDL ステートメントを入力します。

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

コマンドライン

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

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

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

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

# 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 を使用すると、どのジョブタイプにもラベルを追加できます。

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

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

必要な権限

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

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

BigQuery ジョブを実行するには、ユーザー アカウントまたはサービス アカウントに bigquery.jobs.create 権限を付与するか、bigquery.jobs.create 権限が含まれているプロジェクト レベルの事前定義された IAM 役割をアカウントに付与します。次の定義済みの IAM 役割には bigquery.jobs.create 権限が含まれています。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。

ジョブへのラベルの追加

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

Console

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

従来の UI

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

コマンドライン

クエリジョブにラベルを追加するには、--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 を使用して、任意のジョブタイプにラベルを追加できます。

Go

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

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

タグの作成

値が空のキーを持つラベルはタグとして使用されます。新しいラベルを値なしで作成することも、既存のラベルをタグに変換することもできます。

タグは、リソースにラベルを付けたいものの、Key-Value 形式は必要ない場合に役立ちます。たとえば、あるテーブルに格納されているテストデータを複数のグループ(サポート、開発など)で使用する場合に、test_data タグをテーブルに追加してそのことを示します。

タグを作成するには:

Console

  1. ウェブ UI で、該当するリソース(データセット、テーブル、またはビュー)を選択します。

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

    テーブルの詳細

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

    ラベルの鉛筆

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

    • [ラベルを追加] をクリックします。
    • 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[ラベルを追加] をクリックして同じ手順を繰り返します。
    • [更新] をクリックして、変更を保存します。

従来の UI

オプション 1: ラベルを手動で編集する

  1. ウェブ UI で、該当するリソース(データセット、テーブル、またはビュー)を選択します。

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

  3. 詳細ページで、[Labels] の右にある [Edit] をクリックします。

  4. [Edit Labels] ダイアログで、次の操作を行います。

    • 新しいキーを入力し、値を空白のままにします。追加のタグを適用するには、[Add Label] をクリックします。
    • [OK] をクリックします。

      タグを追加

オプション 2: DDL ステートメントを使用する

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

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

は、

  1. [COMPOSE QUERY] をクリックします。

  2. [New Query] テキスト領域に DDL ステートメントを入力します。

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

コマンドライン

既存のリソースにタグを追加するには、set_label フラグを指定して bq update コマンドを使用します。キーを指定して、後ろにコロンを付けますが、値は指定しません。

bq update --set_label [KEY]: [RESOURCE_ID]

ここで

  • [KEY] は、タグとして使用するラベルキーです。
  • [RESOURCE_ID] は、有効なデータセット、テーブル、またはビューの名前です。リソースがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID を追加します。

例:

mydataset.mytabletest_data タグを作成するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトにあります。

bq update --set_label test_data: mydataset

API

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

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

ラベルの表示

ラベルを表示するには、BigQuery ウェブ UI またはコマンドライン ツールの bq show コマンドを使用するか、API の datasets.get メソッドまたは tables.get メソッドを呼び出します。ビューはテーブル リソースと同様に扱われるため、tables.get メソッドを使用してビューとテーブルの両方のラベル情報を取得できます。

必要な権限

ラベルの表示に必要な権限は、アクセスするリソースの種類によって異なります。

データセットの権限

データセットに関する情報を取得するには、データセット レベルで READER 役割が割り当てられているか、bigquery.datasets.get 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.jobUser 以外には、bigquery.datasets.get 権限が含まれています。

また、bigquery.user 役割が割り当てられているユーザーには bigquery.datasets.create 権限もあります。そのため、bigquery.user 役割が割り当てられているユーザーは、自分が作成した任意のデータセットに関する情報を取得できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

テーブルとビューの権限

テーブルに関する情報を取得するユーザーには、データセットに対する READER 役割が付与されているか、事前定義されたプロジェクト レベルの IAM 役割のうち bigquery.tables.get 権限を含むものが割り当てられている必要があります。プロジェクト レベルで bigquery.tables.get 権限が付与されているユーザーは、そのプロジェクト内のすべてのテーブルに関する情報を取得できます。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.userbigquery.jobUser 以外には、bigquery.tables.get 権限が含まれています。

また、bigquery.user 役割が割り当てられているユーザーには bigquery.datasets.create 権限もあります。そのため、bigquery.user 役割が割り当てられているユーザーは、自分が作成した任意のデータセットに含まれるテーブルまたはビューの情報を取得できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルとビューを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

ジョブ権限

ジョブデータおよびメタデータを取得するには bigquery.jobs.get 権限が必要です。次の定義済みのプロジェクト レベルの IAM 役割には bigquery.jobs.get 権限が含まれます。

アカウントに bigquery.admin 役割を付与すると、そのユーザーは誰がジョブを送信したかに関係なく、プロジェクト内のすべてのジョブデータを表示できます。

次の役割には、自己作成ジョブに対する bigquery.jobs.get 権限が付与されています。これらのユーザーは、自分が送信したジョブのジョブデータのみを表示できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。

データセット、テーブル、ビューのラベルの表示

リソースのラベルを表示するには:

Console

  1. BigQuery ウェブ UI で、該当するリソース(データセット、テーブル、ビュー)を選択します。

  2. データセットの場合は、データセットの詳細ページが自動的に開きます。テーブルとビューの場合は、[詳細] をクリックして詳細ページを開きます。ラベル情報は、そのリソースの情報テーブルに表示されます。

    テーブルの詳細

従来の UI

  1. BigQuery ウェブ UI で、該当するリソース(データセット、テーブル、ビュー)を選択します。

  2. データセットの場合は、[Dataset Details] ページが自動的に開きます。テーブルとビューの場合は、[Details] をクリックして詳細ページを開きます。ラベル情報は、そのリソースの情報テーブルに表示されます。

コマンドライン

bq show コマンドを使用してリソース ID を指定します。--format フラグを使用して出力を制御できます。リソースがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID を追加します。出力を読みやすい形式にするには、--format フラグを pretty に設定します。

bq show --format=pretty [RESOURCE_ID]

[RESOURCE_ID] は、有効なデータセット、テーブル、またはビューの名前です。

例:

デフォルト プロジェクト内の mydataset のラベルを表示するには、次のコマンドを入力します。

bq show --format=pretty mydataset

次のコマンドを入力して、mydataset.mytable のラベルを表示します。 mydataset はデフォルト プロジェクトではなく myotherproject にあります。

bq show --format=pretty myotherproject:mydataset.mytable

API

datasets.get メソッドまたは tables.get メソッドを呼び出します。レスポンスには、そのリソースに関連付けられたすべてのラベルが含まれます。

または、datasets.list を使用して複数のデータセットのラベルを表示することも、tables.list を使用して複数のテーブルとビューのラベルを表示することもできます。

ビューはテーブル リソースと同様に扱われるため、tables.get および tables.list メソッドを使用してビューとテーブルの両方のラベル情報を表示できます。

Go

このサンプルは、Java 用の Google HTTP クライアント ライブラリを使用してリクエストを BigQuery API に送信します。
// 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")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print("Dataset ID: {}".format(dataset_id))
print("Labels:")
if dataset.labels:
    for label, value in dataset.labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tDataset has no labels defined.")

ジョブラベルの表示

クエリジョブが送信された後は、ジョブラベルが BigQuery ウェブ UI に表示されなくなります。ジョブラベルを表示するには、bq show -j [JOB_ID] コマンドを発行します。

Console

Console の BigQuery ウェブ UI を使用してジョブラベルを表示することはできません。

従来の UI

従来の BigQuery ウェブ UI を使用してジョブラベルを表示することはできません。

CLI

bq コマンドライン ツールを使用してクエリジョブのラベルを表示するには、クエリジョブのジョブ ID を指定して bq show -j コマンドを入力します。--format フラグを使用して出力を制御できます。たとえば、クエリジョブのジョブ ID が bqjob_r1234d57f78901_000023746d4q12_1 の場合は、次のコマンドを入力します。

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

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

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | email@example.com | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

jobs.get メソッドを呼び出します。レスポンスには、そのリソースに関連付けられたすべてのラベルが含まれます。

ラベルを使用したデータセットのフィルタリング

ラベルに基づいてデータセットをフィルタリングするには、bq コマンドライン ツールまたは BigQuery API で使用するフィルタ指定を次の構文で作成します。

    "field[:value][ field[:value]..."

ここで

  • fieldlabels.[KEY] として表されます。 [KEY] はラベルのキーです。
  • value はラベルの値です(省略可能)。

現時点では、フィルタ指定に基づいてテーブルまたはビューのリストを取得することはできません。

制限事項

フィルタ指定には以下の制限があります。

  • AND 論理演算子のみがサポートされています。スペース区切りで条件を列挙すると、暗黙的に AND 演算子があるものとして扱われます。
  • 現在フィルタリングの対象となるフィールドは「labels.key」(「key」はラベルの名前)のみです。
  • フィルタには最大 10 個の条件を含めることができます。
  • フィルタリング時は大文字と小文字が区別されます。
  • フィルタ指定を使用してテーブルまたはビューをフィルタリングすることはできません。
  • 現時点では、BigQuery ウェブ UI を使用してデータセットをフィルタリングすることはできません。

フィルタ指定の例

department:shipping ラベルを持つデータセットのリストを取得するには、次のフィルタ指定を使用します。

labels.department:shipping

複数のラベルを使用してデータセットのリストを取得するには、複数の Key-Value ペアをスペースで区切って指定します。このスペースは論理 AND 演算子として扱われます。たとえば、department:shipping ラベルと location:usa ラベルを持つデータセットのリストを取得するには、次のフィルタ指定を使用します。

labels.department:shipping labels.location:usa

Key-Value ペアに対して照合するのではなく、キーが存在するかどうかのみによってフィルタリングすることもできます。次のフィルタ指定を使用すると、値に関係なく department というラベルが付いたすべてのデータセットのリストが返されます。

labels.department

アスタリスクを使用して、これと同等のフィルタ指定を作成できます。アスタリスクは、department キーに関連付けられているすべての値を表します。

labels.department:*

フィルタ指定でタグを使用することもできます。たとえば、department:shipping ラベルと test_data タグを持つデータセットのリストを取得するには、次のフィルタ指定を使用します。

labels.department:shipping labels.test_data

フィルタリングされたリストの生成

フィルタリングされたデータセットのリストを生成するには:

Console

現時点では、Console の BigQuery ウェブ UI を使用してデータセットをフィルタリングすることはできません。

従来の UI

現時点では、従来の BigQuery ウェブ UI を使用してデータセットをフィルタリングすることはできません。

コマンドライン

--filter フラグを指定して bq ls コマンドを発行します。デフォルト プロジェクト以外のプロジェクトにあるデータセットのリストを取得する場合は、--project_id フラグを指定します。

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

ここで

  • [FILTER_SPECIFICATION] は、有効なフィルタ指定です。このコマンドを実行すると、フィルタ条件を満たすデータセットのリストが返されます。
  • [PROJECT_ID] はプロジェクト ID です。

例:

デフォルト プロジェクト内のデータセットのうち department:shipping ラベルを持つもののリストを取得するには、次のコマンドを入力します。

bq ls --filter "labels.department:shipping"

デフォルト プロジェクト内のデータセットのうち department:shipping ラベルと test_data タグを持つもののリストを取得するには、次のコマンドを入力します。

bq ls --filter "labels.department:shipping labels.test_data"

myotherproject 内のデータセットのうち department:shipping ラベルを持つもののリストを取得するには、次のコマンドを入力します。

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

API の datasets.list メソッドを呼び出し、filter プロパティを使用してフィルタの指定を行います。

Go

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

// 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")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:  # API request(s)
        print("\t{}".format(dataset.dataset_id))
else:
    print("No datasets found with this filter.")

次のステップ

このページは役立ちましたか?評価をお願いいたします。

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

ご不明な点がありましたら、Google のサポートページをご覧ください。