使用標籤篩選資源

本頁面說明如何使用標籤篩選 BigQuery 資源。

總覽

如要使用標籤篩選資源:

  • 使用 GCP Console 或傳統網頁版 UI 中的搜尋列。
  • 建立用於 CLI、API 或用戶端程式庫的篩選規格。

限制

目前的功能限制:

  • API、CLI 和用戶端程式庫僅支援對資料集進行篩選。
  • 您無法在任何 BigQuery 工具中使用標籤篩選工作。

必要權限

如要使用標籤篩選資源,您必須具備擷取資源中繼資料的權限,其中至少包含:

  • bigquery.datasets.get,用於篩選資料集
  • bigquery.tables.get,用於篩選資料表和檢視表

以下是具有 bigquery.datasets.get 權限的預先定義 Cloud IAM 角色:

  • bigquery.user
  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

以下是具有 bigquery.tables.get 權限的預先定義 Cloud IAM 角色:

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

此外,具備 bigquery.datasets.create 權限的使用者在建立資料集時,會獲得 bigquery.dataOwner 存取權。 bigquery.dataOwner 存取權可讓使用者篩選他們建立的資源。

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

在 UI 中篩選資源

如要使用 GCP Console 或傳統網頁版 UI 產生資源的篩選清單,請進行下列操作:

Console

  1. 在導覽窗格中,展開「Resources」(資源) 區段。

  2. 在搜尋列中,輸入您的 keyvaluekey:value 組合。搜尋結果會包含所有部分相符的結果。

    例如,如只要顯示具有 department:shipping 標籤的資料集,您可以輸入下列內容:

    • key 值:department
    • valueshipping
    • key:value 組合:department:shipping

傳統版 UI

  1. 在導覽窗格中,捲動至 [Filter by ID or label] (依 ID 或標籤篩選) 方塊。這個方塊會顯示在專案清單的正上方。

  2. 在搜尋列中,輸入您的鍵、值或鍵/值組合。鍵/值組合的格式應為 key:value。搜尋結果會包含所有部分相符的結果。

    例如,如只要顯示具有 department:shipping 標籤的資料集,您可以輸入下列內容:

    • key 值:department
    • valueshipping
    • key:value 組合:department:shipping

在 CLI 或 API 中篩選資料集

目前 API、CLI 和用戶端程式庫僅支援對資料集進行篩選。

如要使用 CLI、API 或用戶端程式庫來篩選資料集,請建立並使用篩選規格:

  • 做為 CLI 中 --filter 標記的參數
  • 做為 API datasets.list 方法中 filter 屬性的值

篩選規格的限制

篩選規格有下列限制:

  • 僅支援 AND 邏輯運算子。系統會將以空格分隔的比較結果,視為具有隱性 AND 運算子。
  • 目前唯一符合篩選規格的欄位是 labels.key,其中 key 是標籤名稱。
  • 篩選規格最多可以包含十個運算式。
  • 篩選規格須區分大小寫。
  • 目前 CLI、API 和用戶端程式庫僅支援對資料集進行篩選。

篩選規格範例

篩選規格使用下列語法:

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

其中:

  • fieldlabels.key 表示,其中「key」為標籤鍵。
  • value 是選用的標籤值。

下列範例說明如何產生篩選器運算式。

如要列出具有 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

在 CLI 和 API 中篩選資料集

如要使用 CLI、API 或用戶端程式庫來篩選資料集:

CLI

發出 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

各指令的輸出內容會傳回資料集清單,如下所示:

+-----------+
| datasetId |
+-----------+
| mydataset |
| mydataset2|
+-----------+

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.")

後續步驟

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

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

這個網頁
需要協助嗎?請前往我們的支援網頁