外部沿袭关系

Unity Catalog 会自动捕获 Azure Databricks 上运行的查询的运行时数据沿袭信息。但是，你可能有一些在 Azure Databricks 外部运行的工作负载（例如，第一英里 ETL 或最后一英里 BI）。 Unity Catalog 允许您添加外部沿袭元数据，以补充 Azure Databricks 自动捕获的数据沿袭，从而在 Unity Catalog 中提供端到端的沿袭视图。当您想要记录数据在被引入 Unity Catalog 之前来自何处（例如 Salesforce 或 MySQL），或者记录数据在 Unity Catalog 之外的何处被使用（例如 Tableau 或 Power BI）时，这会非常有用。

可以通过两种方式添加外部世系：

使用目录资源管理器 UI、外部元数据和外部世系 API 或用于Python的 Databricks SDK 手动操作。

以下数据沿袭图显示了 MySQL 和 PostgreSQL 中的两个外部表，这些表作为 Unity Catalog 托管表被引入 Azure Databricks，并将多列转换为一个 release_date 列，随后由外部报表使用。

显示外部上游表和连接到 Unity 目录表的下游报表的世系图，右上角带有“创建外部世系”按钮。

有关Azure Databricks中的数据世系的一般信息，请参阅 Unity 目录中的世系。

要求

若要在 Unity 目录中添加外部世系元数据，必须具有以下权限，具体取决于特定任务：

若要在 Unity Catalog 中创建外部元数据可保护对象，您必须对元存储具有 CREATE EXTERNAL METADATA 权限。
若要指定外部元数据对象和任何其他 Unity 目录对象之间的世系关系，您必须对外部元数据对象具有 MODIFY 特权。
若要指定与 Unity Catalog 对象的下游世系关系，您必须对对象具有读取权限（例如， SELECT 对表）。
若要指定与 Unity Catalog 对象的上游世系关系，您必须对对象具有写入权限（例如， MODIFY 对表）。

添加外部血缘元数据

添加外部血缘元数据：

在 Unity 目录中创建外部元数据安全对象。

此对象表示外部系统中的实体，例如 Tableau 中的仪表板。
配置外部元数据对象与另一个 Unity 目录对象（例如表、模型、路径或其他外部元数据对象）之间的世系关系。

创建世系关系后，外部元数据对象将显示在世系图视图中。

可以使用目录资源管理器 UI 创建外部元数据对象并配置世系关系。若要从现有世系图开始，请单击图形右上角的 “创建外部世系 ”。还可以从目录资源管理器中的 “外部数据 ”部分开始，如以下部分所述。

创建外部元数据对象

可以使用目录资源管理器或外部元数据 API 创建外部元数据对象。

若要使用目录浏览器创建外部元数据对象，请执行以下操作：

在 Azure Databricks 工作区中，单击目录。
单击 “外部数据 > ”按钮，转到“ 外部元数据 ”选项卡，然后单击“ 创建外部元数据”。
指定元数据详细信息。

必填：
- 名称：输入一个可读的名称，以帮助Azure Databricks用户了解他们在世系中看到的内容。外部元数据对象是 Unity 目录安全对象，因此名称必须遵循 Unity 目录对象命名规则。请参阅安全对象命名要求。
- 系统类型：从常见外部数据和 BI 系统列表中选择。如果找不到您要的，请选择自定义。
- 实体类型：输入对象类型，例如“table”或“dashboard”。
自选：
- URL：如果希望世系图查看器能够单击外部资产（例如 Tableau 仪表板），请输入对象的 URL。
- 说明
高级：
- 列：如果要从此外部对象到另一个 Unity 目录对象执行列级映射，请输入列名称。选择 UI 可逐个输入这些项，或选择 文本输入 在单个文本框中输入以逗号分隔的列表。
- 属性：如果要在世系中跟踪其他属性，请将其输入为 JSON 键值对。可以使用 UI 输入每个键值对，或输入完整的 JSON 对象。
单击 “创建” 。

对话框提供查看外部元数据对象或为对象创建世系关系的选项。

要用程序创建外部元数据对象，可以使用 Python 的 Databricks SDK 或 REST API。以下示例创建一个外部元数据对象，代表一个 Salesforce 表。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import ExternalMetadata, SystemType

w = WorkspaceClient()

external_metadata = w.external_metadata.create_external_metadata(
    external_metadata=ExternalMetadata(
        name="salesforce_accounts",
        system_type=SystemType.SALESFORCE,
        entity_type="table",
        url="https://my-org.salesforce.com/lightning/o/Account/list",
        description="Salesforce Account records ingested into Databricks.",
    )
)

完整参数列表请参见外部元数据API。

REST API

用你的工作区 URL 替换 <workspace-url>。这个例子假设 DATABRICKS_TOKEN 环境变量被设置为Databricks的个人访问令牌。

curl -X POST \
  https://<workspace-url>/api/2.0/lineage-tracking/external-metadata \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "salesforce_accounts",
    "system_type": "SALESFORCE",
    "entity_type": "table",
    "url": "https://my-org.salesforce.com/lightning/o/Account/list",
    "description": "Salesforce Account records ingested into Databricks."
  }'

完整的请求字段列表，请参见外部元数据API。

创建世系关系

可以使用目录资源管理器、外部世系 API 或用于 Python 的 Databricks SDK 创建世系关系。

若要添加外部元数据对象和其他 Unity 目录对象之间的关系，请执行以下作：

按照上述提示作，或在目录资源管理器中找到现有的外部元数据对象：
1. 单击目录
2. 单击“ 外部数据 > ”按钮
3. 转到 “外部元数据 ”选项卡并选择外部元数据对象。
单击“ 创建世系关系”。
选择是要创建上游还是下游关系。
输入要创建关系的对象类型：
- 表：使用搜索对话框选择表。
- 模型：使用搜索对话框选择模型，然后选择模型版本。
- 路径：对于卷或外部位置，请输入路径。
- 外部元数据：从下拉菜单中选择外部元数据对象。
（可选）单击“ 高级 ”添加：
- 外部元数据对象与源或目标对象之间的列映射。
- 其他元数据，以 JSON 键值对形式表示。例如，您可以使用它们输入用于根据外部元数据对象创建表的查询文本，或输入用于说明生成该关系的外部工作流的注释。
单击 “创建” 。

现在可以在相关对象的“世系”选项卡中查看外部世系关系。

要用程序创建血脉关系，可以使用 Python 的 Databricks SDK 或 REST API。指定 source and target 对象，每个对象是 Unity 目录表、路径、模型版本或外部元数据对象。以下示例创建了从 Unity 目录表到 salesforce_accounts 外部元数据对象的关系，将表的 id 列映射到外部对象的 external_id 列。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    CreateRequestExternalLineage,
    ExternalLineageObject,
    ExternalLineageTable,
    ExternalLineageExternalMetadata,
    ColumnRelationship,
)

w = WorkspaceClient()

relationship = w.external_lineage.create_external_lineage_relationship(
    external_lineage_relationship=CreateRequestExternalLineage(
        source=ExternalLineageObject(
            table=ExternalLineageTable(name="main.sales.accounts")
        ),
        target=ExternalLineageObject(
            external_metadata=ExternalLineageExternalMetadata(
                name="salesforce_accounts"
            )
        ),
        columns=[ColumnRelationship(source="id", target="external_id")],
    )
)

有关参数的完整列表，请参见外部沿袭 API。

REST API

用你的工作区 URL 替换 <workspace-url>。这个例子假设 DATABRICKS_TOKEN 环境变量被设置为Databricks的个人访问令牌。

curl -X POST \
  https://<workspace-url>/api/2.0/lineage-tracking/external-lineage \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "table": { "name": "main.sales.accounts" } },
    "target": { "external_metadata": { "name": "salesforce_accounts" } },
    "columns": [{ "source": "id", "target": "external_id" }]
  }'

有关请求字段的完整列表，请参见 External Lineage API。

为外部世系关系建模

手动添加外部世系时，使用以下模式对更复杂的关系建模：

连接两个 Unity 目录表：若要在 Unity 目录中注册的两个表之间指定世系关系，请创建位于两个表之间的外部元数据对象。将一个表指定为外部元数据对象的上游，另一个表作为下游表，以便它们显示在世系图中。
添加多个级别的世系：若要注释在进入Azure Databricks之前通过多个系统传递的数据，请创建多个外部元数据对象并配置每个系统之间的外部世系关系。
添加列级世系：在创建外部元数据对象时指定列名，然后在配置世系关系时映射源列和目标列。

Limitations

世系系统表中未记录外部世系（system.access.table_lineage 和 system.access.column_lineage）。
每个元存储最多可创建 10,000 个外部元数据对象和 100,000 个外部血缘关系。请参阅资源限制。

其他资源

Last updated on 2026-09-23

外部沿袭关系

要求

添加外部血缘元数据

创建外部元数据对象

Python SDK

REST API

创建世系关系

Python SDK

REST API

为外部世系关系建模

Limitations

其他资源

其他資源