新增及使用標籤

您可以在資料集、資料表和視圖中加入標籤,以協助整理您的 BigQuery 資源。標籤是您可以附加至資源的鍵/值組合。建立 BigQuery 資源時可以選擇是否要加入標籤。

為您的資源加上標籤後,您就可以根據標籤值進行搜尋。例如,您可以使用標籤依照用途、環境和部門等將資料集分組。

本頁面說明如何為 BigQuery 資源加上標籤。

如需管理標籤的相關資訊,請參閱管理標籤

什麼是標籤?

標籤是協助您整理 Google Cloud Platform BigQuery 資源的鍵/值組合。您可以將標籤附加到每一個資源,然後按標籤來篩選資源。標籤的相關資訊會轉送至帳單系統,所以您可以按標籤查看帳單費用明細

標籤的常見用法

以下是一些常見的標籤用途:

  • 團隊或成本中心標籤:依據團隊或成本中心來新增標籤,以區別不同團隊擁有的 BigQuery 資源 (例如 team:researchteam:analytics)。這類型的標籤可用於成本會計或預算編列作業。

  • 元件標籤:例如 component:rediscomponent:frontendcomponent:ingestcomponent:dashboard

  • 環境或階段標籤:例如 environment:productionenvironment:test

  • 狀態標籤:例如 state:activestate:readytodeletestate:archive

標籤需求

套用於資源的標籤必須符合下列需求條件:

  • 每個資源可以有多個標籤,上限為 64 個。
  • 每個標籤必須是鍵/值組合。
  • 鍵的長度下限為 1 個字元,上限為 63 個字元,不能空白。值可以空白,長度上限為 63 個字元。
  • 鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼,且容許使用國際字元。
  • 標籤中,鍵的部分不得重複。但可以多個資源使用相同的鍵。
  • 鍵的開頭必須是小寫字母或國際字元。

加入資料集標籤

使用指令列工具的 bq mk 指令或呼叫 datasets.insert API 方法建立 BigQuery 資料集時,您可在當中加入標籤。如果資料集是透過 GCP 主控台或傳統 BigQuery 網頁版 UI 所建立,目前您無法在這類資料集中加入標籤。

本頁面說明如何在建立資料集後加入標籤。如要深入瞭解如何在建立資料集時加入標籤,請參閱建立資料集

在資料集中加入標籤後,標籤就會列入儲存空間帳單資料中,不過工作相關的帳單資料並不會顯示資料集標籤。

所需權限

如要在現有資料集中加入標籤,您必須具備資料集層級的 OWNER 存取權,或必須獲指派擁有 bigquery.datasets.update 權限的專案層級身分與存取權管理角色。以下是擁有 bigquery.datasets.update 權限的預先定義專案層級身分與存取權管理角色:

此外,因為 bigquery.user 角色擁有 bigquery.datasets.create 權限,所以經指派為 bigquery.user 角色的使用者可以更新自己建立的任何資料集。當接受 bigquery.user 角色指派的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。 OWNER 存取權可讓使用者完全控管該資料集。

如要深入瞭解 BigQuery 中的身分與存取權管理角色和權限,請參閱存取權控制一文。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

在資料集中加入標籤

如何在建立資料集後加入標籤:

主控台

  1. 在 BigQuery 網頁版 UI 中選取資料集。

  2. 在「Dataset Details」(資料集詳細資料) 頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。

    標籤鉛筆圖示

  3. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 按一下 [Add label] (新增標籤)
    • 輸入鍵/值以加入標籤。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
    • 修改現有的鍵/值以更新標籤。
    • 按一下 [Update] (更新),儲存您所做的變更。

傳統版 UI

  1. 在 BigQuery 網頁版 UI 中選取資料集。

  2. 在「Dataset Details」(資料集詳細資料) 頁面的「Labels」(標籤) 右側,按一下 [Edit] (編輯)

    編輯標籤

  3. 在「Edit Labels」(編輯標籤) 對話方塊中:

    • 輸入鍵/值以加入標籤。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一個專案的不同資料集中使用同一個鍵。
    • 修改現有的鍵/值以更新標籤。
    • 按一下 [OK] (確定)

      新標籤

指令列

如要在現有資料集中加入標籤,請發出 bq update 指令並搭配使用 set_label 標記。重複使用該標記即可加入多個標籤。

如果資料集位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集:[PROJECT_ID]:[DATASET]

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET]

其中:

  • [KEY:VALUE] 會對應至您所要加入標籤的鍵/值組合。鍵不得重複。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是您要加入標籤的資料集。

範例:

如要加入標籤以追蹤部門,請輸入 bq update 指令並指定 department 做為標籤鍵。例如,如要將 department:shipping 標籤加入預設專案中的 mydataset,請輸入:

    bq update --set_label department:shipping mydataset

如要在資料集中加入多個標籤,請重複使用 set_label 標記並為每個標籤指定唯一的鍵。例如,如要在預設專案的 mydataset 中加入 department:shipping 標籤和 cost_center:logistics 標籤,請輸入:

    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 指令或呼叫 tables.insert API 方法建立資料表或資料檢視時,您可以在當中加入標籤。

本頁面說明如何在現有資料表或視圖中加入標籤。如要深入瞭解如何在建立資料表或資料檢視時加入標籤,請參閱建立資料表建立資料檢視

資料表或資料檢視建立完成後,您可以使用 GCP 主控台、傳統 BigQuery 網頁版 UI、指令列工具的 bq update 指令,或呼叫 tables.patch API 方法來加入標籤。由於系統會將資料檢視當做資料表資源處理,因此可以使用 tables.patch 方法來修改資料檢視和資料表。

所需權限

如要在現有資料表或資料檢視中加入標籤,您必須具備資料表層級的 OWNER 存取權,或必須獲指派擁有 bigquery.tables.update 權限的專案層級身分與存取權管理角色。以下是擁有 bigquery.tables.update 權限的預先定義專案層級身分與存取權管理角色:

此外,因為 bigquery.user 角色擁有 bigquery.datasets.create 權限,所以經指派為 bigquery.user 角色的使用者可以更新自己建立的任何資料集中的資料表和視圖。當獲得 bigquery.user 角色的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。資料集的 OWNER 存取權可讓使用者完全控管該資料集以及其中的資料表和視圖。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

在資料表或資料檢視中加入標籤

如何在現有資料表或資料檢視中加入標籤:

主控台

  1. 在 BigQuery 網頁版 UI 中,選取資料表或資料檢視。

  2. 按一下 [Details] (詳細資料) 分頁標籤。

    資料表詳細資料

  3. 按一下「Labels」(標籤) 右側的鉛筆圖示

    標籤鉛筆圖示

  4. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 按一下 [Add label] (新增標籤)
    • 輸入鍵/值以加入標籤。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
    • 修改現有的鍵/值以更新標籤。
    • 按一下 [Update] (更新),儲存您所做的變更。

傳統版 UI

選項 1:手動編輯標籤 1. 在 BigQuery 網頁版 UI 中,選取資料表或資料檢視。

  1. 在「Details」(詳細資料) 頁面的「Labels」(標籤) 右側,按一下 [Edit] (編輯)。這個範例會顯示資料表的詳細資料。

    編輯標籤

  2. 在「Edit Labels」(編輯標籤) 對話方塊中:

    • 輸入鍵/值以加入標籤。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個鍵只能在每個資料表或視圖使用一次,但在不同資料集的資料表或視圖中可使用同一個鍵。
    • 按一下 [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")]
     )
     

指令列

如要在現有資料表或視圖中加入標籤,請發出 bq update 指令並搭配使用 set_label 標記。重複使用該標記即可加入多個標籤。

如果資料表或視圖位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集:[PROJECT_ID]:[DATASET]

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE_OR_VIEW]

其中:

  • [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 標記並為每個標籤指定唯一的鍵。例如,如要在預設專案的 mytable 中加入 department:shipping 標籤和 cost_center:logistics 標籤,請輸入:

    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 標記透過指令列在查詢工作中加入標籤。指令列工具僅支援在查詢工作中加入標籤。

如果某個工作是透過 API 提交,您也可以在其中加入標籤,方法是當您呼叫 jobs.insert 時,在工作設定中指定 labels 屬性。API 可用於在任何工作類型中加入標籤。

您無法在待處理、執行中或已完成的工作中加入或更新標籤。

在工作中加入標籤後,標籤就會列入您的帳單資料中。

所需權限

您不需要具備特殊權限就能在工作中加入標籤。不過如果您擁有 jobs.create 權限,就能在提交工作時加入標籤。

如要執行工作,您必須擁有 bigquery.jobs.create 權限。 由 BigQuery 自動建立的工作和您透過程式執行的工作,都需要 bigquery.jobs.create 權限。

如要執行 BigQuery 工作,請將 bigquery.jobs.create 權限授予您的使用者或服務帳戶,或將擁有 bigquery.jobs.create 權限的專案層級預先定義 IAM 角色授予您的帳戶。以下是擁有 bigquery.jobs.create 權限的預先定義 IAM 角色:

如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控管

在工作中加入標籤

如何在工作中加入標籤:

主控台

主控台 BigQuery 網頁版 UI 不支援在工作中加入標籤。

傳統版 UI

傳統 BigQuery 網頁版 UI 不支援在工作中加入標籤。

指令列

如要在查詢工作中加入標籤,請發出 bq query 指令並搭配使用 --label 標記。重複使用該標記即可加入多個標籤。--nouse_legacy_sql 標記表示您的查詢採用標準 SQL 語法。

bq query --label [KEY:VALUE] --nouse_legacy_sql '[QUERY]'

其中:

  • [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 標記以供識別。

如何建立標記:

主控台

  1. 在網頁版 UI 中,選取適當的資源 (資料集、資料表或資料檢視)。

  2. 如果是資料集,「Dataset Details」(資料集詳細資料) 頁面會自動開啟;如果是資料表和資料檢視,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。

    資料表詳細資料

  3. 在「Details」(詳細資料) 頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。

    標籤鉛筆圖示

  4. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 按一下 [Add label] (新增標籤)
    • 輸入新的鍵並將值留空。如要套用其他標記,請按一下 [Add label] (新增標籤),並重複執行相同步驟。
    • 按一下 [Update] (更新),儲存您所做的變更。

傳統版 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. 將您的 DDL 陳述式輸入到「New Query」(新查詢) 文字區域中。

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

指令列

如要在現有資源中加入標記,請將 bq update 指令搭配 set_label 標記使用。請指定鍵並在後面加入冒號,但不要指定值。

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

其中:

  • [KEY] 是您要做為標記的標籤鍵。
  • [RESOURCE_ID] 是有效的資料集、資料表或視圖名稱。如果資源位於預設專案以外的專案中,請使用下列格式加入專案 ID:[PROJECT_ID]:[DATASET]

範例:

輸入下列指令,為 mydataset.mytable 建立 test_data 標記。mydataset 位於預設專案中。

bq update --set_label test_data: mydataset

API

呼叫 datasets.patch 方法或 tables.patch 方法,並在資料集資源資料表資源中加入值設為空字串 ("") 的標籤。用空字串取代現有標籤的值,即可將標籤轉換為標記。

因為系統會將視圖視同資料表資源處理,因此可以使用 tables.patch 方法來修改視圖和資料表。此外,因為 tables.update 方法會取代整個資料集資源,因此建議使用 tables.patch 方法。

查看標籤

如要查看標籤,請使用 BigQuery 網頁版 UI、指令列工具的 bq show 指令,或呼叫 datasets.gettables.get API 方法。由於系統會將資料檢視當做資料表資源處理,因此可以使用 tables.get 方法來取得資料檢視和資料表的標籤資訊。

所需權限

查看標籤所需的權限視您要存取的資源類型而定。

資料集權限

如要取得資料集相關資訊,您必須獲指派資料集層級的 READER 角色,或擁有 bigquery.datasets.get 權限的專案層級身分與存取權管理角色。所有預先定義的專案層級身分與存取權管理角色都具備 bigquery.datasets.get 權限,但 bigquery.jobUser 除外

此外,經指派為 bigquery.user 角色的使用者還擁有 bigquery.datasets.create 權限。因此,只要是自己建立的資料集,經指派為 bigquery.user 角色的使用者就能取得該資料集的相關資訊。當獲得 bigquery.user 角色的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。資料集的 OWNER 存取權可讓使用者完全控管該資料集。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

資料表和視圖的權限

如要取得資料表的相關資訊,您必須取得資料集的 READER 角色,或必須取得擁有 bigquery.tables.get 權限的預先定義專案層級 IAM 角色。如果您獲授予專案層級的 bigquery.tables.get 權限,就能取得專案中所有資料表的相關資訊。所有預先定義的專案層級 IAM 角色都擁有 bigquery.tables.get 權限,但 bigquery.userbigquery.jobUser 除外

此外,經指派為 bigquery.user 角色的使用者還擁有 bigquery.datasets.create 權限。因此,只要是自己建立的資料集,經指派為 bigquery.user 角色的使用者就能取得其中資料表和視圖的相關資訊。當獲得 bigquery.user 角色的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。資料集的 OWNER 存取權可讓使用者完全控管該資料集以及其中的所有資料表和視圖。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

工作權限

為了取得工作資料和中繼資料,您必須具備 bigquery.jobs.get 權限。以下是擁有 bigquery.jobs.get 權限的專案層級預先定義 IAM 角色:

如果您授予帳戶 bigquery.admin 角色,則該使用者可以檢視專案中的所有工作資料,而不管是哪一位使用者提交工作。

以下角色具備自建工作的 bigquery.jobs.get 權限。這些使用者只能檢視自己提交的工作資料。

如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控管

查看資料集、資料表和視圖標籤

如何查看資源的標籤:

主控台

  1. 在 BigQuery 網頁版 UI 中,選取適當的資源 (資料集、資料表或資料檢視)。

  2. 如果是資料集,「Dataset Details」(資料集詳細資料) 頁面會自動開啟;如果是資料表和資料檢視,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。標籤資訊會顯示在資源的資訊資料表中。

    資料表詳細資料

傳統版 UI

  1. 在 BigQuery 網頁版 UI 中,選取適當的資源 (資料集、資料表或資料檢視)。

  2. 如果是資料集,「Dataset Details」(資料集詳細資料) 頁面會自動開啟;如果是資料表和視圖,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。標籤資訊會顯示在資源的資訊資料表中。

指令列

使用 bq show 指令並搭配使用資源 ID。--format 標記可用來控制輸出。如果資源位於預設專案以外的專案中,請使用下列格式加入專案 ID:[PROJECT_ID]:[DATASET]。為了便於閱讀,可以透過將 --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.gettables.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] 指令。

主控台

您無法使用主控台 BigQuery 網頁版 UI 查看工作標籤。

傳統版 UI

您無法使用傳統 BigQuery 網頁版 UI 查看工作標籤。

CLI

如要使用 bq 指令列工具查看查詢工作的標籤,請輸入 bq show -j 指令並加入查詢工作的工作 ID。--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]..."

其中:

  • field 會以 labels.[KEY] 表示, 其中 [KEY] 是標籤鍵。
  • value 是選用的標籤值。

目前,您無法根據篩選規格列出資料表或視圖。

限制

篩選規格具有下列限制:

  • 只有 AND 邏輯運算子受支援。以空格分隔的比較結果,會被視為具有隱性 AND 運算子。
  • 目前唯一符合篩選規格的欄位是「labels.key」,其中「key」是標籤的名稱。
  • 篩選規格最多可以包含十個運算式。
  • 篩選規格須區分大小寫。
  • 您無法使用篩選規格篩選資料表和視圖。
  • 目前,您無法使用 BigQuery 網頁版 UI 篩選資料集。

篩選規格範例

如要列出具有 department:shipping 標籤的資料集,請使用以下篩選規格:

labels.department:shipping

如要列出使用多個標籤的資料集,請以空格分隔鍵/值組合。空格會被視為邏輯 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

產生篩選後的清單

如何產生篩選後的資料集清單:

主控台

您目前無法使用主控台 BigQuery 網頁版 UI 篩選資料集。

傳統版 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

呼叫 datasets.list API 方法,並使用 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.")

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁