企业官网建设流程全解析

OpenMetadata 元数据摄取管线配置指南：数据库服务 Metadata Pipeline 的 14 个核心配置项深度解析

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata

导读

Metadata Pipeline（元数据摄取管线）是 OpenMetadata 连接数据库服务、持续同步库表结构、视图、存储过程等元数据信息的核心工作流。本指南以 OpenMetadata 官方服务配置文档 metadata.md 为骨架，逐项讲解 Database Service Metadata Pipeline 的 14 个配置项——从四类过滤模式、FQN 过滤开关，到软删除语义、调试日志与重试策略——并结合仓库内摄取工作流源码与真实 YAML 示例，帮助你在 UI 表单与 YAML 配置两个层面都能准确、可复用地完成元数据摄取的精细化管控。

一、元数据摄取管线与配置文档的定位

OpenMetadata 的元数据摄取由MetadataWorkflow承载，其实现位于 metadata.py：

class MetadataWorkflow(IngestionWorkflow): """ Metadata ingestion workflow implementation. """ def set_steps(self): # We keep the source registered in the workflow self.source = self._get_source() sink = self._get_sink() self.steps = (sink,)

从源码结构看，Metadata 工作流由「Source（读取源端元数据）」与「Sink（写入 OpenMetadata 服务端）」两步构成，Source 类型即mysql、postgres、snowflake等数据库连接器，Sink 类型为metadata-rest。管线每一步的行为都由sourceConfig.config下的参数控制。

本文档 metadata.md 正是这些参数在 OpenMetadata UI「服务 → 编辑 → 添加 Metadata Ingestion」页面中的官方字段说明来源。UI 中看到的每个配置项，都与文档中带$(id="...")标识的字段一一对应。下面按文档顺序逐一展开。

二、四类过滤模式：用正则精确圈定摄取范围

过滤模式（Filter Pattern）是元数据摄取中最常用的配置，用于控制「哪些对象进入 OpenMetadata」。每一类过滤模式都遵循同一套规则：

• Include（包含）：填入一组正则表达式，OpenMetadata 只摄取名称能匹配其中任意一个正则的对象，其余全部排除。例如只摄取名称以demo开头的数据库，Include 填^demo.*。
• Exclude（排除）：填入一组正则表达式，OpenMetadata 排除所有名称能匹配其中任意一个正则的对象，其余全部包含。例如排除名称中包含demo的数据库，Exclude 填.*demo.*。
• 两者可同时配置，最终生效范围是「被包含」与「未被排除」的交集。

文档按对象层级给出了四类独立的过滤模式：

1. Database Filter Pattern（数据库过滤）$(id="databaseFilterPattern")

控制数据库（database）是否纳入摄取。示例：

• Include^demo.*：仅摄取名称以demo开头的数据库。
• Exclude.*demo.*：排除所有名称含demo的数据库。

2. Schema Filter Pattern（模式过滤）$(id="schemaFilterPattern")

控制 schema 是否纳入摄取。语法与数据库过滤完全一致，正则匹配的是 schema 名称：

• Include^demo.*：仅摄取名称以demo开头的 schema。
• Exclude.*demo.*：排除所有名称含demo的 schema。

3. Table Filter Pattern（表过滤）$(id="tableFilterPattern")

控制 table 是否纳入摄取，正则匹配表名：

• Include^demo.*：仅摄取名称以demo开头的表。
• Exclude.*demo.*：排除所有名称含demo的表。

4. Stored Procedure Filter Pattern（存储过程过滤）$(id="storedProcedureFilterPattern")

控制存储过程是否纳入摄取。文档给出了专用于存储过程的示例：

• Include^sp_.*：仅摄取名称以sp_开头的存储过程。
• Exclude.*temp.*：排除所有名称含temp的存储过程。

过滤在源码中的实际落点

过滤并非 UI 层噱头，而是直接作用于摄取拓扑的关键节点。在数据库服务的抽象基类 database_service.py 中：

class DatabaseServiceSource(TopologyRunnerMixin, Source, ABC): """ Base class for Database Services. It implements the topology and context. """ ... @abstractmethod def get_database_names(self) -> Iterable[str]: """ Prepares the database name to be sent to stage. Filtering happens here. """ ... @abstractmethod def get_tables_name_and_type(self) -> Iterable[tuple[str, TableType]] | None: """ Prepares the table name to be sent to stage. Filtering happens here. """

从源码结构可以确认：get_database_names、get_tables_name_and_type等抽象方法在实现中都会基于本节的 Filter Pattern 对候选对象做正则匹配过滤，之后再进入 Sink 写入 OpenMetadata。也就是说，配置过滤模式能够直接减少源端到服务端的无效数据传输与 API 调用，而不是先全量摄取再丢弃。

三、Use FQN For Filtering：按全限定名过滤同名对象

$(id="useFqnForFiltering")是一个开关型配置：开启后，上述过滤模式将作用于对象的Fully Qualified Name（FQN，全限定名），即service_name.db_name.schema_name.table_name这样的完整路径；关闭（默认）时则只作用于对象的裸名称（如table_name）。

典型场景：当多个数据库下存在同名 schema、或多个 schema 下存在同名表，而你想只过滤掉其中某一个时，仅凭裸名称无法区分，此时应开启该开关，在过滤模式中写入完整 FQN 路径（例如表过滤的 Exclude 填^my_service.my_db.my_schema.demo_table$）即可精确定位。

四、Include Views / Include Tags：摄取内容的两个快捷开关

• Include Views$(id="includeViews")：控制是否将视图（view）纳入元数据摄取。关闭后，源端视图将不会被同步。
• Include Tags$(id="includeTags")：控制是否将源端已有的标签（tags）随元数据一起摄取进 OpenMetadata。如果源系统（如 Snowflake、BigQuery 的标签体系）与 OpenMetadata 标签体系存在映射关系，此开关决定是否同步。

二者都是布尔开关，语义直白，但会显著影响摄取结果的数据量与后续治理工作流——关闭 Tags 可避免源端标签污染 OpenMetadata 的标签体系，适合标签治理规范尚未统一的团队。

五、Override Metadata：元数据覆盖策略

$(id="overrideMetadata")控制源端摄取到的元数据是否覆盖 OpenMetadata 服务端已有的元数据，是维护数据质量的关键开关：

• 开启（enabled）：源端摄取的元数据将直接覆盖并替换 OpenMetadata 中已存在的同名元数据。
• 关闭（disabled）：源端摄取的元数据不会覆盖已有值，只会填充 OpenMetadata 中尚未赋值的字段。

文档明确指出，该策略仅适用于description（描述）、tags（标签）、owner（负责人）和displayName（显示名）这四类字段。

该配置在源码中会被直接传递到 Sink 层。在 metadata.py 中可以看到：

def _get_sink(self) -> Sink: sink_type = self.config.sink.type sink_class = import_sink_class(sink_type=sink_type) sink_config = self.config.sink.model_dump().get("config", {}) sink_config.setdefault("override_metadata", self._source_override_metadata()) sink: Sink = sink_class.create(sink_config, self.metadata) return sink def _source_override_metadata(self) -> bool: source_config = self.config.source.sourceConfig.config return bool(getattr(source_config, "overrideMetadata", False))

这段源码证实：overrideMetadata取自source.sourceConfig.config，其取值会通过sink_config.setdefault(...)注入 Sink 配置。若管线未显式设置该字段，则按False（不覆盖）处理——这正是「服务端已有的人工编辑描述、标签、负责人不被摄取任务冲掉」的保障机制。

实践建议：在团队刚接入 OpenMetadata、需要以源端为准批量补齐描述时开启；在元数据已经过多轮人工治理后，务必关闭以避免源端的空值或过期描述覆盖人工成果。

六、Enable Debug Logs：问题排查入口

$(id="enableDebugLog")将摄取的进程日志级别切换到 debug。开启后，可在服务的Ingestion（摄取）Tab中查看更详细的执行日志，从而深入定位错误根因。

配合 YAML 侧的workflowConfig.loggerLevel（可取DEBUG、INFO、WARN、ERROR），可以在 sample_data.yaml 这类示例中看到其写法：

workflowConfig: loggerLevel: INFO # DEBUG, INFO, WARN or ERROR

当 UI 表单排查信息不足时，在 YAML 中直接设置loggerLevel: DEBUG也是等价的调试手段。

七、Mark Deleted Tables：表的软删除语义

$(id="markDeletedTables")是可选配置，用于在摄取过程中启用表的软删除（soft deletion）。启用后需要把握三个关键约束：

1. 仅作用于源端已删除的表：只有「从数据源中被删除」的表才会被软删除，普通缺失不会被误删。
2. 仅作用于当前管线正在摄取的 schema：软删除严格限定在本管线本次摄取的 schema 范围内。
3. 级联删除关联实体：被软删除的表所关联的 test suite（测试套件）、lineage（血缘）等实体也会一并删除。

会发生软删除的场景

• 未配置任何过滤，但某表已在数据源中删除 → 该表在 OpenMetadata 中被软删除。
• 配置了Schema Filter Pattern只包含SchemaA→SchemaA中任何被源端删除的表都会在 OpenMetadata 中被软删除。
• TableA已存在于 OpenMetadata，之后给Table Filter Pattern添加了对TableA的排除 →TableA会被软删除。

不会发生软删除的场景

• 已摄取SchemaA与SchemaB，之后用Schema Filter Pattern排除SchemaB→SchemaB中的表不会被删除（被排除的 schema 根本不参与本次摄取）。
• 已摄取SchemaA与SchemaB，本次管线用Schema Filter Pattern只包含SchemaA→SchemaB中源端已删除的表不会被删除（SchemaB在本次摄取中被忽略）。

在上述不会被自动软删除的情况下，文档明确建议：可在 UI 中手动删除对应的表或 schema。

理解这套语义非常关键——它意味着软删除的触发与「过滤模式」强耦合，过滤范围的收缩并不会自动清理过滤范围之外的存量数据。

八、Mark Deleted Stored Procedures：存储过程的软删除

$(id="markDeletedStoredProcedures")与 Mark Deleted Tables 语义完全对称，只是作用对象从表换成了存储过程：

• 启用后，仅源端已删除、且位于当前管线正在摄取的 schema内的存储过程会被软删除；
• 关联的 test suite、lineage 一并删除；
• 场景规则与表一致：包含SchemaA时SchemaA内被删的存储过程会软删；排除或未摄取SchemaB时，SchemaB内被删的存储过程不会被软删，需在 UI 手动清理。

九、View Parsing Timeout Limit：视图解析超时

$(id="viewParsingTimeoutLimit")用于指定解析视图定义 SQL（view definition sql）以进行血缘（lineage）分析时的超时时间。视图的血缘推断需要对视图创建语句做 SQL 解析，复杂或超长的视图定义可能耗时较长；设置合理的超时上限可以避免单个视图解析阻塞整条摄取管线。该参数按需调大或调小，取值单位与具体配置表单提示一致，建议从默认值开始，遇到视图解析超时错误时再逐步调大。

十、Number of Retries 与 Raise on Error：失败处理策略

• Number of Retries$(id="retries")：工作流以失败告终时的重试次数。配置后，摄取任务失败会自动按该次数重试，适合网络抖动、源端临时不可用等瞬时故障场景。
• Raise on Error$(id="raiseOnError")：决定工作流遇到异常时是标记为失败（fail）还是避免抛出异常（avoid raising exceptions）。默认标记失败便于告警与排查；若你希望在个别对象摄取失败时不中断整条管线、让其余对象继续摄取，可关闭该开关。

两者配合使用：retries解决「瞬时失败重试」，raiseOnError解决「局部失败是否阻断整条管线」。

十一、一份完整的 Metadata Pipeline YAML 配置示例

以上全部配置项在 YAML 中统一位于source.sourceConfig.config下。参考仓库中 sample_data.yaml 的骨架结构，一个典型的数据库元数据摄取配置如下（字段名与文档中$(id="...")一一对应）：

source: type: mysql # 按实际连接器填写，如 postgres / snowflake / bigquery serviceName: local_mysql # 已在 OpenMetadata 中注册的服务名 serviceConnection: config: type: Mysql username: openmetadata_user authType: password: ${MYSQL_PASSWORD} hostPort: localhost:3306 databaseSchema: openmetadata_db sourceConfig: config: type: DatabaseMetadata # 元数据摄取管线类型 databaseFilterPattern: includes: - "^demo.*" excludes: - ".*backup.*" schemaFilterPattern: includes: - "^public$" tableFilterPattern: includes: - "orders|users" storedProcedureFilterPattern: includes: - "^sp_.*" useFqnForFiltering: false includeViews: true includeTags: true overrideMetadata: false enableDebugLog: false markDeletedTables: true markDeletedStoredProcedures: false viewParsingTimeoutLimit: 60 retries: 3 raiseOnError: false sink: type: metadata-rest config: {} workflowConfig: loggerLevel: INFO openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: ${JWT_TOKEN}

实践要点：

• type: DatabaseMetadata是数据库服务元数据摄取管线的固定取值，其余为本次讲解的 14 个配置项；
• 过滤模式的正则建议先在本地用小数据集验证，避免 Include/Exclude 写错导致漏采或误采；
• markDeletedTables与过滤模式耦合的软删除语义（见第七、八节）务必在启用前确认，防止意外的数据清理；
• overrideMetadata默认按false处理，人工治理后的描述、标签、负责人默认不会被摄取任务覆盖。

十二、配置项速查表

结语

Metadata Pipeline 是 OpenMetadata 数据资产持续新鲜度的生命线，而本文档覆盖的 14 个配置项正是对这条生命线「摄取什么、以什么方式摄取、失败如何处理」的完整控制面。过滤模式与 FQN 开关决定摄取范围，Include Views/Tags 与 Override Metadata 决定内容与覆盖策略，两个软删除开关决定存量数据的清理语义，调试与重试参数则保障管线可观测、可恢复。无论你是通过 UI 表单逐项配置，还是通过 YAML 声明式管理，都可以以上文为索引，在 metadata.md、metadata.py 与 sample_data.yaml 之间交叉对照，构建出符合自身数据治理要求的元数据摄取管线。

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata