ラベルの作成と管理

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

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

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

ラベルとは

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

ラベルの一般的な用途

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

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

  • コンポーネント ラベル: component:rediscomponent:frontendcomponent:ingestcomponent:dashboard などがあります。

  • 環境またはステージのラベル: environment:productionenvironment:test などがあります。

  • オーナーまたは連絡先のラベル: BigQuery リソースのオーナーまたは主要な連絡先に基づいてラベルを追加します。

  • 状態のラベル: state:activestate:readytodeletestate:archive などがあります。

ラベルの要件

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

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

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

BigQuery データセットを作成するときにラベルを追加するには、コマンドライン ツールの bq mk コマンドを使用するか、API の datasets.insert メソッドを呼び出します。データセットの作成時にラベルを追加する方法の詳細については、データセットの作成をご覧ください。

データセットを作成した後にラベルを追加または更新するには、BigQuery ウェブ UI またはコマンドライン ツールの bq update コマンドを使用するか、API の datasets.patch メソッドを呼び出します。

必要な権限

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

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

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

データセット ラベルの作成または更新

データセット ラベルを更新する、またはデータセットの作成後にラベルを追加するには:

ウェブ UI

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

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

    ラベルを編集

  3. [Edit Labels] ダイアログで:

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

      新しいラベル

コマンドライン

データセット ラベルを追加または更新するには、bq update コマンドを発行して set_label フラグを指定します。複数のラベルを追加または更新するには、このフラグを繰り返し指定します。

データセットがデフォルト プロジェクト以外のプロジェクトにある場合は、[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

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

    bq update --set_label department:logistics myotherproject:mydataset

複数のラベルをデータセットに追加するには、set_label フラグを繰り返し、ラベルごとに一意のキーを指定します。データセットの複数のラベルを削除するには、clear_label フラグを繰り返し、各 Key-Value ペアを指定します。たとえば、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

このサンプルは、Google HTTP Client Library for Java を使用してリクエストを 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 メソッドを呼び出します。テーブルまたはビューの作成時にラベルを追加する方法の詳細については、テーブルの作成またはビューの作成をご覧ください。

テーブルやビューを作成した後にラベルを追加または更新するには、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 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

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

テーブルまたはビューのラベルを更新する、またはテーブルまたはビューの作成後にラベルを追加するには:

ウェブ UI

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

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

    ラベルを編集

  3. [Edit Labels] ダイアログで:

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

      新しいラベル

コマンドライン

テーブルまたはビューのラベルを追加または更新するには、bq update コマンドを発行して set_label フラグを指定します。複数のラベルを追加または更新するには、このフラグを繰り返し指定します。

テーブルまたはビューがデフォルト プロジェクト以外のプロジェクトにある場合は、[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

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

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

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

このサンプルは、Google HTTP Client Library for Java を使用してリクエストを 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

ラベルの削除

データセット、テーブル、ビューのラベルを削除するには、BigQuery ウェブ UI またはコマンドライン ツールの bq update コマンドを使用するか、API の datasets.patch メソッドまたは tables.patch メソッドを呼び出します。

データセット ラベルの削除

データセット ラベルを削除するには、BigQuery ウェブ UI またはコマンドライン ツールの bq update コマンドを使用するか、API の datasets.patch メソッドを呼び出します。

必要な権限

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

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

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

データセット ラベルの削除

データセットからラベルを削除するには:

ウェブ UI

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

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

  3. [Edit Labels] ダイアログで:

    • 削除する各ラベルの削除アイコン(X)をクリックします。
    • [OK] をクリックします。

      ラベルを削除

コマンドライン

データセット ラベルを追加または更新するには、bq update コマンドを発行して clear_label フラグを指定します。複数のラベルを削除するには、このフラグを繰り返します。

データセットがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセットに追加します。

    bq update --clear_label [KEY] [PROJECT_ID]:[DATASET]

ここで:

  • [KEY] は削除するラベルのキーです。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] は更新するデータセットです。

例:

department:shipping ラベルを mydataset から削除するには、bq update コマンドで --clear_label フラグを使用します。mydataset はデフォルト プロジェクトにあります。

    bq update --clear_label department mydataset

department:shipping ラベルを myotherproject 内の mydataset から削除するには、bq update コマンドで --clear_label フラグを使用します。

    bq update --clear_label department myotherproject:mydataset

複数のラベルをデータセットから削除するには、clear_label フラグを繰り返して各ラベルのキーを指定します。たとえば、department:shipping ラベルと cost_center:logistics ラベルをデフォルト プロジェクト内の mydataset から削除するには、次のように入力します。

    bq update --clear_label department --clear_label cost_center mydataset

API

既存データセットの特定のラベルを削除するには、datasets.patch メソッドを呼び出して、ラベルの Key-Value を null に設定することでデータセット リソースlabels プロパティを更新します。

データセットのすべてのラベルを削除するには、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.DeleteLabel("color")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

このサンプルを試す前に、クライアント ライブラリを使用する BigQuery Quickstart の 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

# This example dataset starts with one label
assert dataset.labels == {'color': 'green'}
# To delete a label from a dataset, set its value to None
dataset.labels['color'] = None

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

assert dataset.labels == {}

テーブルまたはビューのラベルの削除

テーブルまたはビューのラベルを削除するには、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 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

テーブルまたはビューのラベルの削除

テーブルまたはビューからラベルを削除するには:

ウェブ UI

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

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

  3. [Edit Labels] ダイアログで:

    • 削除する各ラベルの削除アイコン(X)をクリックします。
    • [OK] をクリックします。

      ラベルを削除

コマンドライン

テーブルまたはビューのラベルを削除するには、bq update コマンドを発行して clear_label フラグを指定します。複数のラベルを削除するには、このフラグを繰り返します。

テーブルまたはビューがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセットに追加します。

    bq update --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]

ここで:

  • [KEY] は削除するラベルのキーです。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] は更新するデータセットです。
  • [TABLE_OR_VIEW] は、更新するテーブルまたはビューの名前です。

例:

department:shipping ラベルを mydataset.mytable から削除するには、bq update コマンドで --clear_label フラグを使用します。mydataset はデフォルト プロジェクトにあります。

    bq update --clear_label department mydataset.mytable

department:shipping ラベルを myotherproject 内の mydataset.myview から削除するには、bq update コマンドで --clear_label フラグを使用します。

    bq update --clear_label department myotherproject:mydataset.myview

複数のラベルをテーブルまたはビューから削除するには、clear_label フラグを繰り返して各ラベルのキーを指定します。たとえば、department:shipping ラベルと cost_center:logistics ラベルをデフォルト プロジェクト内の mydataset.mytable から削除するには、次のように入力します。

    bq update --clear_label department --clear_label cost_center mydataset.mytable

API

既存テーブルや既存ビューの特定のラベルを削除するには、tables.patch メソッドを呼び出して、ラベルの Key-Value を null に設定することでテーブル リソースlabels プロパティを更新します。

特定のテーブルやビューからラベルをすべて削除するには、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.DeleteLabel("color")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

このサンプルを試す前に、クライアント ライブラリを使用する BigQuery Quickstart の 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

# This example table starts with one label
assert table.labels == {'color': 'green'}
# To delete a label from a table, set its value to None
table.labels['color'] = None

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

assert table.labels == {}

タグの作成

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

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

タグを作成するには:

ウェブ UI

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

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

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

  4. [Edit Labels] ダイアログで:

    • 新しいキーを入力して値を空白のままにします。または、既存のラベルの値を削除します。追加のタグを適用するには、[Add Label] をクリックします。
    • [OK] をクリックします。

      タグを追加

コマンドライン

bq update コマンドで set_label フラグを使用します。キーを指定して、後ろにコロンを付けますが、値は指定しません。この方法で既存のラベルをタグに更新したり、新しいタグを追加したりできます。

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

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

bq update --set_label test_data: myotherproject: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 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

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

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

ウェブ UI

  1. ウェブ 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

このサンプルを試す前に、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")
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 Quickstart の 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.")

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

ラベルに基づいてデータセットをフィルタリングするには、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

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

labels.department

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

labels.department:*

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

labels.department:shipping labels.test_data

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

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

ウェブ UI

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

コマンドライン

bq ls コマンドを発行して --filter フラグを指定します。デフォルト プロジェクト以外のプロジェクトにあるデータセットのリストを生成する場合は、--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 Quickstart の 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 のサポートページをご覧ください。