DataNavo
Connects to MySQL as a business data source, enabling source table discovery, schema synchronization, and BI querying through semantic models; MySQL is also supported as the metadata database.
DataNavo
DataNavo 通过 MCP 为其他 Agent 提供 BI 和企业数据分析能力,并提供支持单企业和多租户的 MySQL BI Web 应用。配置数据源并同步源表,在关系画布和表单中维护同源多表语义模型,用维度、指标、筛选和排序自动查询,以二维表格查看精确结果。
计划使用的官网域名为 datanavo.dev。
第一次使用请从本地快速试用开始。示例使用合成数据,覆盖安装、初始化、建模发布和外部 MCP 查询。
启动
需要 Node.js 24.7+、Python 3.12,以及可访问的 MySQL。首次安装:
npm ci
python3.12 -m venv .venv
.venv/bin/python -m pip install -r python/requirements.txt
npm run build
npm start访问 http://127.0.0.1:3000 。无元数据库配置时显示部署配置页;启动终端会提示本次配置会话凭据文件的位置,在页面输入该文件内容。默认选中 SQLite,但不会自动创建数据库。首次建立新库时主动选择“初始化新的空库 / Schema”,测试后点击“保存并启用”并确认目标;元数据库与 Worker 就绪后,使用同一部署凭据完成产品初始化,选择单企业/多租户、首个企业及管理员;之后用用户名密码登录。本版账号密码不限制长度或强度,可留空;初始化、注册、改密与重置使用相同规则。普通用户由管理员分享租户可复用注册链接自行注册,用户管理没有直接新增账号。Ctrl+C 统一停止。
默认运行数据为 data/;正式部署将 DATANAVO_DATA_DIR 指向安装目录外的固定持久目录。SQLite、MySQL 均使用 MikroORM 和 JSON 文本,旧 JSONB 或其他不匹配结构明确拒绝,原数据不转换或清空。开发与验证使用独立数据目录。
npm start 启动前会比较 dist/web 与参与前端构建的源码(web/、shared/、设计系统组件、入口与构建配置):产物缺失或落后时自动运行 Vite 构建,因此改了前端后直接重启即可生效;产物新鲜时不做额外构建。这一步只做打包,完整校验(i18n、parser 生成、类型检查、后端构建)仍以 npm run build 为准;后端改动需先 npm run build:server,npm start 不会重建后端。
前端开发用 npm run dev,访问 Vite 显示的地址(默认 5173),/api 代理至 3000。入口先构建后端,修改后端后重新运行。直接访问 3000 时读到的是 dist/web 构建产物,由上述启动检查保证新鲜。PORT 可修改产品端口,开发代理需同时核对 vite.config.ts;DATANAVO_PYTHON 可指定 Python 可执行文件。
生产远程访问设置 DATANAVO_PUBLIC_URL=https://应用域名,用于可信 Origin、Secure Cookie 和注册/重置链接;不从转发头推断。回环 HTTP 仅供本地开发。会话绝对有效期 12 小时、空闲有效期 30 分钟;退出、改密、重置或停用后重新登录。页面、操作和模型权限来自当前有效角色,监控与全局配置仅部署管理员可见。实现与实际验证边界见身份权限验证。
Related MCP server: agent-gateway
AI 助手、公共结果与 CLI
官方助手是可选启用的 DataNavo 查询与建模客户端。在“系统配置 → AI 助手”启用并配置模型服务后使用;默认关闭。关闭后不接受新对话运行,已有会话、结果和执行记录保留,核心 BI、对外 MCP 与 CLI 独立运行。
助手的查询、建模、业务指南和结果读取统一通过本服务 /api/mcp,自动使用当前用户的短期委托凭据,无需配置 PAT。每次调用仍核验当前角色、资源权限和接口能力。保留流式回答、会话历史、上下文压缩、运行取消与执行记录。选择 DeepSeek 时固定开启深度思考;不提供任意外连 MCP、stdio、个人外部 Key、通用附件、文件工作区、沙箱、Shell 或任意代码执行。模型服务的部署凭据仍由管理员配置。
卡片引用公共查询产物并经 MCP 取数。结果支持分页、CSV/JSONL 导出和下载;删除会话不删除公共产物,关闭助手也不删除任何数据。完整边界见助手设计。
公共 BI API 位于 /api/bi/,建模入口位于 /api/bi/modeling/。查询使用名称 DSL、固定内容与校验 token;产物默认最多五行预览,完整数据按需分页。写操作先保存 operationId,断线后核对原回执,不盲目重放。模型写入返回草稿与修订,随后校验;发布使用单草稿及预期修订。
核心 CLI 使用账户菜单签发的个人访问令牌(PAT),保留查询、建模、导出及资源管理命令:
npm run build:server
export DATANAVO_URL=http://127.0.0.1:3000
read -rs DATANAVO_TOKEN
export DATANAVO_TOKEN
npm run cli -- models list --json
npm run cli -- sources list-for-modeling --json
npm run cli -- query analyze --input /absolute/path/query-request.json --json
npm run cli -- artifact rows --artifact-id <artifactId> --offset 0 --limit 100 --json
npm run cli -- --helpCLI 不提供聊天工作区、附件或 Skill 命令。下载必须指定新的本地 --output 文件。PAT 的接口能力与用户当前业务权限取交集,服务仅保存摘要;默认有效期 30 天,可设置 1–90 天。
完成的公共结果与导出保存在 query-artifacts/,会话保存在 agent/,操作回执保存在 operations/,均按租户/用户隔离。默认单结果 100 万行/64 MiB,容量不足拒绝新写入。文件目录由单一宿主独占,不支持多节点共享。旧元数据库结构明确拒绝启动,不自动迁移或清空;请显式初始化独立新库。
外部 Agent 与 WorkBuddy 接入
通过 /api/mcp 提供无状态 Streamable HTTP MCP,使用核心个人 PAT。工具覆盖模型发现、目录、查询、结果分页、导出、取消、建模读写及校验发布。Agent 使用 knowledge_browse、knowledge_search、knowledge_read 或 MCP Resources 读取获准的模型、共享知识和指南。知识正文保存在本地内容目录,SQLite 归档包含所需正文。官方助手使用同一工具合同,采用服务器内部委托身份。
远程部署配置可信 DATANAVO_PUBLIC_URL=https://应用域名,拒绝不可信 Origin。当前不提供 OAuth、stdio 桥接或客户端市场自动安装。查询返回最多五行预览及 artifactId,更多结果使用 artifact_rows,完整内容未读完不能推断全局结论。
连接配置、工具清单、使用流程及能力要求见接入指南。本机 WorkBuddy 的配置入口和首次信任步骤见WorkBuddy 接入。CLI 是独立可选客户端,可用 npm run pack:cli 生成安装包。
运行日志与排障
npm start 与 npm run dev 的产品后端默认同时向 stderr 和 <dataDir>/logs 保存 UTF-8 JSON Lines,最低级别为 info。每个 HTTP 响应携带服务端生成的 X-Request-Id,可按日志 requestId 找到终态,再由 failureId 关联安全根因。浏览器 API 错误保留 HTTP status 和请求编号。日志不会包含 SQL、绑定值、密码、请求正文或原始异常文案;debug 使用相同边界。Vite、npm 和构建工具输出不混入产品日志文件。
日志配置在启动时读取,变更后重启。DATANAVO_LOG_LEVEL 仅接受 debug、info、warn、error、fatal;DATANAVO_LOG_OUTPUT 接受默认 both 或仅终端的 stderr;DATANAVO_LOG_DIR 可指定绝对目录。默认单段上限 100 MiB,按大小或 UTC 日期轮转,滚动保留 7 天、合计最多 1 GiB 和 1024 段;先触发容量限制时保留时间会缩短。可通过 DATANAVO_LOG_MAX_FILE_MIB、DATANAVO_LOG_RETENTION_DAYS、DATANAVO_LOG_MAX_TOTAL_MIB 调整,范围及校验见配置合同。非法配置安全非零退出;合法配置遇到文件故障时保留 stderr 并继续业务。POSIX 新日志目录为 0700,文件为 0600;已有目录不符合私有权限要求时停用文件输出。
已构建安装可直接查询,无需启动服务;缺少产物时先运行 npm run build:server。默认显示最后 200 条匹配记录,--level 为最低级别,其他筛选取 AND;时间必须含时区,区间为 [since, until)。使用绝对 --dir 可独立读取另一个部署目录:
npm run logs
npm run logs -- --lang en --follow --level warn
npm run logs -- --request-id root-demo
npm run logs -- --failure-id failure-demo --since 2026-10-23T00:00:00Z
npm --silent run logs -- --json --limit 500目录只允许一个产品宿主写入,多实例须配置不同目录。正常停止回收 .writer-lock;SIGKILL、断电或锁操作中崩溃可能留下锁,后续实例保守停用文件输出。恢复前先停止所有使用该目录的实例并确认无写入者,再人工检查、移除 .writer-lock 并重启;保留全部 .jsonl,不自动按 PID 或超时抢锁。文件故障的有限恢复不会补写失败期间的记录。完整命令、故障和生命周期边界见开发设计。
正式部署仍应收集 stderr,覆盖文件故障和尽力输出的 fatal 事件,并限制访问、容量和保留期限;不要长期使用 2>>app.log 无限追加。Linux systemd 可让服务使用 StandardError=journal,由 journald 设置 SystemMaxUse、SystemKeepFree 和 MaxRetentionSec(例如 256M、1G、7day);用 journalctl -u datanavo -o cat 读取并过滤 JSON 事件。安装包同时保留 dist/shared/error-catalog.json、dist/shared/public-messages.json、dist/shared/locales/、shared/error-catalog.json、shared/public-messages.json 与 python/,Node/Python 从模块资源位置读取,不依赖启动时工作目录。缺省数据目录也相对安装根;显式相对 DATANAVO_DATA_DIR 仍相对启动 cwd,服务与 CLI 从不同目录启动时应使用绝对数据或日志目录。
单条日志不超过 16 KiB,每个 sink 的独立应用队列最多 1 MiB/1024 条;下游阻塞时优先丢弃 debug/info,恢复后报告累计损失。停止在既有总期限内为所有输出共同保留最多 1 秒刷新。日志不是数据库提交、资源已排空或断电持久化的证明;超时、响应中断及提交结果未知时先读取当前状态,不自动重放 SQL 或保存请求。基础接入证据见日志与异常验证,文件与本地查询的实际检查及未测边界见持久化验证。本轮在 macOS arm64、Node v26.12.0 验证,最低 Node 24、Linux/Windows、真实满盘及完整权限故障尚未验收。
元数据库配置
宿主管理配置位于
DATANAVO_DATA_DIR/metadata-config/。普通字段和 0600 凭据文件同代次保存,active.json原子发布;配置会话只接受回环同源请求。元数据库未就绪时业务 API 返回503/METADATA_NOT_READY。正常重启只打开当前已有库;目标丢失或变空不会重建。修改连接前停止原服务,再以
DATANAVO_METADATA_SETUP=1 npm start进入维护模式。切换库不会搬迁原数据。设置
DATANAVO_METADATA_CONFIG=/path/metadata.json时,部署文件为唯一且只读来源;秘密通过环境变量引用,错误不回退本地配置或 SQLite。首次自动部署先显式初始化,再启动产品。
npm run db:init -- --lang zh-CN --database /tmp/datanavo-check/metadata.sqlite
# MySQL 或外部插件使用部署文件;与 --database 互斥:
npm run db:init -- --config /path/metadata.jsonCLI 只对明确目标初始化及核验,不发布当前配置、不启动业务。当前完整结构重复执行不写 DDL;空目标以外的未知、部分或旧结构拒绝。共同定义见 entities.ts,运行时与外部插件说明见 metadata README。
MySQL 元数据库内置 mysql2 驱动,随 npm ci 和主程序交付。支持 MySQL 8.0.17+,使用 InnoDB、utf8mb4_0900_bin(NO PAD)、LONGTEXT 与 BIGINT;要求 InnoDB 页至少 16 KiB、max_allowed_packet 至少 32 MiB,以容纳完整索引和大 JSON。账号和专用 database 由管理员预先创建;初始化只创建应用表,不执行 CREATE DATABASE。元数据库连接与“数据源”页面的业务 MySQL 连接分别配置。
MySQL 部署文件示例:
{
"plugin": "mysql", "mode": "fields",
"values": { "host": "db.internal", "port": 3306, "username": "datanavo", "database": "datanavo_metadata", "tls": "verify_identity" },
"secretRefs": { "password": { "env": "DATANAVO_METADATA_PASSWORD" } },
"runtime": { "poolMax": 4, "operationTimeoutMs": 5000 }
}页面选择 MySQL 后使用同一声明式表单填写上述字段,端口默认 3306。TLS 支持 disabled 与系统 CA 的 verify_identity;自定义 CA 和客户端证书尚未支持。部署账号需要访问专用 database、读取实际结构目录、读写应用表及初始化时的建表权限。已有库缺失、为空或结构不匹配时按共同恢复规则拒绝,不重建、不自动迁移。
元数据库备份与恢复
部署管理员在“配置 → 元数据库备份”创建、查看、校验、下载和删除完整元数据库归档。首版支持 SQLite;MySQL 入口明确禁用。备份使用数据库原生完整快照,未来增删表或字段无需修改备份代码;创建期间暂停业务并排空写入,完成后恢复服务。
启动前设置 DATANAVO_BACKUP_KEY_FILE=/secure/datanavo-backup.key。该文件保存 32 字节随机密钥的 64 位十六进制文本,POSIX 权限设为 0600,并与备份分开保管。应用不会生成替代密钥;没有对应密钥就无法解密既有归档。加密 .sdmeta 归档保存在 DATANAVO_DATA_DIR/metadata-backups/archives/;用户账户、权限和库内凭据会随完整库保存,业务源库数据、Agent 密钥文件、聊天/公共产物及部署配置均不在包内。
恢复先校验归档,再由服务器创建独立的 metadata-backups/restored/<operationId>/metadata.sqlite。准备和启用分开确认;启用前必须匹配当前实际结构与领域存储合同,并补齐已知外部依赖。旧结构不匹配时拒绝,不自动迁移或覆盖当前库。启用会撤销旧会话、个人 PAT、注册及重置链接,保留账户密码与角色,随后重新登录。
源元数据库损坏时,以 DATANAVO_METADATA_SETUP=1 npm start 启动本机维护入口,使用部署维护会话读取既有归档;恢复不依赖源业务 Store。首版不接受 Web 上传或任意目标路径。使用外部只读 DATANAVO_METADATA_CONFIG 时,页面不会覆盖部署配置或自动启用。实现边界与实际验证见备份设计。
使用
数据源:选择已安装的 MySQL 连接器,填写稳定 ID、名称、连接、时区及密码。可先测试当前输入,保存时服务会重新探测连接,探测成功才保存。读取源库表清单,勾选表后同步完整结构。密码使用单个输入框;编辑时显示固定掩码,未修改则沿用已保存密码,输入后使用新密码。扩展数据库见数据源驱动。
语义模型:内容页默认展示只读关系画布,点表查看字段和计算列;点击“编辑模型”选择或新建草稿,新建成功后直接进入工作区。先创建空模型,再添加已同步整表;草稿工具栏也提供新建计算列。表节点只显示名称,每张表可自由拖动;未指定位置时自动排列并避开已有节点,拖动后的位置随“保存关系图”提交,重新打开后恢复布局。按住 Shift 拖向另一张表或点击“建立关系”,配置多对一方向、LEFT / INNER 和字段条件;图、维度和指标先加入本地完整草稿,再统一手动保存;发布后才对普通使用生效,内部标识由服务端签发,业务错误单独诊断。结构变化先查看差异并整体确认,再保存映射和比较基线;模型状态标识打开完整报告,可定位问题和重新校验。
查询:选择正常模型,添加维度/指标;日期维度展开后可同时勾选年、年季、年月、年月日、原值,各层独立成列并按完整组合分组,暂不生成小计行。配置统一筛选、排序和每页行数(默认 20 条)。完整有效配置自动查询;只维度返回去重组合,只有指标返回总计。来源歧义提示补选指标。高级 DSL 只读,查询页撤销支持配置、模型切换和清空。
模型关系区可添加 SQL 查询表,在共用编辑器中编写统一 SQL(含 UNION / UNION ALL)或 MySQL 原生查询。按“读取字段 → 应用字段变化 → 应用到模型 → 保存草稿”操作;字段名称、类型和 NULL 信息来自真实数据库且只读,同名保留 ID,删除/改名保留下游失效引用。未探查、过期和业务错误仍可保存/发布,普通查询继续要求模型通过当前完整校验。显式预览默认 20 行、最多 200 行,需要 model.update 与独立的 model.sql.preview,并按当前身份过滤该 SQL 节点的输出行。详细范围、实际检查和未测项见SQL 查询表设计与验证记录。
上下文计算先生成显式语义图,再按固定后端规则安排执行实例和 SQL。同一语句、快照及需求下,已证明相容的成员域、重复计算、同行标量和多输出归约可以共同生产;每个中间转换、条件保护与缺侧总化保持。实现范围及实际结果见上下文查询优化和验证记录。
结果列按维度后接指标的选择顺序排列,表头为业务名称;NULL 显示为 NULL,Decimal 和整数用精确字符串。支持 SUM、AVG、COUNT、COUNT DISTINCT、MIN、MAX。结果支持后端分页,默认每页 20 条,每页上限 200;底部上一页/下一页浏览完整结果,修改数据配置回第一页,翻页可撤销。每页使用独立快照,不额外查询总数。保留上次结果时明确标示正在更新或已与当前配置不同,旧请求响应不能覆盖新配置。
查询顶部可保存完整草稿、另存为新资源,并进入资源管理。正式名称在租户内唯一,只折叠 ASCII 英文大小写;草稿和历史不占名,空输出或未选模型也可保存。字段顺序、筛选、排序、依赖参数实际值及展示设置一并保存,默认值也固定,NULL、空字符串与未填写分别恢复。最新正式查询跟随模型最新发布版,历史查询默认使用发布时正式依赖上下文;每次打开回到第1页,不恢复旧结果。结果未知按原 operationId 核对安全回执,不更换预期修订或载荷重试。详见保存查询设计与资源版本验证。
元数据库保存数据源、原生目录、资源身份、草稿与正式版本、操作回执、内容检查、全局查询配置及身份权限。模型图、维度、指标和保存查询配置属于各自完整定义 JSON,不另存平行分表。结构格式错误拒绝保存,业务错误仍保存并单独诊断;pending / invalid 模型需先校验修复后查询。TLS 支持 disabled 与系统 CA 的 verify_identity;自定义 CA / 客户端证书尚未支持。数据源时区是全部日期维度的唯一配置。
元数据库的共同异步 Store、内置 SQLite/MySQL、声明式配置页与外部包加载已接入;设计与边界见元数据库与插件开发设计,实际结果见本次验证。历史 JSONB 验证不替代本次文本存储验收。
数据源 ID 是应用身份,connection.database 是真实 MySQL 库;源表以 catalog / schema / table 保存,MySQL catalog 固定 def,执行使用已转义的 schema.table。源表同步不创建业务表,也不改写模型结构。详细操作和失败处理见页面流程。
列表和详情可删除数据源或模型;模型画布选中表后可删除表,关系编辑和维度/指标列表也提供删除。删除数据源保留依赖模型;删除模型清除其图、维度、指标及报告,保留引用该模型的已保存查询,重新打开时提示修复;删除表同时清除连接关系,维度与指标保留待修复。表和关系删除确认后仍需保存关系图。数据源删除后的模型可在“模型信息”中改绑;数据源、模型与保存查询标识删除后不可复用。删除边界及版本校验见元数据方案。不匹配的旧元数据库会明确拒绝启动。按开发约定使用独立新库,不自动迁移或清空用户原数据。
计算列只属于模型表,不修改或物化源表。在表节点进入字段管理,使用标签或源码编辑统一/原生表达式、声明结果类型,再加入关系图草稿;参数页签维护模型级标量参数、可空和固定默认值。查询按所选字段的递归依赖显示参数名称和值,修改后 450ms 防抖重查并回到第一页,非法值暂停查询并保留上次结果。统一模式只接受登记函数与本表字段;原生模式只检查模板元素,普通 SQL 在实际执行时反馈错误。两种模式均不预验声明与真实结果是否一致。详细规则见计算列设计及产品验证。
数据源驱动
业务数据库通过安装完整连接器插件扩展,插件包含编译适配、Python 执行适配及固定版本驱动依赖。产品当前随包提供 MySQL 连接器(PyMySQL 1.1.1);其他数据库需要完整适配与对应数据库验收。
部署者在启动前安装插件和依赖,用 DATANAVO_SOURCE_CONNECTORS 指向绝对路径的插件目录清单;重启后,数据源表单只选择已安装的连接器。没有驱动上传、检查、准备环境、源级附件绑定、替换或回收 API。测试与保存使用选中连接器,保存成功才更新源配置和数据库事实。安装合同及示例见连接器设计。已有运行数据不会因退出上传功能被清理。
系统监控与配置
主导航“系统监控”查看查询执行与保存 SQL,“系统配置”管理全局 query 组。每项可独立恢复默认,修改先留草稿,保存后用于下一次新查询,离开前可选择继续编辑、放弃或保存。
默认关闭每次数据库探测,开启查询快照和列检查,遵循实际后端原生排序规则,NULL 位置用数据库默认。此模式下 MySQL 的普通字符串参数直接绑定,让筛选沿用字段的比较规则;金额、日期及显式 CAST 继续按其类型合同处理。SQL 默认不做额外类型转换;开启“严格 SQL 输入/输出类型”后,纯源库普通指标恢复输入/输出类型转换、SUM/AVG 的 38 位精度和 AVG 舍入。计算指标、计算列及显式类型声明仍遵循原有规则。数据源每次保存都会重新探测版本与大小写事实;失败保留旧连接与凭据。关闭查询探测且保存信息缺失时,重新保存数据源或开启探测;查询临时探测不修改源信息。
执行记录固定各组值与 revision,业务 SQL/全部和完整计划/实际轨迹独立筛选。重查保留原配置、SQL、参数并重新核验能力;需要新配置时发起新查询。混合执行允许文本跨后端:“数据库原生排序规则”开启时各阶段使用自身规则,接受分组、关联和排序等结果差异;关闭后使用共同 binary 规则;本地排序保留配置指定的 NULL 顺序。结构变化使用独立最新元数据库,不迁移或清空用户旧库。完整边界见查询规范,实际验证见本轮记录。
模型与保存查询版本
模型和保存查询独立维护草稿与正式历史。首次保存建立资源和草稿,普通使用只跟随最新发布版;有编辑权限即可发布。修改图、维度、指标和查询配置后手动保存,确认后发布。一个资源最多 1 个编辑中草稿,保留最新版及最多 10 个历史;满额后先手动清理。多人修改同一草稿时校验保存修订,冲突后重新读取。历史支持两方比较和整体恢复为草稿,不提供三方合并或选择性撤销发布。放弃的草稿保留一个自然月,删除立即生效。
新建、保存、发布、恢复及删除都返回操作回执。网络中断或结果未知时核对原 operationId,严格原请求重试不会重复提交;不得把没有收到响应当作保存失败。保存和发布允许未完成或有业务错误的内容,实际查询仍要求模型检查通过、当前权限和有效查询。模型预览可选择草稿/正式版本,历史保存查询默认使用发布时的正式依赖上下文。
完整行为与接口见资源版本设计,实际检查及未测边界见开发验证。旧分表结构不能直接打开;按最新实体显式初始化独立新库,原库不迁移或清空。
资源目录与授权
一级“资源”入口按数据源、语义模型、保存查询、共享知识四个固定分类查找对象;模型与查询可在各自分类内创建嵌套文件夹、整理位置,原列表显示同一目录路径。选中资源查看摘要,明确打开后进入原工作区;选中保存查询本身不执行查询。模型内容可展开模型表、维度、普通指标、计算指标与关联知识,内容项与物理引用不复制策略。知识正文里的来源链接打开对应模型、指标或维度。只有查询权限时,可以在知识工作区核对当前获准的只读来源。
打开模型、指标或维度编辑器会按当前权限解析已有知识关联的标题。添加列表的分页不影响已有标题,加载失败时可重新读取。
租户管理员从“管理 → 资源授权”配置角色及类型动作,支持动态继承、整份独立策略、空策略、恢复继承、批量影响预览、同分类移动和按用户查看来源。角色页提供同一策略的反向入口。对象管理动作按树策略核验,创建同时核验功能资格、目标容器与创建后的编辑资格;创建人不隐式获权。查询在 SQL 简化后、方言输出前检查模型资格和实际数据/原生输出依赖,不再逐指标叠加 ACL。目录、分析、公共 BI 和 Agent 复用该规则;PAT 只限制接口能力,角色与资源树策略决定当前业务权限;凭据页不再选择资源范围。管理员 SQL 重放保留管理与执行环境检查,不重新检查任务资源或读取已删除模型。实际覆盖见查询授权验证。
源表/字段以连续身份登记,完整同步确认缺失后退役,同名再出现取得新身份。新增共同实体要求显式初始化独立新库,旧库不转换、不清空。合同见资源树与授权设计,实际结果和未测项见产品验证。
独立 API 自动化测试
通过 DATANAVO_API_CONFIG 提供仓库外私有部署配置,再执行 npm run test:api。测试使用 Playwright APIRequestContext,不启动浏览器;默认 4 个 worker,同一文件内的用例也可并发,单次请求、完整收集和单案默认及最大均为两分钟;普通产品 API/Worker 请求的默认期限与配置上限同为两分钟。复用已有模型,以固定完整数据判断 /api/queries 结果,另有三个公共产物冒烟。业务数据生成与 MySQL 导入独立执行,凭据、大型数据与 JSON/HTML/JUnit 报告均保存在仓库外。
准备步骤、配置与目标覆盖见测试模块说明。已导入人工边界、TPC-H SF=0.01 与 TPC-DS SF=1;TPC-H 全部 22 条具备固定请求与完整预期,此前 API 全量实测为 10 通过/12 失败,完整清单 54 条为 40 通过/14 失败。历史失败原因、Q13 的合法表达限制和未测项见TPC-H 验证,初次导入证据见首期验证。计算 DSL 补齐轮的 Q11/Q17 直接 SQL 复验及剩余超时见原独立验收;后续多事实实现的 Q22 精确通过、Q9/Q20 共同维度拒绝见多事实限定复验。这两轮均未重跑完整 API 清单。
第二期查询专项已接入首批五个固定包、身份/授权与导入发布准备,三条准备试点和 PREP-01–09 的入口见模块说明 §5。其余查询专项待逐案实施。前置资源导入导出已接入“资源”页的“导出资源/导入资源”:选择正式、历史版本或已保存草稿,下载 .sdresources.json;导入时显式绑定目标源、物理表、主体/属性和复用对象,检查后将新资源原子写入草稿。SQL 结构在目标环境重新核实,导入不自动发布;未知结果按原 operationId 核对回执。目标源、秘密与授权独立准备。PAT 还需 resource.export/resource.import 接口能力。新增成功回执表要求显式初始化独立新库,旧库不迁移或清空;实际检查与未测边界单独记录。独立原型仍为模拟预览。
合成数据示例与验证
本地快速试用使用下方付款记录夹具,自动创建模型并比对两道 MCP 查询的独立预期。本节其余命令用于开发回归和手动建模。
examples/order-model.sql 是用于建立订单示例模型的五表数据集,包含 16 位顾客、18 件商品、12 个分类、200 笔订单和 600 条明细。关联字段同名且统一使用 BIGINT UNSIGNED,不建外键;保留未下单顾客和未售出商品。订单仅保存运费,商品金额保留在明细中。文件末尾附记录数和数据自洽检查,导入已创建的独立空库:
mysql --default-character-set=utf8mb4 --host=127.0.0.1 --port=33385 --user=root -p datanavo_order_demo < examples/order-model.sqlexamples/fixture.sql 使用完全合成的数据,建立独立 datanavo_fixture 测试库,覆盖重复业务 ID、NULL、精确小数、有符号 64 位整数、微秒及时间边界、聚合溢出及 205 组分页数据。普通指标不要求全局粒度或主键字段。
在自己的测试 MySQL 导入 fixture,并创建仅对测试库有 SELECT 权限的 reader,密码自行设置:
mysql --host=127.0.0.1 --port=33385 --user=root -p < examples/fixture.sql在数据源表单填写真实测试连接和密码,读取、勾选并同步 fixture 表;在模型中添加整表、定义维度和六种普通指标,再查询。最新 JSON 示例为 source.json、model.json、dimensions.json、metrics.json 与 query.json。其中 query.json 是管理端 /api/queries 的已绑定 ID 载荷;公共 MCP/CLI 使用名称作者 DSL。模型示例中的 sourceTableId 占位值须换成同步返回的源表 ID,不是可直接写入的物理表名;独立人工预期为 examples/expected.json。
npm run typecheck
npm test
npm run test:python
npm run test:metadata -- --plugin=sqlite
# MySQL 元数据库使用独立测试库和部署配置:
# DATANAVO_TEST_METADATA_CONFIG=/path/metadata-test.json npm run test:metadata -- --plugin=mysql
npm run build
# 已导入独立 fixture 并配置 reader 后:
DATANAVO_TEST_PASSWORD='测试账号密码' npm run test:integration集成环境默认 127.0.0.1:33385,可用 DATANAVO_TEST_HOST、DATANAVO_TEST_PORT 调整。也支持 DATANAVO_TEST_PASSWORD_FILE 指向包含 {"password":"..."} 的本地 JSON,避免密码进入 shell 历史。DATANAVO_TEST_ADMIN_SOCKET 仅指向独立合成测试实例的本地 socket,供测试观察活动连接/只读事务及修改 drift_values 夹具验证结构漂移;不赋予产品查询账号额外权限,不指向业务实例。缺少密码或该观察入口时,相应用例明确跳过,不视为真实通过;元数据库使用独立临时目录,默认 data/ 不写入测试配置。普通预览不创建结果文件。
维度、指标的可用范围由本人当前角色与资源树策略控制,查询检查简化后实际使用的数据/输出及隐藏条件、排序、时间和计算依赖;消费目录仅投影可用内容。PAT 入口只选择接口能力,不保存维度/指标或其他资源范围。授权与模型内容版本分离;已有不匹配的元数据库明确拒绝,不自动迁移或清空。当前执行与未测项见查询资源验证,旧子对象授权方案的历史证据见子对象权限产品验证。
实现边界
React / Vite,Node HTTP / MikroORM 元数据库插件,TS 编译,Python / PyMySQL 唯一访问业务数据库;连接器统一原生类型映射,页面消费共享的草稿评估。查询、断言和计算列使用同一套统一 SQL AST。
查询编译统一为 SQL 计划、准备、授权和渲染阶段;单事实同粒度普通指标共用聚合,适用的简单计算指标在聚合后投影,保留类型、NULL 和中间转换。计算指标除法使用显式原生数值策略压缩 SQL,普通计算列精确合同不变。源库负责读取与基础缩减,透明根窗口与计算多事实组合按固定规则进入 DuckDB;单事实标量按自身依赖保留源数值运算,独立事实展示不改变它的数值位置。不满足 effects、类型、键语义或本地驱动源读取边界时明确拒绝,不隐式改为全源运算。透明同粒度路径已接入独立语义/执行计划,复杂上下文的完整阶段迁移仍待完成。本期没有能力驱动自动选址;适用范围、独立结果及性能证据见查询计划优化验证。
业务 SQL renderer 按本次连接返回的 MySQL 版本与
lower_case_table_names检查名称,当前接受 8.0.21 及后续 8.0 补丁版本、8.4.x、9.7.x、26.7.x 和 26.10.x;其他版本明确拒绝。非 ASCII 结构化标识符的目标等价规则尚未实现,会报告不支持;Unicode 字符串值仍可使用。元数据库插件的版本要求另见其配置说明。同源多表仅沿 many → one 使用 LEFT / INNER,禁止有向环和多路径;共享维度多事实已按专项方案接入,各事实独立聚合后按实际完整维度组合并集对齐,所有输出/过滤/计算维度须对每个事实有效。开发专项与独立验收分项记录在验证报告;不扩展 DSL,不支持查询结果集二次加工。不检测实际目标唯一性,不为重复匹配自动去重指标。
Worker 支持多个在途调用、独立查询连接/事务和有界预算;超时及断开按请求处理。故障自动重建 Worker,失败或结果未知的 SQL 不自动重跑。
执行核对真实结构、类型和 NULL 属性,在 UTC 会话只读快照执行数值断言和结果 SQL;业务表要求 InnoDB 基础表。有限预览在内存按 schema 校验,空结果保留列,清理错误不覆盖结果。
计算指标已接入 M0–M3 核心执行:标量、上下文/成员、六类嵌套归约、完整期间与归约交叉、嵌套期间及分层排名与窗口,支持必要的源 → Arrow → DuckDB 单向混合。设置中的“查询执行”提供简单本地记录、SQL/绑定/来源和完整包重查。复杂组合及未测边界见执行验证;尚未提供通用独立 SQL 工作台和跨源查询;Agent、产物图表与导出按上文独立合同使用。登录、资源授权及模型/保存查询发布分别按对应合同实现。
2026-10-13 批次完成 TS 52/52、Python 28/28、真实集成 12/12(零跳过)、生产构建/启动及三个页面 1280/390 px 检查,环境、命令和未测边界见三模块实现验证记录。TLS verify_identity、最低运行版本、其他平台、大图和真实 SQL 故障丢响应未测。2026-10-14 删除能力的 65 项单元、3 项 HTTP/SQLite 和产品页面检查见删除复验。AVG 与默认 20 条分页的 68 项 TS、30 项 Python、16 项真实集成及产品/原型检查见本次验证。分项完成情况见功能状态表。产品范围见产品设计,精确值与执行见查询规范,文档入口见文档目录。
UI 设计与预览
设计系统是唯一视觉规范,产品与方案 A 原型共享公共组件源码和视觉令牌;方案已确认,产品和原型的独立检查结果见本轮验证 §3。
python3 prototypes/module-design/preview.py元数据库备份原型(已确认),结构变化自动进入完整备份、结构匹配后恢复到独立目标;设计与实现,正式产品支持 SQLite,独立目标由服务器自动生成
AI 助手与 Agent 运行原型(已确认),会话、五类卡片、附件与结果生命周期、部署配置及异常场景;原型仅合成演示,正式产品检查见Agent 产品验证
F25 资源树与资源授权原型(已授权接入),资源优先、动态继承、独立策略、批量/移动与来源检查;原型说明,原型使用合成数据,产品配置阶段已接入,执行边界见专项验证
身份与国际化界面改版原型(已确认并接入),角色分组权限与模型授权矩阵、用户/注册/账户流程及紧凑页头;正式页面与 F25 资源目录已分别接入
计算指标与调用解释原型,完整交互原型;产品定义编辑与静态分析已接入,属性继续占位
系统监控与查询执行原型,详情默认业务 SQL,可切换全部步骤;记录与 SQL 重查均为合成演示
全局系统配置原型,六项查询策略(含默认关闭的严格 SQL 类型)、逐项恢复默认值与能力拒绝;原型已确认,正式产品已接入,原型仍仅用合成演示
表关系画布的自由拖动、缺省位置避让及坐标保存恢复检查见位置复验。
只需 Python 3,Ctrl+C 停止;端口占用可加 --port 4312,见原型 README。原型不连接数据库,不能代替产品或持久化验收。功能与数据规则分别见页面流程和元数据方案。
正式产品提供简体中文与 English,页头语言入口即时切换;首次访问跟随浏览器,不支持时回退中文。偏好只在当前浏览器同源存储并同步标签页,不进入服务器配置;语言切换保留草稿、编辑器及查询结果。业务名称、SQL、DSL 和精确值不翻译。db:init、logs 支持 --lang zh-CN|en,未指定时按 LC_ALL → LC_MESSAGES → LANG → 中文 解析,C/POSIX 为英文;JSON 日志保持机器合同。接口、插件与消息边界见国际化设计,本次实际检查与未测项见产品验证。
开发约定
从 AGENTS.md 进入,开发、验证和提交遵循开发流程,目录与命名遵循仓库约定,按任务选择文档阅读路线。所有自维护文档和 README 暂时只维护一个简体中文版,见文档约定。
每次开发任务默认遵守统一日志与异常处理规范及其完成门,无需重复提出。规范定义安全错误出口、错误分类、日志脱敏、请求关联和验收标准;实现与验收状态见功能状态表 N13。
语义查询引擎架构升级设计记录已确认的职责边界、三个内部方法和提交后固定快照规则,以及首版范围和待讨论事项。首版本地模块已接入:宿主捕获数据,引擎协调模型校验、草稿分析和完整查询,运行时登记请求并负责实际收尾。接收后编辑或删除元数据不改变在途查询;新请求按最新状态检查。实际检查及未测边界见引擎验证。
@datanavo/unified-sql 已作为同仓库 npm workspace 接入查询、数值断言、统一与原生计算列,包含 AST、统一 SQL parser、逻辑引用绑定、类型分析、MySQL renderer 和独立 transport。根 npm run generate 维护包内 Peggy 生成源码;npm run build:sql 单独构建该包,生产构建与测试入口会先构建它。接口与职责见统一 SQL 设计。包默认树深度上限为 64;宿主对生成的完整计划设置 512,以容纳产品最多 64 层计算列依赖形成的派生查询。业务语句在物理绑定后显式调用集中简化,覆盖 R1–R7、必填 qualifier 与 OutputRef;规则与未测项见简化器设计及实现验证。四项增强已接入局部屏障及 CTE 删除/绕过/有界内联,全部规则共享无 SQL 输出的字节/绑定预算预检;不承诺数据库性能收益。
计算列与 SQL 表达式编辑器设计已按确认原型接入正式产品:表级计算列、共用 CodeMirror 标签/源码编辑器、模型参数与查询赋值。统一 SQL 拒绝未登记函数,原生表达式保持不透明,用户属性已按行权限设计接入可信定义与取值;计算指标定义编辑与静态分析单列下文,模型内完整查询另通过 SQL 查询表场景接入,通用独立 SQL 工作台仍不在范围内。实际自动化、MySQL 与页面检查及未测边界见产品验证。原型业务执行仍为合成演示。
计算指标设计的文法与业务求值边界保持。产品“语义模型 → 指标”可编辑计算表达式、业务声明、只读分析,随后随模型完整草稿保存和发布;查询已开放 M1–M3 核心能力,草稿分析和直接 API 复用同一规划器按实际调用检查。精确小数常量和中间表达式使用统一 SQL 类型推导,适用于输出、重算及隐藏条件。本地 TIMESTAMP 的显式 RANGE 可混用 DATE/TIMESTAMP 端点,保留微秒;其他时间矩阵见执行验证。CASE 动态需求、完整根域窗口、成员身份和同快照读取继续生效;窗口依赖按完整根域分层,嵌套上下文逐层挂回;需要请求回传及未知原生捕获的组合按具体原因拒绝。范围与实际证据见执行验证和功能状态 F12,历史定义编辑验收单独保留。
语义查询计划与 SQL 执行设计已接入实施路线的 M0–M3 核心范围。SQL 采用允许丢失的尽力记录,数值允许后端原生差异;业务计算全部使用 SQL,不进行业务值回灌。DuckDB 依赖锁定正式版 2.0.0。在“设置 → 查询执行”查看最近记录、固定输入、SQL/类型绑定、基本来源与实际事件;获授权的完整包可从头重查并关联新记录,不重新编译当前模型;要求部署管理员、system.replay、当前业务租户及源身份/修订匹配;不要求原模型或内容仍存在,也不重新核对任务资源权限。记录位于 DATANAVO_DATA_DIR/query-executions/,不保存密码,默认不自动清理,不能当作脱敏诊断日志分发;缺包/坏包或前提失配不可重查。历史严格精度探针不作为当前开放门,真实边界见执行验证。
行权限、用户组与用户属性已接入正式产品:用户管理作用域下的“用户组”“用户属性”分别维护人员归集、定义与直接赋值;模型草稿的“行权限”按表编辑快捷/统一/原生条件,应用后仍需保存草稿并发布。匹配规则固定 OR,无匹配时全部可见;管理员同样参与匹配。查询使用所选模型版本规则和动作开始时的当前组/属性,历史 SQL 重放沿用原 SQL 与绑定。新增元数据结构需要显式建立独立新库,已有不匹配库不会自动转换或清空。实际验证和未测边界见行权限产品验证。
开源许可证
项目自有代码采用 Apache License 2.0,允许企业内部使用、修改、分发和商业使用,须遵守许可证中的声明保留等条件。第三方依赖、嵌入资源和已有第三方文件仍按各自许可证授权,根许可证不替代它们的条款。具体来源和许可证位置见第三方声明。后续开发与贡献遵守开源开发与交付要求。
当前内置元数据库为 SQLite 和 MySQL,业务数据源为 MySQL。达梦适配及 dmdb 依赖已移除;旧验收记录仅保留历史证据,不代表当前支持。独立 CLI 安装包包含同一许可证。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Governed BI MCP. Ask questions of live company data and list workspace sources via OAuth.
Securely query and analyze business data, dashboards, projections, alerts, and knowledge.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI applications to discover and connect to Power BI Desktop semantic models, inspect tables, columns, and measures, and validate or execute DAX queries through MCP.-
- FlicenseAqualityCmaintenanceEnables AI agents to discover and query enterprise knowledge documents and business metrics through standardized MCP tools, supporting retrieval, structured sales/order analysis, anomaly scanning, and data lineage lookups.12-
- AlicenseAqualityBmaintenanceEnables agents to query governed metrics through MCP, including describing metrics, running deterministic SQL against a warehouse, explaining join path preferences, and searching semantically ambiguous terms.8MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to retrieve permission-filtered document knowledge across organizations and knowledge bases, and to identify and expand business terms and typed object relationships through a unified MCP interface.MIT