Knowledge Catalog 搜尋語法

在 Knowledge Catalog 中，您可以透過搜尋查詢，使用語意和關鍵字比對功能，在目錄中尋找特定資料資產。結合自然語言、中繼資料篩選器和邏輯運算子，即可找出相關項目，進而探索、管理及瞭解貴組織的資料。

Knowledge Catalog 也支援僅限關鍵字的搜尋模式，以提供回溯相容性。如要進一步瞭解這個模式、篩選器和使用方式，請參閱「僅限關鍵字搜尋」。

查詢語法總覽

您可以使用下列元件建構 Knowledge Catalog 搜尋查詢：

  • 簡易搜尋：使用單一搜尋字詞尋找資料資產。
  • 任意文字搜尋：使用自然語言詞組或關鍵字尋找資料資產。
  • 具有限定詞的述詞：使用特定中繼資料欄位 (例如名稱、位置、系統或類型) 縮小搜尋範圍。
  • 切面搜尋：根據附加的業務和技術中繼資料搜尋項目。
  • 邏輯運算子：使用 AND、OR 或 NOT 運算子結合多個搜尋條件，建立複雜的查詢。

具有限定詞的述詞

使用具有限定詞的述詞，明確指示搜尋功能評估特定中繼資料欄位 (例如資產名稱、類型或系統)，縮小搜尋結果範圍。

您可以在述詞前面加上鍵，將比對範圍限制在特定中繼資料，藉此限定述詞：

  • 等號 (=)：將搜尋範圍限制為完全比對。
  • 在鍵後方加上冒號 (:)，將述詞與搜尋結果中值的子字串或權杖進行比對。

斷詞會將文字串流分割成一系列詞元，每個詞元通常對應一個字詞。

例如：

  • name:foo 會選取名稱包含 foo 子字串的資源，例如 foo1 和 barfoo。
  • description:foo 會選取說明中含有 foo 權杖的資源，例如 bar 和 foo。
  • location=foo 會比對指定位置中的資源，並以 foo 做為位置名稱。

支援的限定詞

Knowledge Catalog 搜尋支援下列限定詞：

限定詞 說明
name:x 比對資源 ID 或資源顯示名稱中是否含有 x 子字串。
displayname:x 比對資源顯示名稱中是否含有 x 子字串。
column:x 比對資源結構定義中，與 x 相符的資料欄名稱 (或巢狀資料欄名稱) 子字串。
description:x 比對資源說明中的 x 符記。例如：
  • description:"products" 會顯示說明中含有 products 符記的所有資源。例如「商品目錄中的產品清單」。
  • description:"prod" 不會顯示說明中含有 products 符記的資源。而是顯示說明中含有 prod 符記的所有資源。例如「prod environment」。
labels:bar 比對含有標籤 (具有特定值) 且標籤鍵含有 bar 子字串的資源。
labels=bar 比對具有標籤 (含有某個值) 且標籤鍵等於 bar (字串) 的資源。
labels.bar:x 比對 x 是否為標籤值中的子字串，該標籤具有附加至資源的鍵 bar。
labels.foo=bar 比對鍵等於 foo 且鍵值等於 bar 的資源。
type=TYPE 比對特定項目類型或其類型別名的資源。必須使用 = 限定詞。
projectid:bar 比對 Google Cloud 專案中 ID 包含bar子字串的資源。
parent:x 比對 x 是否為資源階層路徑的子字串。
system=SYSTEM 比對指定系統中的資源。必須使用 = 限定詞。
location=LOCATION

比對指定位置中名稱完全相符的資源。必須使用 = 限定詞。 例如，location=us-central1 會比對託管於愛荷華州的資產。

BigQuery Omni 資產支援這項限定詞，只要使用 BigQuery Omni 位置名稱即可。例如，location=aws-us-east-1 會比對維吉尼亞州北部的 BigQuery Omni 資產。
createtime

尋找在指定日期、時間戳記或相對時間 (以天為單位) 內、之前或之後建立的資源。如要瞭解支援的格式和運算子，請參閱「時間篩選器」。
updatetime

尋找在指定日期、時間戳記或相對時間 (以天為單位) 內、之前或之後更新的資源。如要瞭解支援的格式和運算子，請參閱「時間篩選器」。

完全比對限定詞

述詞鍵 type、system、location 和 aspect 搜尋 (不含 has) 僅支援完全比對 (=) 限定詞，不支援子字串限定詞 (:)。

請使用下列完全比對語法：

述詞索引鍵 修正語法 語法錯誤
type type=table (或 type=view、type=dataset) type:table或type:tab
system system=bigquery (或 system=spanner) system:bigquery或system:big
location location=us-central1 (或 location=europe-west1) location:us-central1或location:us

子字串限定詞

name、displayname、column、projectid 和 parent 等述詞支援使用冒號 (:) 限定詞進行子字串比對：

  • name:transactions 會比對 ID 或顯示名稱包含 transactions 的資源。例如 daily_transactions_raw 和 transactions_v2。
  • column:customer_id 會比對資料欄名稱含有 customer_id 的資源。
  • projectid:prod 會比對 ID 包含 prod 的專案資源。例如：finance-prod-2026。

時間篩選器

您可以依建立時間 (createtime) 或上次更新時間 (updatetime) 篩選資源。

支援的運算子和格式

  • 支援的運算子：:、=、<、>、<=、>=、=>、=<
  • 相對天數 (-Nd)：依過去的相對天數篩選 (例如 -30d、-7d、-1d)。
  • 日曆日期 (YYYY-MM-DD 或 YYYY/MM/DD)：依格林威治標準時間/世界標準時間的特定日期篩選。
  • 完整時間戳記 (YYYY-MM-DDTHH:MM:SS 或 YYYY-MM-DDTHH:MM:SSZ)：依格林威治標準時間/世界標準時間的精確時間戳記篩選。系統也支援部分時間戳記，例如 YYYY-MM-DDTHH:MM 或 YYYY-MM-DDTHH。

時間篩選器語法

下表說明時間篩選器語法：

格式類別 有效語法 語法無效 說明
相對時間單位
  • createtime>-30d (過去 30 天)
  • createtime<=-7d (7 天前或更早)
  • updatetime=-1d (前一天)
  • updatetime>=-90d
  • createtime>-24h
  • createtime>-60m
  • createtime>-2w
  • createtime>30d
  • 相對時間僅支援負數天數單位 (-Nd)。
  • 不支援較短的單位 (小時 h、分鐘 m) 和較長的單位 (週 w、月 m)。
  • 正偏移值若開頭沒有減號 (-)，則無效。
日曆日期
  • createtime:2025-01-15
  • createtime>2025-01-01
  • createtime<=2025-06-30
  • createtime:2025/01/15
  • createtime:2025-01
  • createtime:2025
  • createtime:15-01-2025
  • createtime:Jan-15-2025
  • createtime:01/15/2025
  • 日期必須採用 YYYY-MM-DD 或 YYYY/MM/DD 格式。
  • 如果格式的元件順序不符合標準 (例如 DD-MM-YYYY 或 MM/DD/YYYY)，或月份名稱無效，則不適用。
時間戳記和時區
  • createtime:2025-01-15T05:30:00
  • createtime>2025-01-15T05:30:00Z
  • createtime:2025-01-15T05:30
  • createtime:2025-01-15T05:30:00-08:00
  • createtime:2025-01-15T05:30:00 EST
  • createtime:2025-01-15T05:30:00+05:30
  • 所有時間戳記均以 GMT/UTC 為準。
  • 不支援非 GMT 時區偏差 (例如 -08:00 或 +05:30) 和時區縮寫 (例如 EST 或 PST)。
時段範圍
  • createtime>=2025-01-15T09:00:00 createtime<=2025-01-15T17:00:00
  • createtime:09:00:00..17:00:00
  • createtime:09:00-17:00
  • 不支援時間範圍語法。
  • 請改用完整的日期時間字串，分別比較下限和上限。
自然語言日期
  • createtime=-1d
  • createtime>-30d
  • createtime:yesterday
  • createtime:"last week"
  • createtime:today
  • createtime 或 updatetime 限定詞不支援自然語言日期詞組。
  • 請使用相對日期語法 (-1d、-7d) 或明確日期。

標籤篩選器

使用 labels 述詞，依附加的標籤篩選資源。您可以依標籤鍵、標籤值或兩者篩選：

查詢模式 範例 說明
labels=KEY labels=environment 比對具有標籤且鍵為 environment 的資源，不論其值為何。
labels:KEY_SUBSTRING labels:tier 比對標籤鍵含有 tier 子字串 (例如 service_tier 或 storage_tier) 的資源。
labels.KEY=VALUE labels.env=prod 比對標籤鍵為 env 且值完全符合 prod 的資源。
labels.KEY:VALUE_SUBSTRING labels.owner:analytics 比對標籤鍵為 owner 且值包含 analytics 做為子字串 (例如 analytics-team 或 data-analytics) 的資源。
多個標籤 (AND) labels.env=prod labels.data_tier=tier1 比對同時附加 env=prod 和 data_tier=tier1 標籤的資源。
與系統和類型結合 system=bigquery type=table labels.env=prod labels.confidentiality=high 比對標有 env=prod 和 confidentiality=high 的 BigQuery 資料表。

您可以使用查詢語法，根據附加的切面搜尋項目。

子字串比對會嘗試比對有限數量的面向。如果使用路徑片段找不到項目，請使用完整路徑縮小搜尋範圍，並提高檢索率。

限定詞 說明
aspect:x
或
has:x		 比對 x，做為附加至項目的切面類型完整路徑的子字串，格式為 projectid.location.ASPECT_TYPE_ID
aspect=x
或
has=x		 比對 x，做為附加至項目的切面類型完整路徑，格式為 projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

搜尋面向欄位值。比對 x，做為附加至項目的面向類型和欄位名稱完整路徑的子字串，格式如下：

  • 系統切面類型的語法：

    • ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME

    舉例來說，下列查詢會比對 bigquery-dataset 剖面中 type 欄位值為 default 的項目：

    • bigquery-dataset.type=default
    • dataplex-types.bigquery-dataset.type=default
    • dataplex-types.global.bigquery-dataset.type=default

  • 自訂切面類型的語法：

    • 如果是在全球區域建立切面： PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
    • 如果切面是在特定區域建立： PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME

    舉例來說，下列查詢會比對 employee-info 剖面中 is-enrolled 欄位值為 true 的項目。

    • example-project.us-central1.employee-info.is-enrolled=true
    • example-project.employee-info.is-enrolled=true

    支援的運算子清單取決於面向中的欄位類型，如下所示：

    • 字串：= (完全比對)
    • 所有數字類型：=、:、<、>、<=、>=、=>、=<
    • Enum：=
    • 日期時間：與數字相同，但要比較的值會視為日期時間，而非數字
    • 布林值：=

只有面向的頂層欄位可供搜尋。

邏輯運算子

查詢可以使用邏輯運算子結合多個述詞。注意：邏輯運算子 AND、OR 和 NOT 區分大小寫，且必須使用大寫字母。

AND 運算子

如果以空格分隔多個搜尋字詞或述詞，系統會隱含邏輯 AND，因此您不必明確寫出。

以下範例說明如何使用 AND 運算子建構查詢。

  • 搜尋 BigQuery 資料表

    system=bigquery type=table

  • 在專案 banking-prod 中搜尋名為 customer_id 的資料欄

    projectid:banking-prod column:customer_id

  • 如有需要，您可以使用明確的 AND 運算子：

    system=bigquery AND type=table AND location=us-central1

OR 運算子

使用 OR 運算子比對多個條件中的任一條件。將 OR 與其他條件合併時，請使用括號 ( ) 將運算式分組並定義優先順序。

以下範例說明如何使用 OR 運算子建構查詢。

  • 搜尋 BigQuery 資料表和檢視表

    system=bigquery (type=table OR type=view)

  • 搜尋多個系統中的資料表

    (system=bigquery OR system=spanner) type=table

  • 搜尋行銷或財務資料集中的項目

    system=bigquery (parent:marketing_analytics OR parent:finance_analytics)

NOT 運算子

如要否定述詞，請在述詞前方加上大寫 NOT 或 - (連字號)。

以下範例說明如何使用 NOT 運算子建構查詢。

  • 尋找沙箱專案以外的所有資料表

    • 使用 NOT 運算子
    type=table NOT projectid:sandbox-project
    • 使用連字號
    type=table -projectid:sandbox-project

  • 找出名稱不含 test 的所有 BigQuery 資源

    system=bigquery -name:test

縮寫語法

如要使用縮寫語法，請在括號內使用 | (垂直線) 代表 OR 運算子，並使用 , (逗號) 代表 AND 運算子。這種縮寫語法適用於具有限定詞的述詞。

  • 搜尋多個專案 ID

    • 使用 OR 運算子：
    projectid:(finance-prod|sales-prod|analytics-prod)
    • 使用括號：
    projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

  • 搜尋符合多個資料欄名稱的項目 (AND)

    column:(customer_id,transaction_date,amount)

  • 搜尋與多個資料欄名稱 (OR) 任一相符的項目

    column:(customer_id|user_id|client_id)

萬用字元政策

Knowledge Catalog 搜尋語法不支援在查詢字串或述詞中使用萬用字元，例如 * 或 ?。

如果您在查詢中加入星號 (*) 或問號 (?)，系統會將其視為常值字元，而非模式比對萬用字元。

舉例來說，如要搜尋名稱結尾為 _masked 的資料表，請使用下列查詢：

  • 支援：name:_masked：使用子字串比對 : 限定詞，找出名稱包含 _masked 的所有資源，例如 customer_records_masked 或 transactions_masked。
  • 不支援：name:*_masked：* 會視為常值字元，而非模式萬用字元。

括號

搜尋查詢中的括號具有特定技術功能。如果過度使用括號，或將括號套用至自然語言查詢，可能會混淆搜尋剖析器，並降低結果品質。

簡單的自然語言

提出業務問題時，請以純文字格式傳送查詢。請勿用括號括住。例如，輸入：

Find customer orders containing email addresses

縮寫述詞語法

括號與述詞鍵搭配使用時非常有效，能以精簡格式列出多個 OR 和 AND 條件。

  • 使用 OR (|) 將述詞鍵分組

    • 使用 (|) 搜尋位於任何所列專案中的項目

      projectid:(finance-prod|finance-test|analytics-raw)

    • 使用 (OR) 搜尋列出的任何專案中的項目

    projectid:finance-prod OR projectid:finance-test OR projectid:finance-raw

  • 使用 AND (,) 將述詞鍵分組

    • 使用 (,) 搜尋包含所有指定資料欄的項目
    column:(customer_id, order_date, total_amount)
    • 使用 (AND) 搜尋包含所有指定資料欄的項目
    column:customer_id AND column:order_date AND column:total_amount

您可以將自然語言查詢與精簡篩選器結合使用。

舉例來說，如要尋找指定每月活躍使用者的資料表，但將搜尋範圍限制在指定專案，請使用下列查詢：

monthly active users type=table projectid:(data-warehouse|analytical-tier)

使用括號的最佳做法

  • 請勿將整個問題放在括號內，因為語意引擎可能會將括號視為常值字元，導致結果關聯性偏低。

    • 不正確：(Show me datasets about US population by state)
    • 正確：Show me datasets about US population by state

  • 避免在自然語言欄位中，混用複雜的巢狀布林樹狀結構和括號。搜尋功能已針對自然語言意圖進行最佳化。如果查詢過於複雜，包含括號和明確的邏輯區塊，剖析器會無法正確解讀。

    • 不正確：(revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
    • 正確：revenue data system=bigquery projectid:(data-warehouse|analytical-tier)

  • 除非空格是值的一部分，否則請勿任意加入空格。

    • 不正確：column:( email | id )
    • 正確：column:(email|id)。

後續步驟