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

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

从 dbt Core 导入元数据

借助 Knowledge Catalog（以前称为 Dataplex Universal Catalog），您可以使用 Google Cloud CLI 和 dbt 工件文件从 dbt Core、dbt Cloud 和 MetricFlow 导入运营、语义和沿袭元数据。您可以将转换元数据集中起来，而不是将其孤立在 dbt 生态系统中，从而帮助数据工程师、分析工程师和数据监管人员发现和治理企业数据。

导入的元数据和应用场景

由于 dbt Core 作为转换引擎（而非 Oracle 或 PostgreSQL 等存储系统）运行，因此导入其元数据可支持不同的用例。您导入 Oracle 或 PostgreSQL 元数据来回答“我们有哪些原始数据？”，并导入 dbt Core 元数据来回答“我们的数据是如何转换的，是否可靠，对业务意味着什么？”

运行 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。
没有与 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 连接器作业，您需要拥有授予 Knowledge Catalog 和 Cloud Storage 权限的 Identity and Access Management (IAM) 角色。

如需获得配置 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 Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。此外，还要针对每个包含 dbt 模型写入到的 BigQuery 表的项目授予 Dataplex Entry Owner (roles/dataplex.entryOwner) 角色。对于自定义角色，条目链接权限为 dataplex.entryGroups.useReferenceEntryLink、dataplex.entryGroups.useSchemaJoinEntryLink 和 dataplex.entryLinks.reference。
或者，您也可以在项目中授予 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 存储桶（--artifacts-path，如果使用 Cloud Storage）读取 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 中查看日志，您需要拥有项目的日志查看器 (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"

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

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

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
USER_EMAIL：您的用户账号邮箱。
SERVICE_ACCOUNT_EMAIL：您的服务账号邮箱。
STAGING_BUCKET：输出暂存 Cloud Storage 存储桶 (--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 会将每个节点的 run_results.json 覆盖为 success 状态。前 dbt build 的测试结果会丢失，并且目录会将每项数据质量测试报告为通过。

了解 Cloud Storage 角色

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

输入（dbt 来源工件）：生成的 dbt JSON 文件所在的位置。这可以是机器或 CI 运行器上的本地目录路径（例如 ./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）才能上传文件，而 Knowledge Catalog 服务代理需要具有读取权限 (roles/storage.objectViewer) 才能导入文件。

从 dbt Cloud 运行作业导入元数据

Knowledge Catalog 不会直接连接到 dbt Cloud。由于 dbt Cloud 作业会生成与 dbt Core 相同的工件文件，因此您可以通过将这些工件文件检索到本地目录或输入 Cloud Storage 存储桶并运行 gcloud 命令，从 dbt Cloud 导入元数据。

在检索工件之前，请配置 dbt Cloud 作业以生成完整的工件集。然后，您可以使用以下方法之一从 dbt Cloud 作业运行中检索工件文件：

从 dbt Cloud 控制台下载工件：从 dbt Cloud 界面中的作业运行详情页面手动下载工件文件，以进行一次性导入或初始测试。
使用 dbt 平台 CLI 下载工件：在本地终端上执行 dbt Cloud 中的 dbt 命令，以便在开发过程中自动将生成的工件保存到本地项目目录。
使用 dbt Administrative 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 作为作业命令，而不是选择在运行时生成文档选项。在运行时生成文档复选框会运行不带 --no-compile 的 dbt docs generate，这会覆盖 dbt build 中的测试结果，如 dbt 前提条件中所述。请注意，如果命令步骤失败，作业也会失败，而复选框步骤不会导致作业失败。

如果 dbt build 失败（例如，由于测试失败），dbt Cloud 会跳过其后的命令，并且运行没有 catalog.json。如需始终生成一个，请在 dbt build 之前添加 catalog 命令。然后，目录会描述构建之前的表。

如需了解详情，请参阅 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 Administrative API 下载工件

您可以使用 dbt Administrative 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 存储桶，然后针对该路径运行配置 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 触发导入

您可以配置 dbt Cloud webhook，以便在每次作业运行完成时触发自动元数据导入，而无需轮询 API。Webhook 会将载荷发送到您提供的 HTTP 端点：

在 dbt Google Cloud 控制台中，前往账号设置 > Webhook，然后点击创建 Webhook（或创建新的 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 文档中的作业的 webhook。

配置 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 工件在此运行中不存在的切面会保留上一次运行为其提供的值。此方法适用于常规、重复的提取。请参阅重新运行提取。
- --include-entry-links：发出 dbt 关系的条目链接。此选项默认处于启用状态。如需停用该工具，请使用 --no-include-entry-links。该命令会发出以下条目链接类型：
  - reference：一个资源依赖、描述或使用另一个资源。这涵盖节点之间的 dbt 依赖关系、测试及其测试的资源、语义模型或指标及其构建所基于的资源、节点及其调用的项目宏，以及节点及其具体化的 BigQuery 表。
  - schema-join：由 dbt relationships 测试声明的可联接列。
- --skip-bigquery-link：跳过 reference 个链接（dbt 节点 → 物理 BigQuery 表）。默认情况下，系统会为每个物化 dbt 节点（模型、种子、快照）发出一个 reference 链接，其 BigQuery 数据集位于导入位置 (--location)。dbt 来源不会收到指向其 BigQuery 表的 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 暂存存储桶 (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 资源。
条目的显示名称、说明或标签发生更改。
条目层次结构发生变化。
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 搜索页面。

转到搜索
在过滤条件面板中，过滤 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 Administrative API 下载工件

检索运行 ID

使用 webhook 触发导入

配置 dbt 连接

控制台

gcloud

必需的标志

可选标志

REST

重新运行提取

搜索和查看 dbt 元数据

控制台

gcloud

REST

后续步骤

从 dbt Core 导入元数据