接入数据源
登记数据库连接,准备采集账号和只读查询账号,采集表结构。
数据源:连接与只读账号
打开「数仓(数脉)」面板,点顶部的「数仓管理」,在弹窗左侧点「新增数仓」。左侧列表可以按名称、地址或数据库查找,也可以按数据库产品筛选。新增表单分三个小节:基本信息(名称、数据库产品、连接说明)、采集账号(地址、端口、数据库、采集账号、采集密码、「采集账号使用空密码」、「测试采集连接」)和只读查询账号。
两个账号的关系
数据源上有两个账号,用途分开:
- 采集账号:采集表、字段和关联所用的连接。只读取元数据,不扫描业务行。
- 只读查询账号:问数执行所用。必须是另一个独立账号,不能和采集账号相同,表单会直接拒绝同名账号。启用问数时才需要。
只读查询账号只允许拥有查询权限,不允许有写入权限、角色继承或转授权。不同产品的核验方式不同,例如 MySQL 系核验直接授予的 SELECT 和 USAGE,PostgreSQL 还会核验账号所有权、角色成员和写权限。数脉在每次执行前都会重新核验,核验不过就拒绝执行。
怎么选数据库产品
「数据库产品」下拉框分四组:通用关系型数据库、国产数据库、大数据与分析数仓、云数仓。按你的数据库选对应产品,不要用兼容协议代替,例如 MariaDB 就选 MariaDB,不选 MySQL。选定后端口自动换成该产品的默认端口,「连接说明」里写着协议和这个产品的要求。已经保存的数仓不能再切换产品,要换就新增一个连接。
数脉共有 24 种数据库的目录采集适配,其中 SQLite 的文件路径和启用由服务器配置,在控制台里不新增。各产品的验收程度不同,部分产品旁会标「待现场联调」,具体以交付说明为准。选好产品后,先读「连接说明」,其中写明了该产品的特殊要求,例如:
- Oracle 的「数据库」填服务名,MaxCompute 填 Project,Trino、PrestoDB 和 Flink 填 Catalog,并必须填写 Schema 或 Database 范围。
- Trino、PrestoDB、Hive、Spark、Impala 和 Flink 的只读问数需要服务端的可信部署证明;MaxCompute 需要服务端登记的只读策略证明。这些由部署管理员在服务端登记,表单里没有填写的地方。
- Oracle、SQL Server、达梦、KingbaseES、GaussDB、Hive、Spark 和 Impala 通过 JDBC 连接(MaxCompute 的执行也走 JDBC),需要 Java 17 运行时和驱动 JAR,由部署管理员挂载,不随镜像提供。
- GaussDB 的只读执行只支持 10 系列 Kernel 507 的 PG 模式;OceanBase 只支持 MySQL 模式。
主要字段
| 字段 | 说明 |
|---|---|
| 名称 | 必填,例如「订单业务数仓」。 |
| 地址、端口 | 地址只填主机名或 IP,不含协议、账号或路径。 |
| 数据库 | 目标库名。部分产品含义不同,见上文。 |
| Schema 范围(可选) | 逗号分隔,最多 100 项,每项不超过 128 个字符。留空时按产品取默认值:PostgreSQL 系默认 public,SQL Server 默认 dbo,Oracle 默认采集账号同名的大写 Schema。额外的 Schema 要写进范围里,不会因为驱动返回而被扩大。 |
| 采集账号、采集密码 | 密码加密保存,不回显。账号确实没有密码时,勾选「采集账号使用空密码」。 |
| 认证方式 | Hive 和 Spark 可选 Kerberos:填采集 Principal、HiveServer2 服务主体和只读 Principal,不填密码。keytab 由服务端管理员按 Principal 登记,不经表单。 |
| 启用只读查询 | 勾选后展开「独立只读账号」「只读密码」「最多返回行数」「查询超时(毫秒)」。 |
| 已确认该独立账号仅拥有查询权限 | 启用只读查询时必须勾选,这是管理员的声明,数脉另会核验账号权限。 |
| 最多返回行数 | 1 到 500,默认 200。 |
| 查询超时(毫秒) | 1 到 10000,默认 5000。 |
| 使用 TLS、CA 证书 | 在「高级连接」里。达梦、KingbaseES、GaussDB、Impala、Oracle、SQL Server 和 MaxCompute 的「使用 TLS」复选框是禁用的,不能勾选。不能关闭证书校验;CA 证书可选,留空时使用服务端系统信任库,粘贴后加密保存且不回显。只有 Hive 和 Spark 可以填 CA 证书。 |
| 大数据套件目录(可选) | 让 DataWorks、DataArts Studio 或 WeData 提供表、字段和业务描述,问数仍由上面的计算引擎执行。需要填套件类型、OpenAPI 地址和只读密钥,密钥只写不读。套件目录目前只有 DataWorks 加 MaxCompute 的组合用真实账号验证过。 |
测试连接和保存
填好后,分别点「测试采集连接」和「测试只读连接」。测试不保存配置,也不读业务数据。采集测试验证目标 Schema 的系统目录能读;只读测试还会核验账号权限,并做一次零行 SELECT。结果有三种:
| 状态 | 含义 |
|---|---|
| 验证通过 | 采集账号:连接成功,目标 Schema 的固定系统目录查询通过。只读账号:连接成功,通过只读权限核验和零行查询。每次真正执行前仍会重新检查权限。 |
| 暂不支持验证 | 该产品还没有保存前的连接验证。本次没有确认连接,也没有确认只读权限。 |
| 验证失败 | 下方给出原因,见下表。 |
| 失败原因 | 怎么处理 |
|---|---|
| 目标地址拒绝连接、连接中断或目标不可达、无法解析主机名 | 检查数据库是否启动,主机、端口、网络、防火墙和 DNS。 |
| 账号认证失败 | 检查用户名、密码,以及数据库是否允许该账号从数脉所在地址登录。 |
| 目标数据库不存在 | 检查数据库名称。 |
| TLS 连接或证书校验失败 | 检查服务端的 TLS 设置和受信任证书。 |
| 连接验证超时 | 检查数据库负载、网络和端口。 |
| 该账号无法读取所需系统目录 | 检查目标数据库和 Schema 的元数据读取权限。 |
| 只读账号审核未通过 | 账号可能含写权限、角色继承或授权能力,也可能缺少目标表的 SELECT 权限。按只读账号的要求调整后重试。 |
| 当前 Schema 下没有可见的普通表 | 账号已连接,但无法做零行 SELECT 验证。给只读账号授予至少一张表的 SELECT。 |
| 服务端缺少驱动或 SQL 校验运行时 | 请部署管理员安装对应的驱动。 |
| 没有登记 Kerberos 的 keytab,或 Kerberos 登录失败 | 请管理员在服务端登记 keytab;同时检查 KDC 是否可达、服务端时钟是否同步。 |
| 数据库地址属于回环、内网、链路本地或云元数据等受限网段 | 服务端出站策略拒绝了连接。数据库确实在内网时,由部署管理员把该主机或网段放进出站放行名单(部署配置里的 ECHOMIND_EGRESS_ALLOW)。部署自身的数据库不能这样放行。 |
| 当前连接验证正在运行 | 同一个人同时只能跑一个测试,稍等后重试。 |
测试通过后点「创建数仓」。保存只记录配置,不代表连接已验证。已有数仓的按钮是「保存更改」,旁边还有「移除数仓」。
- 修改连接、账号或执行设置:保存前会弹出「确认连接或执行配置变更」。这类变更会撤下已发布的拓扑,清空旧绑定的表结构、关联和业务说明,需要重新采集并补充。只改名称不受影响。
- 修改密码:密码只写不读。没有更换连接或账号时,留空表示保留原密码;更换地址、数据库或账号后,必须重新填写。
- 移除数仓:只取消数脉里的登记,移除入口、结构和业务说明,数据库里的表和数据保持不变,也不会执行 DROP。
结构采集与自动采集
第一次采集
数据源创建后,回到面板顶部点「采集建图」。数脉用采集账号按固定的目录查询读取表、视图、字段、类型、主键、唯一键、外键和注释,建立结构地图。以后这个按钮叫「更新结构」,用来读取最新的表、字段和关联。面板顶部会显示表数、字段数、结构修订号,以及「采集说明」。
采集有这些范围限制:一个数据源最多 1000 张表、12000 个字段,每张表最多 500 个字段,整库最多 2000 条目录关联,超限时采集失败,并要求明确采集范围;超过 80 张表或 1000 个字段的库,仍然完整采集,只是不做整库的 AI 关系推断,业务关联可以继续手工维护。
自动采集
在「数仓管理」弹窗里选中数据源,打开「自动采集」标签。它按计划检查结构变化,默认停用。
| 设置 | 说明 |
|---|---|
| 定时检查结构 | 勾选后启用。只检查表、字段和关联,不读业务行。 |
| 检查周期 | 「按间隔」或「每天固定时间」。间隔 5 分钟到 7 天(填 5 至 10080 的整数分钟);每天固定时间按北京时间。 |
| AI 补充业务理解 | 结构变化后,由模型对变化的表和字段生成业务理解建议,人工确认后才应用,可能产生模型费用。每轮最多分析 20 张变化表,上下文最多 50 张表、1000 个字段,超出的部分会提示,不会自动发布。 |
| 保存采集设置、立即检查一次 | 前者保存并按计划运行,后者马上检查一次。关闭窗口不影响已提交的后台检查。 |
「运行状态」里显示当前状态、上次检查、下次检查、最近结构变化和表、字段、关联的数量。状态含义如下:
| 状态 | 含义 |
|---|---|
| 已停用、等待检查、正在检查 | 按设置运行的三种常态。 |
| 结构无变化、结构已更新 | 检查完成。无变化时不会再请求模型。 |
| 部分完成 | 结构已采集,但后续的业务理解或索引更新没有完成,页面会写明下一步。 |
| 检查失败 | 先在「连接配置」里测试采集账号,再看排查详情。常见原因:采集账号验证失败、采集权限不足、授权已被撤销、连接已变化。 |
| 配置待更新 | 连接已经更换。确认新连接和采集账号后,重新保存自动采集设置。 |
服务停止或重启会让正在进行的检查中断,恢复后手动检查一次即可。表、字段或关系变化后,要复核相关的指标、模板查询和授权。