Databend Semantic Analytics

面向 Databend 的 AI 驱动、可治理、可观测语义查询平台。让 AI 问数变得可信：以语义层为地基，把自然语言安全地转化为 Databend 上的真实结果。

核心分工：

LLM            理解自然语言
本平台          语义约束 · 治理 · 安全 · 可观测
Cube Compiler  把 Semantic Query 编译为 Databend SQL
Databend       承载复杂 SQL 的分析计算与真实执行

仓库名 databend-semantic-analytics，UI 展示名 Semantic Analytics。

为什么用 Databend 承载

AI 问数会带来大量临时、长尾、跨实体的查询，编译出的 SQL 常含多表 JOIN、大范围扫描、高基数聚合和时间计算，资源消耗远高于固定报表。这类分析负载适合 Databend：列式扫描 + 数据裁剪、分布式并行、存算分离（可为 AI 问数的突发负载独立扩容），让语义层和 LLM 专注“生成受治理的查询”，重计算交给 Databend。

高频稳定的问题应沉淀为 Certified Query / 认证 SQL；生产环境可用 Cube Server 模式的缓存与 Pre-aggregations 进一步加速。

工作原理

业务问题
   │
   ├─ 命中认证查询 ────────────→ Certified Query / Certified SQL
   │
   ├─ 触发治理护栏 ────────────→ 拒绝 + 解释（如把订单金额当 GMV/营收）
   │
   └─ 交给 LLM 语义规划器
            ├─ 单一粒度 ──────→ Dynamic Cube Query
            ├─ 父 Top N→子明细 → Semantic Workflow（两阶段）
            └─ 无安全计划 ────→ 拒绝 / 确定性回退

每个语义阶段 → Cube 编译为 Databend SQL → SQL Safety 校验 → Databend 执行 → 结果 + 可观测日志

四种查询策略：

• Certified Query — 高频问题的稳定查询计划
• Dynamic Cube — LLM 从公开语义成员构造受约束的单阶段查询（含 ungrouped 明细）
• Semantic Workflow — 单个查询不足时，编排两个受治理阶段（父实体 Top N → 注入 Keys 展开子明细）
• Governed SQL — Policy 控制用户自由 SQL 是否可执行

治理护栏（确定性、不依赖 LLM）：问题命中语义模型 prohibited_interpretations 时在编译前拦截并解释原因，不会向 Databend 发送查询。

主要功能

• AI 语义查询工作台：自然语言查询 TPC-H 业务数据；认证查询优先，其次动态 Cube Query 与两阶段 Workflow；展示查询理解、Cube Query、Databend SQL、耗时与真实结果；支持校验、EXPLAIN、真实执行；LLM 不可用时确定性回退。
• 可视化语义层：浏览实体 / 度量 / 维度 / 关系，查看业务名、描述、同义词、枚举、治理属性与认证查询引用，实时组装 Runtime Manifest。
• Semantic Model 管理：模块化 YAML 在线查看 / 编辑 / 校验 / 发布，发布前完整校验 + Cube 编译，热重载无需重启；可从 Databend 表生成实体草稿，LLM 仅增强业务元数据（不改表源、SQL、类型、聚合、主键、权限）。
• 可观测：规划与执行阶段的 JSONL 日志（query / llm / modeler）。

已含认证查询：S1–S7（业务）+ Q1 / Q6 / Q21（TPC-H）。

快速开始

环境：Node.js 20 或 22 LTS（Embedded 模式依赖 @cubejs-backend/native 预编译二进制，仅 LTS 版本可用）、可访问的 Databend、已加载 TPC-H 的 tpch_100 库、一个只读用户。LLM 可选。

git clone https://github.com/wubx/databend-semantic-analytics.git
cd databend-semantic-analytics
npm install          # 无需克隆或构建 Cube 源码
cp .env.example .env # 填入 DATABEND_DSN
npm start            # http://localhost:4100

最小配置：

SEMANTIC_GATEWAY=embedded
DATABEND_DSN=databend://readonly_user:password@databend-host:8000/tpch_100?sslmode=disable
PORT=4100
AI_ENABLED=false

检查运行状态：curl http://localhost:4100/api/health，api / cube / databend 三项应为 true。若 cube 为 false，确认用的是 Node 20/22 LTS；若 databend 为 false，检查 DSN、网络、TLS、权限与 tpch_100。

运行模式

模式	说明
Embedded（默认，推荐本地 Demo）	Cube Schema Compiler + 内置 DatabendQuery 方言直接跑在 Node 进程内，npm install 即可，无需 Cube Server。不含 Cube 的缓存 / Pre-aggregations / Security Context。
Cube Server	每个语义阶段经 Cube HTTP API 执行，适合需要完整 Cube Runtime（缓存、预聚合、运行时访问策略）的场景。需从 wubx/cube 的 feat/databend-driver 分支构建 Cube Server。

两阶段 Workflow 始终由本平台的应用层编排。详见 docs/embedded-cube-compiler.md。

客户演示模式

默认 BUILDER_MODE=false：界面只突出「自然语言 → 语义计划 → Databend SQL → 真实结果」，隐藏 YAML 编辑、模型生成等建模 UI（查询路由仍完整工作）。维护建模时设 BUILDER_MODE=true。

常用配置

变量	默认	说明
SEMANTIC_GATEWAY	embedded	embedded 或 cube-server
DATABEND_DSN	—	Databend 连接串，建议只读用户
PORT / HOST	4100 / 0.0.0.0	HTTP 端口 / 监听地址（默认允许局域网）
AI_ENABLED	false	AI（LLM 规划、摘要、模型增强）的启动默认；运行时可用页头 AI 开关临时切换
MODELER_PUBLISH_ENABLED	false	允许写入 / 删除语义源文件
CERTIFIED_SQL_PUBLISH_ENABLED	false	允许维护认证 SQL
RESULT_ROW_LIMIT	500	单次返回最大行数

启用 LLM 需配置 AI_BASE_URL / AI_API_KEY / AI_MODEL（OpenAI 兼容）。LLM 仅做受约束的 Cube Query 规划、结果摘要和元数据增强，不直接生成或执行 SQL，其输出仍经本地成员 / 类型 / 枚举 / 粒度 / Limit 校验。完整变量见 .env.example。

常用命令

npm test              # 单元与回归测试
npm run build:semantic # 组装运行时 Manifest 到 generated/
npm run verify:runtime # 连真实 Databend 编译并执行 S1–S7
npm run validate:meta  # 校验运行时 Cube Metadata
npm run report:queries # 输出认证查询报告

安全边界

这是一个 Demo，没有登录、用户隔离、TLS、CSRF 与接口级授权，不要直接暴露到公网。建议：

• 始终使用只读 Databend 账户；不提交 .env / DSN / Token
• SQL Safety 只允许单条只读查询并限制访问 tpch_100
• LLM 不直接生成 SQL；模型发布需显式开启并经完整校验
• 共享演示时保持 MODELER_PUBLISH_ENABLED=false，限制防火墙来源
• 需要多人长期使用时，前置带认证 + HTTPS 的反向代理，并用 Cube Server 承担运行时访问治理

semantic/policy.yaml 属声明性治理元数据，最终安全边界以服务端成员校验、SQL Safety、只读账号和 Cube Runtime 配置为准。

项目结构

public/                 无框架 Web UI
semantic/               模块化语义源（model / entities / relationships / verified-queries / certified-sql / policy）
src/
  server.js             Express API 与静态站点
  planner.js            查询规划与路由
  governance-guard.js   确定性治理护栏
  semantic-gateway/     Embedded / Cube Server Gateway
  cube-dialect/         内置 Databend SQL 方言
  compiler.js           Cube Model 与 Catalog 编译
  sql-safety.js         只读 SQL 安全校验
test/                   单元与回归测试
docs/                   设计与运行文档

进一步阅读

• Embedded Cube Compiler 模式
• Semantic Manifest 维护设计
• 验证和回归测试 · 查询可观测日志
• 自然语言查询验证手册
• Snowflake 与 Cube 语义层设计对比 · Snowflake Semantic View 字段参考
• 项目计划与验收条件

License

Apache-2.0