OpenMetadata Couchbase 数据库连接器接入指南连接配置、元数据提取与源码解析【免费下载链接】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/OpenMetadataOpenMetadata 通过 Couchbase 连接器将 Couchbase 的 Bucket、Scope 与 Collection 抽象为标准的数据库层级元数据让 NoSQL 数据资产也能纳入统一的数据目录。本文以仓库内连接器文档为核心结合连接配置 JSON Schema、Python 摄取源码与单元测试完整讲解从界面表单配置、YAML 工作流编写到元数据提取原理的全过程。读完本文你将能够独立完成 Couchbase 服务的连接配置、连通性测试与元数据摄取排障。Couchbase 连接器概览Couchbase 连接器是 OpenMetadata 数据库Database服务家族的一员负责从 Couchbase 集群中提取元数据。它在 OpenMetadata 中的落地文件位于 Couchbase.md对应 UI 中创建 Database Service 时的连接表单帮助文案其底层由三部分协同工作连接配置 SchemacouchbaseConnection.json 定义了连接参数的字段、类型与必填约束同时驱动 UI 表单渲染与后端校验Python 摄取实现ingestion/src/metadata/ingestion/source/database/couchbase/ 目录下的connection.py、metadata.py、queries.py等文件负责建立连接、执行元数据提取单元测试test_couchbase.py 验证了 Bucket → Scope → Collection 的拓扑提取与列类型推断行为。前置要求账号与权限在开始配置之前请确保用于连接的账号具备读取 Couchbase 元数据所需的全部访问权限。从 couchbaseConnection.json 的字段描述可以确认Username to connect to Couchbase. This user should have privileges to read all the metadata in Couchbase.即该用户应具备读取 Couchbase 中所有元数据的权限包括集群内各 Bucket 的 Scope 与 Collection 信息。权限不足时摄取流程会在拉取 Bucket 列表或 Scope/Collection 列表阶段失败具体错误可参考后文常见排障一节。连接参数详解连接表单共包含四个核心参数对应 JSON Schema 中的username、password、hostport、bucket字段其中前三个为必填项见 Schema 中required: [hostport, username, password]。Username用户名用于连接 Couchbase 集群的用户名。该用户需要拥有读取全部元数据Buckets、Scopes、Collections的权限。在代码层面它被传入 Couchbase Python SDK 的PasswordAuthenticatorauth PasswordAuthenticator(connection.username, connection.password.get_secret_value())见 connection.pyPassword密码连接密码在 JSON Schema 中以format: password声明见 couchbaseConnection.json这意味着 OpenMetadata 会在存储与展示层面对该字段做敏感信息脱敏处理。读取时通过get_secret_value()取出明文用于认证。Hostport主机端口Couchbase 实例客户端连接的 hostname 或 endpoint。实际拼接连接 URL 的代码如下url f{connection.scheme.value}://{connection.hostport} cluster Cluster.connect(url, ClusterOptions(auth))见 connection.py连接协议由 Schema 中scheme字段决定当前仅支持couchbase一种取值见 couchbaseConnection.json因此最终 URL 形如couchbase://127.0.0.1。测试代码中使用的示例为hostport: localhost见 test_couchbase.py。Bucket NameBucket 名称Bucket 参数在 OpenMetadata 的数据库服务层级中承担数据库Database的角色。官方文档明确给出了 Couchbase 下的层级映射Database Service Bucket Schema Table对应到 Couchbase 原生概念即为Bucket→ OpenMetadata 的 Database数据库Scope→ OpenMetadata 的 Schema数据库模式Collection→ OpenMetadata 的 Table表不指定 Bucket 时的行为如果连接配置中不提供 bucket 名称默认会摄取所有可用 Bucket。这一行为在源码中有直接体现metadata.pydef get_database_names(self) - Iterable[str]: if self.service_connection.bucket: self.index_condition_map.clear() yield self.service_connection.__dict__.get(bucket) else: buckets self.couchbase.buckets() for bucket_name in buckets.get_all_buckets(): self.index_condition_map.clear() yield bucket_name.name即配置了bucket时只摄取该单个 Bucket未配置时遍历buckets().get_all_buckets()逐一枚举。默认 Schema 名在 Couchbase 的默认设置中每个 Bucket 至少包含_default作用域。摄取器将其作为默认 Schema 名处理常量定义于 metadata.pyDEFAULT_SCHEMA_NAME _default随后在索引条件构造get_index_condition时_default与非默认 Scope 会生成不同的 N1QL 查询条件详见下文索引条件与采样一节。层级映射的测试佐证单元测试 test_couchbase.py 给出了完整的映射示例测试中bucket: default对应的 Mock 实体为MOCK_DATABASE.name default、MOCK_DATABASE_SCHEMA.name default表的 fullyQualifiedName 为local_couchbase.default.default与Database Service Bucket Schema Table的层级完全一致。完整 YAML 工作流示例除了在 UI 上通过表单创建服务Couchbase 连接器也支持以 YAML 工作流方式运行元数据摄取。仓库提供的可运行示例位于 couchbase.yamlsource: type: couchbase serviceName: local_couchbase serviceConnection: config: type: Couchbase bucket: bucket username: username password: password hostport: hostport sourceConfig: config: type: DatabaseMetadata sink: type: metadata-rest config: {} workflowConfig: loggerLevel: INFO # DEBUG, INFO, WARN or ERROR openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: your-jwt-token各字段说明字段含义说明source.type连接器类型固定为couchbaseserviceName服务名称在 OpenMetadata 中注册的 Database Service 名称需全局唯一serviceConnection.config.type连接配置类型固定为Couchbase对应 Schema 中couchbaseType枚举bucketBucket 名称可选不填则摄取全部 BucketsourceConfig.config.type摄取类型元数据摄取固定为DatabaseMetadataworkflowConfig.openMetadataServerConfigOpenMetadata 服务端信息服务地址、认证方式与 JWT Token在实际使用中jwtToken应替换为你自己的 Token并通过环境变量等方式注入避免明文出现在配置文件中。源码纵深连接建立与连通性测试连接建立Connection HandlerCouchbaseConnection继承自BaseConnection其_get_client方法使用 Couchbase Python SDKcouchbase包建立连接见 connection.py使用PasswordAuthenticator(username, password)构造认证器以couchbase://hostport为地址调用Cluster.connect(url, ClusterOptions(auth))通过self._on_close(cluster.close)注册关闭回调保证工作流结束时优雅释放连接。值得注意SDK 采用惰性导入import-outside-toplevel仅在真正建立连接时才加载couchbase依赖包避免无 Couchbase 环境的场景下不必要的依赖开销。对应测试 test_connection.py 也明确验证了这一点——该测试不导入 SDK仅断言CouchbaseConnection是BaseConnection的子类。连通性测试步骤test_connection方法实现了两步连通性探测见 connection.pyGetDatabases调用client.buckets().get_all_buckets()枚举所有 Bucket验证集群访问与读取权限GetCollections取第一个 Bucket 后调用collections().get_all_scopes()验证 Scope/Collection 元数据读取能力。这两步测试既可在创建服务的 UI 向导中触发也可作为自动化工作流Automation Workflow周期执行结果统一封装为TestConnectionResult返回。源码纵深元数据提取流程Couchbase 摄取的核心逻辑位于 metadata.py 中的CouchbaseSource类继承自CommonNoSQLSource。整体提取链路为get_database_names()按是否配置bucket返回单个或全部 Bucket 作为 Databaseget_schema_name_list()对每个 Bucket 调用bucket.collections().get_all_scopes()将全部 Scope 作为 Schema 返回见 metadata.pyquery_table_names_and_types()从 Scope 对象中提取所有 Collection 作为 Table见 metadata.pyget_table_columns_dict()对每个 Collection 执行 N1QL 采样查询推断列结构。索引条件与采样由于 Couchbase 是 Schemaless 的文档型数据库摄取器需要通过索引信息辅助构造采样查询。get_index_condition会查询系统索引表system:indexesSQL 定义于 queries.pyselect * from system:indexes where {condition}对于_default作用域条件为keyspace_id bucket对于其他作用域条件为bucket_id bucket AND scope_id schema。若存在主索引primary index则直接返回空条件否则收集各索引键index key构造WHERE (key is not missing ...)条件见 metadata.py确保采样查询能命中有效文档。结果按COUCHBASE_GET_DATA模板执行select * from {database_name}.{schema_name}.{table_name} {condition} limit {sample_size}见 queries.py其中sample_size来自CommonNoSQLSource的SAMPLE_SIZE常量。如果目标表没有创建任何索引SDK 会抛出QueryIndexNotFoundException此时该表列提取失败并记录警告日志提示检查是否为表创建了索引或表中是否存在数据见 metadata.py。列类型推断从采样文档中摄取器会推断出对应 OpenMetadata 列类型。测试数据与期望类型展示了这一映射关系见 test_couchbase.py采样 JSON 字段推断 DataTypename: mayur字符串STRINGage: 25数值INTis_married: false布尔BOOLEANaddress: {line: random address}嵌套对象JSON且嵌套字段line被展开为子列children这说明 Couchbase 连接器能够将嵌套 JSON 文档结构转化为 OpenMetadata 的列-子列模型为后续的数据血缘、数据质量与搜索索引提供结构化元数据基础。过滤模式与高级配置除四个核心连接参数外couchbaseConnection.json 还定义了三个可选的正则过滤模式均引用公共filterPattern定义schemaFilterPattern按正则仅包含/排除匹配的 SchemaScopetableFilterPattern按正则仅包含/排除匹配的 TableCollectiondatabaseFilterPattern按正则仅包含/排除匹配的 DatabaseBucket。例如只想摄取名称以prod_开头的 Bucket 时可在serviceConnection.config中追加databaseFilterPattern: includes: - prod_.* excludes: []过滤模式与未指定 bucket 时摄取全部 Bucket的行为配合使用可以在不逐个列举 Bucket 的情况下实现精细化摄取范围控制。常见排障连接失败 / 认证失败检查hostport是否可从 OpenMetadata 摄取容器访问注意scheme固定为couchbase勿写成couchbases并确认用户名密码在 Couchbase RBAC 中具备正确的权限角色。Fetching columns failed ... check if the index is created目标 Collection 未建立索引导致采样查询失败。为相关 Collection 创建主索引或覆盖索引后重新运行摄取。权限不足导致 Bucket/Scope 列表为空连接测试步骤GetDatabases/GetCollections可快速定位权限问题也可在 UI 创建服务时直接触发这两步连通性测试来验证账号权限。小结Couchbase 连接器通过Database Service Bucket Schema Table的四级映射将 NoSQL 的 Bucket/Scope/Collection 完整纳入 OpenMetadata 数据目录体系四个连接参数username、password、hostport、bucket驱动连接建立两步连通性测试验证权限N1QL 索引条件采样完成文档结构到列模型的转换。无论是通过 UI 表单、YAML 工作流还是自动化工作流掌握上述配置与原理即可完成 Couchbase 元数据摄取并借助过滤模式精细控制摄取范围。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考