自 2026 年 4 月 10 日起，Dataplex Universal Catalog 更名为 Knowledge Catalog。API、客户端库、CLI 和 IAM 名称保持不变。如需了解详情，请参阅 Google Cloud Knowledge Catalog 简介。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

从 dbt Core 导入元数据

本文档介绍了如何使用 gcloud 命令将元数据从 dbt Core 和 MetricFlow 导入 Knowledge Catalog（以前称为 Dataplex Universal Catalog）。

dbt 集成会捕获以下元数据：

技术元数据：包括关键资源（来源、种子、模型）及其技术属性（列名称、数据类型、行数）。
业务和语义元数据：由 dbt MetricFlow 提供支持，包括业务定义和逻辑，例如语义模型、指标和已保存的查询。
运营和数据质量元数据：包括执行元数据，例如时间、成功或失败状态、数据新鲜度、测试和测试结果。
沿袭和关系元数据：包括转换图 (DAG) 和 dbt 资源之间的依赖项、跟踪和关联物理转换区块的物理沿袭、联接键和动态联接，以及父子关系。
使用情况元数据：包括在曝光中捕获的元数据，用于映射 dbt 之外的数据使用情况。

在从 dbt Core 和 MetricFlow 导入元数据之前，请完成以下任务：

授予所需的角色和权限。
启用 Knowledge Catalog API。
满足 dbt 前提条件。
创建目标条目组（如果尚不存在）。
了解 Cloud Storage 角色。

IAM 角色和权限

如需创建和管理知识目录连接器作业，您需要 Identity and Access Management (IAM) 角色，该角色可授予知识目录和 Cloud Storage 的权限。

如需获得配置 dbt 连接器所需的权限，请让您的管理员为您授予以下 IAM 角色：

如需创建和管理条目组，您需要拥有项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin)、Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。
如需执行 dbt gcloud 命令并创建元数据导入作业，请遵循最小权限原则，授予以下角色：
- 针对项目的 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) 角色。
- 针对目标条目组或项目的 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter)。
或者，您可以授予项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色和 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) 角色。
如需将转换后的元数据上传到输出暂存存储桶 (--storage-uri)，请在暂存存储桶上授予以下权限：Storage Object Creator (roles/storage.objectCreator) 或 Storage Object Admin (roles/storage.objectAdmin)。
如需从输入 Cloud Storage 存储桶（如果使用 Cloud Storage，则为 --artifacts-path）读取 dbt 制品，请对输入制品存储桶授予 Storage Object Viewer (roles/storage.objectViewer) 或 Storage Object Admin (roles/storage.objectAdmin) 角色。如果您拥有 Storage Object Admin 角色，则不需要 Storage Object Viewer 角色。
如需查看 dbt 元数据，请为项目授予 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 角色。
如需在 Cloud Logging 中查看日志，请确保您拥有项目的 Logs Viewer (roles/logging.viewer) 角色。

此外，您还必须向知识目录服务代理 (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) 授予输出暂存 Cloud Storage 存储桶 (--storage-uri) 的 Storage Object Viewer (roles/storage.objectViewer) 角色，以便导入作业可以读取暂存的元数据文件。

如需详细了解如何授予角色，请参阅管理访问权限。

启用 API

启用 Knowledge Catalog API。

启用 API

dbt 前提条件

为了导入完整的 dbt 元数据，我们建议生成所有四个 dbt JSON 制品文件。仅 manifest.json 是必需的；其他参数可丰富导入功能，即使没有这些参数，转换功能也能正常运行：

manifest.json（必需）：核心项目结构和执行图。还包含 MetricFlow 语义模型、指标和已保存的查询。
catalog.json：列名称和数据类型。如果不使用 catalog.json，则会导入具有无类型列的架构方面。
run_results.json：测试结果和执行元数据。
sources.json：来源新鲜度。

如需生成完整的 dbt 元数据制品 JSON 文件集，您可以按以下顺序执行 dbt 命令：

dbt source freshness
dbt build
dbt docs generate --no-compile

警告：如果没有 --no-compile，dbt docs generate 会将每个节点的 run_results.json 覆盖为 success 状态。前述 dbt build 中的测试结果会丢失，并且目录会将所有数据质量测试报告为通过。

了解 Cloud Storage 角色

导入 dbt 元数据涉及两个不同的 Cloud Storage 位置，这两个位置具有不同的用途，不应混淆：

输入（dbt 源制品）：生成 dbt JSON 文件所在的位置。此路径可以是您机器或 CI Runner（例如 ./target/ 或 .）上的本地目录路径，也可以是输入 Cloud Storage 存储桶 URI 前缀（例如 gs://my-dbt-artifacts-bucket/target/）。您可以使用 --artifacts-path 标志提供此路径。gcloud 命令会在作业准备期间读取这些输入文件。如果使用 Cloud Storage，执行 gcloud 命令的调用者需要具有读取权限（roles/storage.objectViewer 或 roles/storage.objectAdmin）。Knowledge Catalog 服务代理不需要访问输入制品存储桶。
输出（Knowledge Catalog 导入暂存存储桶）：Cloud Storage 存储桶 URI 前缀（例如 gs://my-staging-bucket/dbt-imports/），gcloud 命令会将转换后的元数据导入文件 (dbt_metadata.jsonl) 上传到该位置，Knowledge Catalog 导入作业会在提取期间从该位置读取文件。您可以使用 --storage-uri 标志提供此 URI。执行 gcloud 命令的调用者需要拥有写入权限（roles/storage.objectCreator 或 roles/storage.objectAdmin）才能上传文件，而知识目录服务代理需要拥有读取权限 (roles/storage.objectViewer) 才能导入文件。

配置 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 连接器页面。

前往“连接器”
点击添加连接。
在连接器列表中，选择 dbt Core 和 MetricFlow 卡片。

注意：由于 dbt Core 元数据提取需要在提取之前将客户端 dbt 制品 JSON 文件（manifest.json、catalog.json、run_results.json、sources.json）转换为 Knowledge Catalog 导入格式，因此选择此卡片会将您定向到 CLI 或 API 说明。
如需查看导入的 dbt 资产，请前往搜索页面或查看目标条目组页面。

gcloud

如需创建 dbt 元数据作业，请完成以下步骤：

确保 dbt 元数据工件文件存储在本地或输入 Cloud Storage 存储桶中。
确保您已配置输出暂存 Cloud Storage 存储桶，并为调用方和 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），并且 Knowledge Catalog 服务代理必须具有读取权限 (roles/storage.objectViewer)。
可选标志
- --artifacts-path=ARTIFACTS_PATH：（输入）源 dbt 制品的路径。可以是本地目录路径（例如 . 或 ./target）或 Cloud Storage URI 前缀（例如 gs://my-bucket/dbt-artifacts/）。可以指向 dbt 项目根目录（系统会自动检测到 target/ 子目录），也可以直接指向包含 manifest.json 的目录。默认值为 .。如果提供了 Cloud Storage URI，调用者必须具有对输入存储桶的读取权限（roles/storage.objectViewer 或 roles/storage.objectAdmin）。
- --async：立即返回，而无需等待正在进行的操作完成。
- --entry-group=ENTRY_GROUP：接收 dbt 条目的条目组的简短 ID。必须已存在于项目和位置中（默认值为 dbt-metadata-ingestion）。
- --aspects-only：仅更新此 dbt 运行所观测到的元数据，并保持条目组的其余部分不变。没有创建、删除或重新设置父级的条目，并且在此运行中缺少 dbt 制品的方面会保留之前运行赋予的值。此设置适用于常规的重复摄入。请参阅重新运行提取。
- --validate-only：构建并上传 JSON，验证元数据作业，但不实际注入数据。
确认您收到了 Created 状态。

REST

如需使用 REST API 导入 dbt 元数据，请执行以下操作：

生成 dbt 制品，并将其转换为 Knowledge Catalog JSON 导入文件 (dbt_metadata.jsonl)。
将转换后的文件上传到您的 Cloud Storage 临时存储桶 (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：元数据作业的唯一标识符。
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 资源。
条目的显示名称、说明或标签发生变化。
条目层次结构发生变化。

完整运行会从磁盘上的制品中重写每个条目的必需方面，因此请从流水线可以生成的最完整的制品集中运行它。

运行 --aspects-only 以进行常规刷新：

在流水线运行的任何 dbt 命令（dbt build、dbt test、dbt source freshness 或 --select 缩窄的重建）之后。
添加、移除、更改类型或重新描述了列。
模型 SQL 已更改，运行也写入了 catalog.json。
新的测试结果或来源新鲜度。

--aspects-only 可以添加和刷新元数据，但无法移除元数据。

搜索和查看 dbt 元数据

控制台

在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索页面。

转到搜索
在过滤条件面板中，按 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 或相对资源名称。

如需详细了解如何搜索资源，请参阅在 Knowledge Catalog 中搜索资源。如需详细了解查询表达式和过滤条件，请参阅 Knowledge Catalog 的搜索语法。

限制

支持最新的 dbt Core v1 版本（已针对版本 1.11 和 1.12 进行验证）。不支持 dbt Core v2 和 dbt Fusion。
不支持使用模型版本控制的 dbt 模型。
不支持 dbt Cloud。
过大或嵌套过深的架构会被截断：单个方面不能超过每个方面的尺寸上限，因此嵌套过深的架构可能会丢失尾随字段。
--aspects-only 可以添加和刷新元数据，但无法移除元数据。删除 dbt 资源需要完整运行。
不支持入口链接。
此集成仅支持 Data Lineage API 和图中的 BigQuery 资源上的 dbt 血缘关系事件。外部第三方来源的 dbt 条目（来源、种子、模型）不会捕获在数据血缘关系中。
- 如需在 Data Lineage API 中注入所有 dbt 沿袭事件，请使用 OpenLineage dbt 集成。然后，将 OpenLineage 与 Knowledge Catalog 集成，以从 dbt 导入和可视化数据沿袭。

后续步骤

了解如何管理连接器作业。

从 dbt Core 导入元数据 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

IAM 角色和权限

启用 API

dbt 前提条件

了解 Cloud Storage 角色

配置 dbt 连接

控制台

gcloud

必需的标志

可选标志

REST

重新运行注入

搜索和查看 dbt 元数据

控制台

gcloud

REST

限制

后续步骤

从 dbt Core 导入元数据