自 2026 年 4 月 10 日起，Dataplex Universal Catalog 將更名為 Knowledge Catalog。API、用戶端程式庫、CLI 和 IAM 名稱維持不變。詳情請參閱「隆重推出 Google Cloud Knowledge Catalog」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

從 dbt Core 匯入中繼資料

對資料工程師、分析工程師和資料管理員而言，集中管理中繼資料是企業資料探索和管理的重要環節。團隊使用 dbt 進行資料轉換時，會產生寶貴的作業、語意和歷程中繼資料，但這些資料通常會保留在 dbt 生態系統中。

如要將這項資訊整合至集中式目錄，您可以將 dbt Core、dbt Cloud 和 MetricFlow 的中繼資料匯入 Knowledge Catalog (舊稱 Dataplex Universal Catalog)。

由於 dbt Core 是轉換引擎，而非 Oracle 或 PostgreSQL 等儲存系統，因此匯入其中繼資料可啟用不同的用途。匯入 Oracle 或 PostgreSQL 中繼資料，回答「我們有哪些原始資料？」；匯入 dbt Core 中繼資料，回答「資料轉換方式為何？是否可靠？對業務有何意義？」

本文說明如何使用 Google Cloud CLI 指令和 dbt 構件檔案匯入中繼資料。

執行 dbt 整合時，您會擷取下列中繼資料：

技術中繼資料：探索重要資源 (來源、種子、模型) 及其技術屬性 (資料欄名稱、資料類型、列數)，發掘企業資料。
業務和語意中繼資料：透過 dbt MetricFlow 支援的業務定義和邏輯 (例如語意模型、指標和已儲存的查詢)，為 BI 工具和 AI 代理提供背景資訊。
作業和資料品質中繼資料：監控管道健康狀態，並透過探索執行中繼資料 (例如時間、成功或失敗狀態、資料更新間隔和測試結果)，排解資料問題。
歷程和關係中繼資料：探索轉換圖 (DAG) 和 dbt 資源之間的依附元件、追蹤及連結實體轉換區塊的實體歷程、聯結鍵和動態聯結，以及父項/子項關係，藉此啟用下游影響分析和根本原因追蹤。
耗用中繼資料：探索曝光中擷取的中繼資料，瞭解下游應用程式如何耗用轉換後的資料，並排解相關問題。這些曝光會對應資料在 dbt 外部的使用方式。

限制

支援 dbt Core v1 (已針對 1.11 和 1.12 版進行驗證)、dbt Core v2 和 dbt Fusion。
gcloud CLI 586.0.0 以上版本支援 dbt 和 BigQuery 整合。如要安裝或更新 CLI，請參閱「安裝 Google Cloud CLI CLI」。
您無法直接連線至 dbt Cloud。如要從 dbt Cloud 工作匯入中繼資料，請先取得該工作的構件。請參閱「從 dbt Cloud 執行作業匯入中繼資料」。
系統會截斷過大或深層巢狀結構的結構定義：單一面向不得超過每個面向的大小上限，因此深層巢狀結構的結構定義可能會遺失尾隨欄位。
--aspects-only 可以新增及重新整理中繼資料，但無法移除。刪除 dbt 資源需要完整執行。
這項整合功能僅支援 Data Lineage API 和圖表中的 BigQuery 資源 dbt 沿襲事件。外部第三方來源的 dbt 項目 (來源、種子、模型) 不會擷取至資料沿襲。
- 如要在 Data Lineage API 中擷取所有 dbt 歷程事件，請使用 OpenLineage dbt 整合功能。接著，將 OpenLineage 與 Knowledge Catalog 整合，從 dbt 匯入並顯示資料歷程。

事前準備

如要從 dbt Core 和 MetricFlow 匯入中繼資料，請先完成下列工作：

授予必要的角色和權限。
啟用 Knowledge Catalog API。
符合 dbt 必要條件。
建立目的地項目群組 (如果還沒有的話)。
瞭解 Cloud Storage 角色。

IAM 角色和權限

如要建立及管理 Knowledge Catalog 連接器工作，您需要 Identity and Access Management (IAM) 角色，授予 Knowledge Catalog 和 Cloud Storage 的權限。

如要取得設定 dbt 連接器所需的權限，請要求管理員授予下列 IAM 角色：

如要建立及管理項目群組和項目連結，您必須是專案的 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin)、Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex 項目群組擁有者 (roles/dataplex.entryGroupOwner)。
如要執行 dbt gcloud 指令和建立中繼資料匯入工作：請遵循最低權限原則，並授予下列角色：
- 專案的 Dataplex 中繼資料工作擁有者 (roles/dataplex.metadataJobOwner)。
- Dataplex 項目群組匯入者 (roles/dataplex.entryGroupImporter) 適用於目標項目群組或專案。如果同時匯入項目連結，請改為在專案中授予「Dataplex 項目群組擁有者」(roles/dataplex.entryGroupOwner) 角色。此外，請在每個包含 dbt 模型寫入 BigQuery 資料表的專案中，授予「Dataplex 項目擁有者」(roles/dataplex.entryOwner) 權限。如果是自訂角色，項目連結權限為 dataplex.entryGroups.useReferenceEntryLink、dataplex.entryGroups.useSchemaJoinEntryLink 和 dataplex.entryLinks.reference。
或者，您也可以在專案中授予「Dataplex Catalog 管理員」(roles/dataplex.catalogAdmin) 角色和「Dataplex 中繼資料工作擁有者」(roles/dataplex.metadataJobOwner) 角色。
如要將轉換後的中繼資料上傳至輸出暫存 bucket (--storage-uri)：暫存 bucket 的「Storage 物件建立者」(roles/storage.objectCreator) 或「Storage 物件管理員」(roles/storage.objectAdmin)。
如要從輸入 Cloud Storage bucket 讀取 dbt 構件 (如果使用 Cloud Storage，則為 --artifacts-path)：輸入構件 bucket 的「Storage 物件檢視者」(roles/storage.objectViewer) 或「Storage 物件管理員」(roles/storage.objectAdmin)。如果您具備 Storage 物件管理員角色，則不需要 Storage 物件檢視者角色。
如要查看 dbt 中繼資料：在專案中，指派 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer) 角色。
如要在 Cloud Logging 中查看記錄，請在專案中啟用「記錄檢視者」(roles/logging.viewer)。

如果您具備在專案中管理 IAM 存取權的必要權限，可以執行下列 gcloud 指令，將這些角色授予自己的使用者帳戶：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

如果您使用服務帳戶執行匯入作業 (例如在自動化 CI/CD 管道中)，可以執行下列 gcloud 指令，將這些角色授予服務帳戶：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

此外，您必須在輸出暫存 Cloud Storage bucket (--storage-uri) 中，將「Storage 物件檢視者」() 角色 (roles/storage.objectViewer) 授予 Knowledge Catalog 服務代理 (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)，匯入作業才能讀取暫存的中繼資料檔案：

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
USER_EMAIL：使用者帳戶電子郵件地址。
SERVICE_ACCOUNT_EMAIL：服務帳戶電子郵件地址。
STAGING_BUCKET：輸出暫存 Cloud Storage bucket 的名稱 (--storage-uri)。
PROJECT_NUMBER：您的 Google Cloud 專案編號。

如要進一步瞭解如何授予角色，請參閱「管理存取權」。

啟用 API

啟用 Knowledge Catalog API。

啟用 API

dbt 必要條件

如要匯入整組 dbt 中繼資料，建議您產生所有四個 dbt JSON 構件檔案。只需要 manifest.json，其他屬性則可豐富匯入內容，即使沒有這些屬性，轉換作業也會正常運作：

manifest.json (必要)：核心專案結構和執行圖表。也包含 MetricFlow 語意模型、指標和已儲存的查詢。
catalog.json：資料欄名稱和資料類型。如果沒有 catalog.json，系統會匯入結構定義層面，但資料欄沒有型別。
run_results.json：測試結果和執行中繼資料。
sources.json：來源新鮮度。

在安裝 dbt 的本機終端機、Cloud Shell 或自動化 CI/CD 環境中，前往 dbt 專案根目錄，並針對單一設定檔和目標依序執行下列 dbt 指令，產生完整的 dbt 中繼資料構件 JSON 檔案集：

適用於 dbt Core 2.x 和 dbt Fusion：
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  警告： 請勿在 dbt Core 2.x 或 dbt Fusion 上使用 dbt docs generate。不會寫入 catalog.json，且會覆寫 run_results.json，但不會有任何測試結果。dbt build --write-catalog 也不會編寫目錄，因此請使用獨立的 dbt parse --write-catalog 步驟。
適用於 dbt Core 1.x (dbt parse 不會寫入目錄)：
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  警告： 如果沒有 --no-compile，dbt docs generate 會為每個節點以 success 狀態覆寫 run_results.json。dbt build的測試結果會遺失，且目錄會將每項資料品質測試回報為通過。

瞭解 Cloud Storage 角色

匯入 dbt 中繼資料時，會用到兩個不同的 Cloud Storage 位置，用途各異，不應混淆：

輸入 (dbt 來源構件)：產生 dbt JSON 檔案的位置。可以是機器或 CI 執行器上的本機目錄路徑 (例如 ./target/ 或 .)，也可以是輸入 Cloud Storage bucket URI 前置字串 (例如 gs://my-dbt-artifacts-bucket/target/)。您可以使用 --artifacts-path 旗標提供這個路徑。gcloud 指令會在準備工作時讀取這些輸入檔案。如果使用 Cloud Storage，執行 gcloud 指令的呼叫端需要讀取存取權 (roles/storage.objectViewer 或 roles/storage.objectAdmin)。Knowledge Catalog 服務代理不需要存取輸入構件 bucket。
輸出內容 (Knowledge Catalog 匯入暫存 bucket)：Cloud Storage bucket URI 前置字元 (例如 gs://my-staging-bucket/dbt-imports/)，gcloud 指令會將轉換後的中繼資料匯入檔案 (dbt_metadata.jsonl) 上傳至該位置，Knowledge Catalog 匯入工作也會在擷取期間從該位置讀取資料。您可以使用 --storage-uri 旗標提供這個 URI。執行 gcloud 指令的呼叫端需要寫入權限 (roles/storage.objectCreator 或 roles/storage.objectAdmin) 才能上傳檔案，而 Knowledge Catalog 服務代理程式需要讀取權限 (roles/storage.objectViewer) 才能匯入檔案。

從 dbt Cloud 執行作業匯入中繼資料

Knowledge Catalog 不會直接連線至 dbt Cloud。由於 dbt Cloud 工作產生的構件檔案與 dbt Core 相同，因此您可以將這些構件檔案擷取至本機目錄或輸入 Cloud Storage bucket，然後執行 gcloud 指令，從 dbt Cloud 匯入中繼資料。

擷取構件前，請先設定 dbt Cloud 工作，產生完整的構件集。接著，您可以使用下列其中一種方法，從 dbt Cloud 工作執行中擷取構件檔案：

從 dbt Cloud 控制台下載構件：從 dbt Cloud 使用者介面的工作執行詳細資料頁面手動下載構件檔案，用於一次性匯入或初步測試。
使用 dbt 平台 CLI 下載構件：在本機終端機上執行 dbt Cloud 的 dbt 指令，即可在開發期間自動將產生的構件儲存至本機專案目錄。
使用 dbt 管理 API 下載構件：透過 HTTP 以程式輔助方式從已完成的執行作業中擷取構件，用於自動排定的管道。

設定 dbt Cloud 工作

在 dbt Google Cloud 控制台中，設定工作設定以產生完整的中繼資料構件集：

在「執行設定」部分，選取「執行來源新鮮度」。dbt Cloud 會在工作指令前執行 dbt source freshness，以產生 sources.json。
在「指令」部分中，新增 dbt build。
根據發布群組新增指令，產生 catalog.json：
- 適用於 dbt Core 2.x 和 dbt Fusion 發布管道：新增 dbt parse --write-catalog 做為工作指令。
- 適用於 dbt Core 1.x 版本軌：新增 dbt docs generate --no-compile 做為工作指令，而不是選取「在執行時產生文件」選項。「Generate docs on run」核取方塊會執行 dbt docs generate (不含 --no-compile)，這會覆寫 dbt build 的測試結果，如 dbt 先決條件所述。請注意，如果指令步驟失敗，工作也會失敗，但核取方塊步驟不會導致工作失敗。

如果 dbt build 失敗 (例如測試失敗)，dbt Cloud 會略過後續指令，且執行作業不會有 catalog.json。如要一律產生一個，請在 dbt build 前新增目錄指令。目錄接著會說明建構前表格的狀態。

詳情請參閱 dbt 說明文件中的「作業指令」和「發布管道」。

從 dbt Google Cloud 控制台下載構件

如要從 dbtGoogle Cloud 控制台的已完成執行作業手動下載構件，請按照下列步驟操作：

在 dbt Google Cloud 控制台中，開啟已完成的工作執行。
前往「構件」分頁標籤，即可查看產生的構件檔案。
將 manifest.json、catalog.json、run_results.json 和 sources.json 下載至本機目錄。
在本機終端機或 Cloud Shell 中，執行「設定 dbt 連線」一節所述的 gcloud 匯入指令，並將 --artifacts-path 設為包含已下載檔案的目錄。

詳情請參閱 dbt 說明文件中的「執行可見度」。

使用 dbt 平台 CLI 下載構件

dbt 平台 CLI (舊稱 dbt Cloud CLI) 會在本機終端機上執行 dbt Cloud 平台上的 dbt 指令，並自動將產生的構件下載至本機 dbt 專案的 target/ 目錄。

在本機終端機中，前往 dbt 專案根目錄，然後執行dbt 先決條件中列出的三個指令。
執行「設定 dbt 連線」一節所述的 gcloud 匯入指令，並將 --artifacts-path 設為專案根目錄或 target/ 目錄。

CLI 會在開發環境中執行，並使用您的個人資料倉儲憑證，因此產生的中繼資料會反映您的開發結構定義，而不是已排定的工作建立的正式版表格。使用 CLI 進行測試或開發工作流程，並使用部署作業排定正式匯入作業。

詳情請參閱 dbt 說明文件中的「安裝 dbt 平台 CLI」。

使用 dbt 管理 API 下載構件

您可以使用 dbt 管理 API，以程式輔助方式從任何已完成的工作執行中擷取構件。List Run Artifacts 端點會傳回執行作業產生的檔案路徑，而 Retrieve Run Artifact 端點則會從下列網址下載特定構件檔案：

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL取決於代管 dbt Cloud 帳戶的區域。使用 dbt Cloud 服務權杖驗證要求。詳情請參閱 dbt 說明文件中的下列頁面：

從本機終端機、Cloud Shell 或自動化工作流程環境，將 manifest.json、catalog.json、run_results.json 和 sources.json 下載至本機目錄或 Cloud Storage bucket，然後針對該路徑執行「設定 dbt 連線」一文所述的 gcloud 指令。

根據預設，除非您指定 step 查詢參數，否則構件端點會傳回執行作業最後一個步驟的構件。如要按照「設定 dbt Cloud 工作」一文所述設定工作，最後一個步驟是 dbt parse --write-catalog 或 dbt docs generate --no-compile，這只會寫入 catalog.json，並在預設步驟中保留其他三個構件。

擷取執行作業 ID

如要下載特定執行的構件，您需要該執行的 ID。您可以從 dbt Google Cloud 控制台的執行作業網址複製執行作業 ID，也可以從終端機或工作流程指令碼查詢 API，取得作業最近一次成功執行的記錄：

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

在查詢參數中，status=10 會篩選出狀態為 Success 的已完成執行作業。您可以按照排定的時間輪詢這個端點，找出最新的成功執行作業、下載構件，並執行 gcloud 匯入指令。

使用 Webhook 觸發匯入作業

您不必輪詢 API，可以設定 dbt Cloud 網頁掛鉤，在工作執行完畢時觸發自動中繼資料匯入作業。Webhook 會將酬載傳送至您提供的 HTTP 端點：

在 dbt Google Cloud 控制台中，依序前往「Account settings」>「Webhooks」，然後點選「Create webhook」 (或「Create new webhook」)。設定 Webhook 訂閱項目：
- 事件：選取「執行作業完成」 (job.run.completed)，只有在執行作業完成且構件可供下載時，才會觸發這個事件。
- 工作：選取要監控的 dbt Cloud 部署工作。
- 端點：輸入您執行的服務 HTTPS 網址 (例如 Cloud Run 服務或 Cloud Run 函式)。
儲存 dbt Cloud 顯示的 Webhook 密鑰權杖。服務會使用這個密鑰驗證 Authorization 標頭，其中包含要求主體的 HMAC-SHA256 簽章。
在服務中，從 JSON 酬載讀取 data.runId，使用 Administrative API 下載執行階段的構件 (如先前所述)，然後執行 gcloud alpha dataplex dbt metadata-jobs create 指令。

實作 Webhook 處理常式時，請注意下列事項：

dbt Cloud 最多會等待 10 秒來接收回應。由於匯入中繼資料需要幾分鐘，請先傳回 HTTP 回應，然後在背景執行匯入作業 (例如以 Cloud Run 工作或使用 --async 標記)。
job.run.completed 也會在執行失敗時觸發，因此系統仍會匯入測試失敗的執行作業。請勿訂閱 job.run.errored，因為這可能會在執行階段的構件可用之前觸發。

如要進一步瞭解 Webhook 酬載和簽章驗證，請參閱 dbt 說明文件中的「Webhooks for your jobs」。

設定 dbt 連線

如要建立 dbt 連線，請先執行適當的 dbt 指令，生成中繼資料構件。JSON 檔案儲存完畢並可供存取後，匯入程序會執行下列動作：

讀取輸入構件：從輸入位置 (--artifacts-path 中指定的本機目錄或 Cloud Storage URI)，讀取 dbt Core 和 MetricFlow 產生的 JSON 構件。
轉換中繼資料：將內容轉換為 Knowledge Catalog 中繼資料匯入格式 (dbt_metadata.jsonl)。
上傳至暫存位置：將轉換後的中繼資料匯入檔案上傳至 --storage-uri 中指定的輸出暫存 Cloud Storage 位置。
觸發匯入作業：觸發 Knowledge Catalog 中繼資料匯入作業，指示 Knowledge Catalog 服務代理程式從 --storage-uri 讀取並擷取暫存中繼資料，然後匯入 Knowledge Catalog 資源。

控制台

前往 Google Cloud 控制台的「Knowledge Catalog」「Connectors」頁面。

前往「連線器」
按一下「新增連線」。
在「連結器」清單中，選取「dbt Core 和 MetricFlow」資訊卡。

注意： 由於擷取 dbt Core 中繼資料時，需要先將用戶端 dbt 構件 JSON 檔案 (manifest.json、catalog.json、run_results.json、sources.json) 轉換為知識目錄匯入格式，才能擷取資料，因此選取這張資訊卡後，系統會將您導向 CLI 或 API 指令。
如要查看匯入的 dbt 資產，請前往「搜尋」頁面，或查看目的地「項目群組」頁面。

gcloud

如要建立 dbt 中繼資料工作，請完成下列步驟：

確認 dbt 中繼資料構件檔案儲存在本機或輸入 Cloud Storage 值區中。
請確認您已設定輸出暫存 Cloud Storage bucket，並為呼叫端和 Knowledge Catalog 服務代理程式授予適當權限。
從 Cloud Shell、本機終端機或自動化工作流程工具，執行 gcloud 指令：
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
必要旗標
- --storage-uri=STORAGE_URI：(輸出/暫存) Cloud Storage URI 前置字元 (gs://bucket/path/)，轉換後的 JSONL 會上傳至此處，匯入作業也會從這裡讀取資料。呼叫端必須具備寫入存取權 (roles/storage.objectCreator 或 roles/storage.objectAdmin)，知識目錄服務代理必須具備讀取存取權 (roles/storage.objectViewer)。
選用旗標
- --artifacts-path=ARTIFACTS_PATH：(輸入) 來源 dbt 構件的路徑。可以是本機目錄路徑 (例如 . 或 ./target)，也可以是 Cloud Storage URI 前置字串 (例如 gs://my-bucket/dbt-artifacts/)。可以指向 dbt 專案根目錄 (系統會自動偵測 target/ 子目錄)，也可以直接指向包含 manifest.json 的目錄。預設值為 .。如果提供 Cloud Storage URI，呼叫端必須具備輸入 bucket 的讀取權限 (roles/storage.objectViewer 或 roles/storage.objectAdmin)。
- --async：立即返回，不要等待執行中的作業完成。
- --entry-group=ENTRY_GROUP：接收 dbt 項目項目的項目群組簡短 ID。必須已存在於專案和位置 (預設為 dbt-metadata-ingestion)。
- --aspects-only：只更新這個 dbt 執行作業觀察到的中繼資料，並保留其餘項目群組不變。不會建立、刪除或重新設定父項項目，也不會發出項目連結，且 dbt 構件在此執行中缺少的層面會保留先前執行提供的值。適用於例行性重複擷取作業。請參閱「重新執行擷取作業」。
- --include-entry-links：為 dbt 關係發出項目連結。這項設定預設為啟用。如要停用這項功能，請使用 --no-include-entry-links。這個指令會發出下列項目連結類型：
  - reference：一個資源依附、說明或使用另一個資源。這包括節點之間的 dbt 依附元件、測試和測試的資源、語意模型或指標和建構的資源、節點和呼叫的專案巨集，以及節點和具體化的 BigQuery 資料表。
  - schema-join：由 dbt relationships 測試宣告的可聯結資料欄。
- --skip-bigquery-link：略過 reference 連結 (dbt 節點 → 實體 BigQuery 資料表)。根據預設，系統會為每個具體化的 dbt 節點 (模型、種子、快照) 發出連結，這些節點的 BigQuery 資料集位於匯入位置 (--location)。dbt 來源不會收到其 BigQuery 資料表的連結。reference reference 項目連結只能參照同一區域的 @bigquery 項目，因此系統會自動略過其他區域的資料集。如要判斷每個資料集的區域，指令會呼叫 BigQuery API，因此呼叫端需要具備這些資料集的 bigquery.datasets.get 權限；否則指令無法略過其他區域的資料集，且與這些資料集的連結無法解析。如果 BigQuery 資料表未編目至 Knowledge Catalog，請使用 --skip-bigquery-link。
- --validate-only：建構及上傳 JSON，並驗證中繼資料作業，但實際上不會擷取資料。
確認您收到「已建立」狀態。

REST

如要使用 REST API 匯入 dbt 中繼資料，請按照下列步驟操作：

產生 dbt 構件，並轉換為 Knowledge Catalog JSON 匯入檔案 (dbt_metadata.jsonl)。
將轉換後的檔案上傳至 Cloud Storage 暫存 bucket (gs://BUCKET_NAME/PATH/)。

呼叫 projects.locations.metadataJobs.create 方法：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

更改下列內容：

PROJECT_ID：登錄群組所在的 Google Cloud 專案 ID。
LOCATION：進入群組的區域 (例如 us-central1)。
JOB_ID：中繼資料工作的專屬 ID。
BUCKET_NAME/PATH：上傳 dbt_metadata.jsonl 的 Cloud Storage URI 前置字元。
ENTRY_GROUP：目的地項目群組的簡短 ID。

如要追蹤匯入工作的狀態，請使用 projects.locations.metadataJobs.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

建立工作後，Knowledge Catalog 會根據設定排定首次執行時間，您也可以手動啟動工作。

重新執行擷取作業

首次匯入後，大多數執行作業只需要重新整理現有資源的中繼資料。請使用 --aspects-only 執行這些作業。這項功能只會更新 dbt 執行作業觀察到的內容，並保留項目群組中的其他所有內容，因此可放心在任何排程中重複執行，且不限於一個工作。

執行完整擷取作業 (省略 --aspects-only)，前提是項目集有所變更：

首次擷取至項目群組。
新增、重新命名或刪除 dbt 資源。
項目顯示名稱、說明或標籤變更。
項目階層有所變更。
dbt 依附元件變更，例如新增或移除 ref()、source()、測試或巨集呼叫。--aspects-only不會建立或更新項目連結。
變更 --include-entry-links 或 --skip-bigquery-link。

完整執行會從磁碟上的構件重新編寫每個項目的必要層面，因此請從管線可產生的最完整構件集運作執行。

執行 --aspects-only，定期重新整理：

管道執行的任何 dbt 指令 (dbt build、dbt test、dbt source freshness 或 --select 縮小範圍的重建)。
新增、移除、重新輸入或重新描述資料欄。
模型 SQL 已變更，且執行作業也寫入 catalog.json。
新的測試結果或來源新鮮度。

--aspects-only 可以新增及重新整理中繼資料，但無法移除。

搜尋及查看 dbt 中繼資料

控制台

前往 Google Cloud 控制台的「Knowledge Catalog」「Search」(搜尋) 頁面。

前往「搜尋」
在「Filters」(篩選器) 面板中，篩選 dbt 資產：
- 在「系統」部分，選取「匯入的內容」。
- 在隨即顯示的「受管理連接器」子區段中，選取「dbt」。
在搜尋欄位中，使用關鍵字或自然語言搜尋輸入查詢。舉例來說，如要使用關鍵字搜尋查看所有 dbt 資產，請輸入 system=DBT 或 system=DBT AND type=dbt-model。
在搜尋結果中，按一下任一 dbt 資產，開啟該項目的詳細資料頁面，即可查看其結構、歷程和技術層面。

gcloud

如要在專案中搜尋 dbt 項目，請使用 gcloud dataplex entries search 指令：

gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

如要依特定 dbt 項目類型 (例如模型或來源) 篩選：

gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

如要查看特定 dbt 項目完整詳細資料和各個方面，請使用 gcloud dataplex entries lookup 指令：
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
更改下列內容：
- PROJECT_ID：您的 Google Cloud 專案 ID。
- LOCATION：項目群組的位置 (例如 us-central1)。
- ENTRY_GROUP：目的地項目群組的簡短 ID (例如 dbt-metadata-ingestion)。
- ENTRY_ID：dbt 項目的簡短 ID 或相對資源名稱。

REST

如要搜尋 dbt 項目，請呼叫 projects.locations:searchEntries 方法：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

如要依特定 dbt 資源類型篩選：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

如要擷取特定項目的完整中繼資料詳細資料和層面，請呼叫 projects.locations.entryGroups.entries.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

如要擷取特定 dbt 資源的 LLM 內容，請使用 projects.locations:lookupContext API：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：項目群組的位置 (例如 us-central1)。
ENTRY_GROUP：目的地項目群組的簡短 ID (例如 dbt-metadata-ingestion)。
ENTRY_ID：dbt 項目的簡短 ID 或相對資源名稱。

如要列出 dbt 項目連結，請呼叫 projects.locations:lookupEntryLinks 方法。舉例來說，如要擷取 dbt 模型具體化的 BigQuery 資料表，請執行下列操作：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME 是 dbt 項目完整的資源名稱。結果會分頁顯示，每頁最多 10 個連結。

如要進一步瞭解如何搜尋資源，請參閱「在 Knowledge Catalog 中搜尋資源」。如要進一步瞭解查詢運算式和篩選器，請參閱「Knowledge Catalog 的搜尋語法」。

後續步驟

瞭解如何管理連結器工作。

從 dbt Core 匯入中繼資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

限制

事前準備

IAM 角色和權限

啟用 API

dbt 必要條件

瞭解 Cloud Storage 角色

從 dbt Cloud 執行作業匯入中繼資料

設定 dbt Cloud 工作

從 dbt Google Cloud 控制台下載構件

使用 dbt 平台 CLI 下載構件

使用 dbt 管理 API 下載構件

擷取執行作業 ID

使用 Webhook 觸發匯入作業

設定 dbt 連線

控制台

gcloud

必要旗標

選用旗標

REST

重新執行擷取作業

搜尋及查看 dbt 中繼資料

控制台

gcloud

REST

後續步驟

從 dbt Core 匯入中繼資料