開始使用 Knowledge Catalog Universal Catalog 的基礎治理功能

1. 簡介

身為開發人員和資料工程師，我們經常會繼承大量資料，這些資料看起來更像是資料沼澤。我們不斷遇到相同的摩擦點：「這個『amt』欄位的實際定義是什麼？」「如果這個資料集發生問題，誰要負責？」或「我們可以在個人化推薦引擎中使用這個資料表嗎？」

傳統上，資料目錄是填入自由形式標記的被動清單，很快就會變得不一致且過時。這類目錄不會強制執行結構，因此幾乎不可能進行程式輔助式管理。

為求實用，我們將在本實驗室中逐步完成一個情境：針對原始零售銷售資料建立健全的管理機制，讓財務部門能夠信任這些資料，並用於正式報表。您會將這項資料從模糊不清的「沼澤」狀態，移至受控產品。

Knowledge Catalog Universal Catalog 提供主動式結構化中繼資料管理架構，可解決這個問題。您可以將結構化、以結構定義為準的中繼資料 (切面) 和已接受的業務定義 (詞彙表)，直接附加至資料資產 (項目)。

如要編寫 Python 指令碼或 Terraform 模組，大規模自動執行這項作業，您必須先瞭解基礎物件模型。

在本程式碼研究室中，我們將在 Google Cloud 控制台中手動執行控管步驟，並明確連結項目、層面類型、層面和術語表，讓您清楚瞭解如何讓資料可供探索、易於理解且值得信賴。

必要條件

• 具備擁有者或編輯者權限的 Google Cloud 專案。
• Google Cloud 控制台。
• 在 Cloud Shell 中使用 gcloud 和 bq CLI 的基本技能。

課程內容

• Knowledge Catalog 項目、切面類型和切面的重要區別。
• 如何建立商務詞彙表，解決術語含糊不清的問題。
• 如何設計切面類型，以強制執行技術中繼資料的嚴格結構定義 (超越「標記」)。
• 如何將業務術語表中的術語連結至特定 BigQuery 資料欄。
• 如何將結構化 Aspect 附加至資料資產，以及驗證輸入內容。
• 如何根據這項新的結構化中繼資料執行精確的搜尋查詢。

軟硬體需求

• Google Cloud 帳戶和 Google Cloud 專案
• 網路瀏覽器，例如 Chrome

重要概念

• 項目：目錄中資料資產的標準抽象表示法。可視為「指標」或「名詞」。建立 BigQuery 資料表時，Knowledge Catalog 會自動為該資料表建立項目。我們不會直接控管資料表，而是控管其項目。
• 業務詞彙表：集中式版本控管字典，收錄貴機構的業務用語。這是單一事實來源。可避免「銷售部門與財務部門對 GMV 的定義不同」的問題。
• 切面類型：特定類別中繼資料的結構定義或範本。切面類型會定義欄位、資料類型 (字串、列舉、日期時間等) 和限制 (必要/選用)，是確保中繼資料一致性的合約。
• 層面：附加至項目的特定中繼資料，遵循層面類型定義的結構。其中包含符合層面類型結構定義的實際資料。

2. 設定和需求條件

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台中，點選右上角工具列的 Cloud Shell 圖示：

佈建並連線至環境的作業，應該很快就能完成。完成後，您應該會看到如下的內容：

這部虛擬機器搭載各種您需要的開發工具，而且主目錄提供 5 GB 的永久儲存空間。此外，這部虛擬機器可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有工作，不需安裝任何軟體。

啟用必要的 API 並設定環境

執行下列指令，設定專案 ID、定義區域，並啟用必要的服務 API。

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export LOCATION="us-central1"

gcloud services enable dataplex.googleapis.com \
                       bigquery.googleapis.com \
                       datacatalog.googleapis.com

建立 BigQuery 資料集並準備範例資料

我們需要具體的資料資產來管理。我們會建立 BigQuery 資料集，並載入代表交易的小型 CSV 範例。Knowledge Catalog 會自動探索這個資料表，並為其建立項目。

# Create the BigQuery Dataset in the us-central1 region
bq --location=$LOCATION mk --dataset \
    --description "Retail data for governance codelab" \
    $PROJECT_ID:retail_data

# Create a temporary CSV file with the sample data
echo "transaction_id,user_email,gmv,transaction_date
1001,[e-mail],150.50,2025-08-28
1002,[e-mail],75.00,2025-08-28" > /tmp/transactions.csv

# Load the data from the temporary CSV file into BigQuery
bq load \
    --source_format=CSV \
    --autodetect \
    retail_data.transactions \
    /tmp/transactions.csv

# (Optional) Clean up the temporary file
rm /tmp/transactions.csv

執行快速查詢來驗證設定：

bq query --nouse_legacy_sql "SELECT * FROM retail_data.transactions"

3. 透過商務詞彙表建立通用語言

有效的治理措施從明確的定義開始。如果開發人員看到名為「gmv」的資料欄，就不必猜測其中是否包含稅金或退款。業務字彙表可將業務定義與技術實作項目分離，解決這個問題。

1. 在 Google Cloud 控制台中，前往「Knowledge Catalog Universal catalog」(Knowledge Catalog 通用目錄)。
2. 在左側導覽選單中，選取「詞彙表」(位於「管理中繼資料」下方)。

3. 按一下「建立組織詞彙」。
4. 輸入下列詳細資料：
   • Name (名稱)：Retail Business Glossary
   • 位置：us-central1 (或您在設定中定義的位置)。
5. 點選「建立」。

6. 按一下新建立的「零售業業務詞彙表」即可進入。

7. 按一下「建立類別」，然後將類別命名為 Sales Metrics，再按一下「建立」。類別可協助您將相關字詞分組。
8. 選取 Sales Metrics 類別，然後按一下「新增字詞」，將其命名為 Gross Merchandise Value，然後按一下「建立」
9. 按一下「總覽」頁面上的「+ 新增」按鈕，然後填寫下列詳細資料：
   • 總覽： The total value of merchandise sold over a given period of time before the deduction of any fees or expenses. This is a key indicator of e-commerce business growth.
10. 按一下 [儲存]。

您現在已建立明確的定義，可連結至整個機構的技術資產。

4. 使用切面類型定義結構化技術中繼資料

簡單的「鍵:值」標記不足以滿足工程嚴謹度。如果您需要追蹤「資料擁有者」，您不會希望一個資料表標記為 owner:bob，另一個標記為 contact:[e-mail]。您需要結構定義來強制規定擁有者為必要條件，且必須採用有效的電子郵件格式。

我們會使用「切面類型」定義這份合約。

1. 在 Knowledge Catalog 左側導覽面板中，選取「目錄」下方的「切面類型和標記範本」。

⚠️ 警告：淘汰通知

您會發現目前的使用者介面會一併參照「標記範本」和切面類型。標記範本是舊版 Data Catalog 服務的一部分，這項服務已淘汰，並預計於 2026 年 2 月停止運作。

2. 選取「自訂」分頁標籤，然後點選「建立切面類型」。

3. 輸入下列詳細資料：
   • 顯示名稱：Data Asset Governance
   • 位置：us-central1
4. 在「範本」部分，我們將定義 Aspect 的結構定義。點選「新增欄位」，建立下列三個欄位：
   • 欄位 1：
     • 顯示名稱：Data Steward
     • 「類型」：Text
     • 文字類型：Plain text
     • 基數：必填 (勾選方塊)
   • 欄位 2 (再次按一下「新增欄位」)：
     • 顯示名稱：Data Sensitivity
     • 「類型」：Enum
     • 值：新增 Public、Internal 和 Confidential
     • 基數：選用
   • 欄位 3 (再次點選「新增欄位」)：
     • 顯示名稱：Last Review Date
     • 「類型」：Date and time
     • 基數：選用
5. 按一下 [儲存]。

您剛建立可重複使用的中繼資料合約。目前沒有任何項目使用，但結構存在。

5. 將控管措施連結至資產

現在我們將整合所有內容。我們有 BigQuery 資料表 (retail_data.transactions)、業務定義 (Gross Merchandise Value) 和管理架構 (Data Asset Governance)。

我們會擴充 BigQuery 資料表的 Knowledge Catalog 項目。

在結構定義中加入業務情境資訊 (資料欄層級)

將「gmv」欄位連結至字彙表，讓使用者瞭解實際意義。

1. 在 Knowledge Catalog 左側導覽中，按一下「搜尋」。
2. 如果「Knowledge Catalog 通用目錄」分頁未啟用，請點選右上方的「Knowledge Catalog 通用目錄」分頁。

3. 搜尋 retail_data.transactions。點選 BigQuery 資料表的搜尋結果。

4. 在「項目詳細資料」中，按一下「結構定義」分頁標籤。
5. 勾選「gmv」欄列的核取方塊，然後按一下「新增商家字詞」。
6. 選取 Gross Merchandise Value 字詞。

「gmv」欄不再只是「FLOAT」，現在已連結至 Gross Merchandise Value 的公司定義。

使用結構化技術中繼資料 (表格層級) 豐富項目內容

接著，我們會將 Data Asset Governance Aspect 附加至表格，以定義擁有權和機密程度。

1. 停留在「項目」retail_data.transactions頁面。
2. 按一下「新增標記或切面」分頁，然後從下拉式選單中選取 Data Asset Governance 類型。

3. 表單現在會顯示在切面類型結構定義中定義的欄位。請填寫這些欄位，如下所示：
   • 資料管理員： [e-mail]
   • 資料敏感程度：選取 Internal。
   • 上次審查日期：選取今天的日期。
4. 按一下 [儲存]。

您已成功將結構化面向附加至項目。與簡單標記不同，系統會根據您建立的結構定義驗證這項資料。

6. 統一探索與驗證

我們並非只是為了填寫表單而完成這項工作，而是為了讓資料更容易發掘且值得信賴。讓我們看看這項中繼資料如何改變搜尋和探索的開發人員體驗。

返回 Knowledge Catalog Universal Catalog 的主要「Search」(搜尋) 頁面。

⚠️ 警告：Knowledge Catalog 通用目錄提供兩種不同的搜尋體驗，語法也不同：自然語言 (AI 輔助) 和關鍵字 (結構化/完全相符)。在本程式碼研究室中，我們使用關鍵字搜尋。

假設您是平台工程師，負責強制執行控管措施。您需要找出受特定長寬比類型控管的所有標示為「內部」的素材資源。您需要根據架構使用精確的述詞。

您可以透過兩種方式驗證這項資訊：使用精確的查詢語法 (自動化作業的必要條件)，或使用互動式 UI 篩選器。

方法 1：透過結構化查詢驗證

1. 在搜尋列 (位於「關鍵字」搜尋模式中) 輸入下列結構化查詢。

aspect:data-asset-governance.data-sensitivity=Internal

2. 您應該會看到 retail_data.transactions 資料表。

方法 2：透過 UI 篩選條件構面驗證

1. 清除搜尋列即可重設檢視畫面
2. 查看畫面左側的「依屬性篩選」面板。
3. 向下捲動並展開「資料資產管理」部分 (這代表您建立的切面類型)
4. 在「資料敏感度」下方，勾選 Internal 方塊。
5. 搜尋結果會更新，顯示 retail_data.transactions 表格。

無論是使用輸入的查詢或 UI 篩選器，底層機制都相同。

這說明瞭 Knowledge Catalog 與簡單 Wiki 的根本差異：中繼資料是可查詢的結構。現在，您可以根據這個可預測的結構，建立自動稽核 (例如「找出所有 last_review_date 大於 1 年前的資料表」)。

7. 清理環境

如要避免產生持續性費用，請刪除本程式碼研究室中建立的資源。

刪除 BigQuery 資料集

這項指令無法復原，且會使用 -f (強制) 標記移除資料集和所有資料表，無需確認。

⚠️ 警告：為避免資料遺失，強烈建議您手動輸入下列指令，而非複製及貼上，確保資料集名稱正確無誤。

# Re-run these exports if your Cloud Shell session timed out
export PROJECT_ID=$(gcloud config get-value project)

# Manually type this command to confirm you are deleting the correct dataset
bq rm -r -f --dataset $PROJECT_ID:retail_data

刪除 Knowledge Catalog 構件

1. 依序前往「Knowledge Catalog Universal catalog UI」>「Manage metadata」>「Catalogue」。
2. 在「Aspect types & tag templates」(切面類型和標記範本) 中，選取並刪除 data_asset_governance 切面類型。
3. 依序前往「管理中繼資料」>「詞彙表」，選取 Retail Business Glossary，然後刪除。請務必先刪除字詞 Gross Merchandise Value，再刪除詞彙表。

8. 恭喜！

您已不再使用簡單的資料標記，而是在 Knowledge Catalog 中建立基礎的結構化管理模型。

您學到：

• 詞彙表可解決業務上的模糊不清之處。
• 切面類型提供技術中繼資料的結構定義合約。
• Aspect 會將該結構定義套用至實際的資料項目。
• Knowledge Catalog 搜尋功能會運用這些結構化中繼資料，精確找出所需內容。

後續步驟

• 以程式碼形式進行管理：使用 Google Cloud Terraform 提供者，在版本管控中定義 Aspect 類型和詞彙表，確保開發/測試/正式環境的結構定義一致。
• 自動標記：編寫 Cloud Function 或 Cloud Build 步驟，在建立新資料集時觸發，自動附加「資料資產管理」Aspect 並使用預設值 (例如 sensitivity=Internal, steward=TBD)，標記以供審查。