ラベルの作成と管理

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

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

制限事項

BigQuery のラベルには以下の制限があります。

  • 各リソースには最大 64 個のラベルを付けることができます。
  • ラベルのキーと値は、63 文字以内でなければなりません。
  • ラベルのキーと値には、小文字の英字、数字、アンダースコア、ハイフン、国際文字のみを使用できます。
  • ラベルのキーと値は、128 バイト以内でなければなりません。
  • ラベルのキーは文字で始まる必要があります。
  • ラベルのキーは必須ですが、値は空でもかまいません。値を持たないラベルはタグとして使用できます。
  • ある特定のラベルキーはリソースごとに 1 回だけ使用できます。たとえば、キー値が organization であるデータセット ラベルまたはテーブルラベルを 1 つだけ設定できます。
  • ラベルをテーブルまたはビューに追加するとき、ラベルのキーはデータセット内で一意である必要があります。同じデータセット内の 2 つの異なるテーブルまたはビューに対して同じキーを使用することはできません。
  • ラベルをデータセットに追加するとき、ラベルのキーはプロジェクト内で一意でなくてもかまいませんが、データセット単位では一意でなければなりません。たとえば、同じプロジェクト内の 2 つのデータセットがラベルキー department を持つことができますが、department キーを使用できるのはデータセットごとに 1 回だけです。

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

データセットを作成するときにラベルを追加するには、コマンドライン ツールの 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 メソッドの方が適切です。

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

このサンプルは、Google Auth Library for Python を使用して、Requests セッションと互換性のある AuthorizedSession でリクエストを BigQuery API に送信します。
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

テーブルおよびビューのラベルの作成と更新

テーブルまたはビューを作成するときにラベルを追加するには、コマンドライン ツールの 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 メソッドの方が適切です。

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

このサンプルは、Google Auth Library for Python を使用して、Requests セッションと互換性のある AuthorizedSession でリクエストを BigQuery API に送信します。
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

ラベルの削除

データセット、テーブル、またはビューのラベルを削除するには、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 メソッドを呼び出してデータセット リソースlabels プロパティを更新します。その際、ラベルのキー値を null に設定します。

特定のデータセットのラベルをすべて削除するには、datasets.patch メソッドを呼び出して labels プロパティを削除します。

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

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

テーブルまたはビューのラベルを削除するには、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 メソッドを呼び出してテーブル リソースlabels プロパティを更新します。その際、ラベルのキー値を null に設定します。

特定のテーブルまたはビューのラベルをすべて削除するには、tables.patch メソッドを呼び出して labels プロパティを削除します。

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

タグの作成

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

タグは、リソースにラベルを付けたいものの、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.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 メソッドを使用してビューとテーブルの両方のラベル情報を表示できます。

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

ラベルに基づいてデータセットをフィルタリングするには、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 プロパティを使用してフィルタ指定を指定します。

次のステップ

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

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

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