新思路，图数据库加持的Text2SQL神器|json|key|schema|sql|工作流|数据源

大家好，我是 Ai 学习的老章

关于 Text-to-SQL，我之前写过：

那篇介绍的是 Wren AI，它的核心思路是在数据库上加一层"语义层"。今天要聊的QueryWeaver，走了另一条路——用图数据库来理解数据库 Schema，思路完全不同，但同样精彩。

先聊聊背景：FalkorDB 是谁？

在聊 QueryWeaver 之前，得先说说它背后的公司FalkorDB。

FalkorDB 是一家专注于图数据库的公司，官方定位是 **"Ultra-fast, Multi-tenant Graph Database Powering GenAI"**——超快的、多租户的图数据库，专为 GenAI 而生。

它的核心产品是同名的 FalkorDB 图数据库，主要特点：

采用属性图模型（Property Graph Model），支持 OpenCypher 查询语言
性能碾压级别：官方 benchmark 显示延迟比 Neo4j 快496 倍，内存占用低6 倍
支持全文搜索、向量相似度搜索、范围索引三种索引类型
内置GraphRAG SDK，直接支持图检索增强生成
应用场景覆盖 GraphRAG、Agentic AI、Chatbot、欺诈检测、安全图谱等

简单说，FalkorDB 的核心竞争力就是快、省内存、多租户。在图数据库赛道里，Neo4j 是老大哥没错，但 FalkorDB 在性能上的优势确实惊人。

所以你可以理解，当 FalkorDB 团队做 Text-to-SQL 工具的时候，他们天然会想：能不能用图来理解数据库结构？QueryWeaver 就这么来了。

简介

QueryWeaver是 FalkorDB 推出的一个开源 Text-to-SQL 工具，核心定位很清晰：把自然语言问题转换成 SQL 查询，用图数据库来理解数据库 Schema。

QueryWeaver 产品界面演示

和其他 Text-to-SQL 工具最大的不同在于——它的底层是图驱动的 Schema 理解（graph-powered schema understanding）。

什么意思？传统 Text-to-SQL 工具是把表结构塞进 prompt，让 LLM 硬猜。QueryWeaver 是先把你的数据库 Schema 解析成一个图——表是节点，外键关系是边——然后通过图遍历来理解表与表之间的关系。

这思路其实很聪明。数据库本来就是关系模型，用图来表示表之间的关系，比把 Schema 平铺成文本给 LLM 要直观得多。LLM 在理解多表 JOIN 时更不容易出错。

核心功能与特点：

Graph-powered Schema 理解：用 FalkorDB 图数据库存储和理解数据库 Schema 关系，自然语言查询时通过图遍历定位相关表
REST API + MCP 双接口：既有传统的 RESTful API，也支持 MCP（Model Context Protocol）协议，可以被 Claude、Cursor 等 AI 工具直接调用
多 LLM 支持：默认用 Azure OpenAI，也支持 OpenAI 直连。Embedding 用text-embedding-ada-002，Completion 用gpt-4.1
对话记忆：每个用户的对话上下文存在 FalkorDB 中，支持多轮对话追问，不会"翻脸不认人"
流式响应：Text-to-SQL 的生成过程是流式返回的，包含中间推理步骤，你能看到它"思考"的过程
Google/GitHub OAuth 登录：企业级的认证体系，不是玩具项目

和 Wren AI 比较

既然都是 Text-to-SQL，免不了和我之前介绍的 Wren AI 做个对比：

对比维度

QueryWeaver

Wren AI

核心思路

图数据库理解 Schema 关系

语义层（Semantic Layer）抽象

Schema 理解

自动构建表关系图，图遍历定位

需手动建模语义层

上手门槛

Docker 一行启动，导入 Schema 即用

需要花时间建立语义模型

MCP 支持

✅ 原生支持

数据源

通过 Schema 导入，不直连数据库

直连 PostgreSQL、MySQL、Snowflake 等

LLM

Azure OpenAI / OpenAI

支持多家（OpenAI、Gemini、Claude、Ollama）

SQL 验证

流式返回含推理过程

内置 SQL 执行验证

可视化

图形化 Schema 展示

自动生成图表和报告

GitHub Stars

336 ⭐

13.3k ⭐

两者各有所长。QueryWeaver 的优势在于开箱即用和 MCP 原生支持——上传 Schema 就能开始问问题，不需要花时间建模。而且 MCP 支持意味着你可以在 Claude、Cursor 等 AI IDE 中直接用它查数据库，这个体验是很超前的。

Wren AI 的优势在于成熟度和可配置性——语义层虽然建模麻烦，但一旦建好，可以带来更精确的 SQL 生成，对企业级场景更友好。

安装

QueryWeaver 的安装非常简单，Docker 一行搞定：

docker run -p 5000:5000 -it falkordb/queryweaver

启动完成后访问 http://localhost:5000 就能看到界面了。

如果你想配置 API Key，推荐用.env文件：

cp .env.example .env
# 编辑 .env 设置你的配置
docker run -p 5000:5000 --env-file .env falkordb/queryweaver

也可以通过环境变量直接传：

# 使用 OpenAI
docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e OPENAI_API_KEY=your_openai_api_key \
  falkordb/queryweaver


 # 使用 Azure OpenAI
docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e AZURE_API_KEY=your_azure_api_key \
  -e AZURE_API_BASE=https://your-resource.openai.azure.com/ \
  -e AZURE_API_VERSION=2024-12-01-preview \
  falkordb/queryweaver

MCP 集成：AI IDE 直接查数据库

这是 QueryWeaver 最让我兴奋的功能。它内置了 MCP Server，提供了 4 个 Text-to-SQL 相关的操作：

list_databases：列出可用数据库
connect_database：连接到指定数据库
database_schema：获取数据库 Schema
query_database：执行自然语言查询

配置也很简单，在你的 MCP 客户端配置文件中加入：

{
  "servers": {
    "queryweaver": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  },
  "inputs": []
}

想象一下这个场景：你在 Claude Desktop 或 Cursor 里写代码，突然想查一下"上个月有多少新注册用户"，直接在 AI 对话里问就行，QueryWeaver 作为 MCP Server 在后台帮你把自然语言翻译成 SQL 并返回结果。

这才是 Text-to-SQL 的正确打开方式——不是一个单独的 Web 界面，而是融入到你的工作流里。

REST API 使用

QueryWeaver 也提供了完整的 REST API，适合集成到自己的产品中：

import requests
import json

 # 列出可用的图（Schema）
resp = requests.get(
    'https://app.queryweaver.ai/graphs',
    headers={'Authorization': f'Bearer {TOKEN}'}
)
print(resp.json())

 # 自然语言查询（流式）
url = 'https://app.queryweaver.ai/graphs/my_database'
headers = {
    'Authorization': f'Bearer {TOKEN}',
    'Content-Type': 'application/json'
}
with requests.post(
    url,
    headers=headers,
    json={"chat": ["上个月有多少新注册用户？"]},
    stream=True
) as r:
    boundary = '|||FALKORDB_MESSAGE_BOUNDARY|||'
    buffer = ''
    for chunk in r.iter_content(decode_unicode=True, chunk_size=1024):
        buffer += chunk
        while boundary in buffer:
            part, buffer = buffer.split(boundary, 1)
            ifnot part.strip():
                continue
            obj = json.loads(part)
            print('STREAM:', obj)

流式响应会包含中间推理步骤和最终 SQL，前端可以很好地展示"AI 正在思考"的过程。

源码开发

如果你想从源码运行或参与开发：

# 克隆仓库
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver


 # 一键安装和启动
make install
make run-dev

前置条件：Python 3.12+、pipenv、Node.js（前端是 React + Vite）、以及一个 FalkorDB 实例。

项目结构很清晰：

api/— FastAPI 后端
app/— React + Vite 前端
tests/— 单元测试和 E2E 测试

对话记忆

QueryWeaver 有个贴心的设计：对话记忆。每个用户的会话上下文都存在 FalkorDB 中，默认永久保存。如果你担心占用空间，可以设置 TTL 自动清理：

# 1 周无活动后自动清理记忆
MEMORY_TTL_SECONDS=604800

只要用户还在互动，TTL 就会刷新。这样活跃用户不受影响，休眠用户的数据自动回收。

它适合谁？

数据分析师：上传 Schema 就能自然语言问数据，不用手写 SQL
AI 应用开发者：通过 REST API 或 MCP 协议把 Text-to-SQL 能力集成到自己的产品
Claude/Cursor 用户：通过 MCP 直接在 AI IDE 中查数据库
技术团队：需要一个开源可控的 Text-to-SQL 方案（AGPL 协议）

不足

当然也不是完美的：

LLM 选择有限：目前只支持 Azure OpenAI 和 OpenAI 直连，不像 Wren AI 那样支持 Ollama 本地模型，对数据安全要求高的团队不太友好
不直连数据库：需要手动上传 Schema（JSON 或文件），不能像 Wren AI 那样直接对接 PostgreSQL/MySQL
社区规模较小：336 Star，相比 Wren AI 的 13.3k Star，生态还在早期
缺少可视化报表：只返回 SQL 和查询结果，没有自动生成图表的功能

总结

QueryWeaver 给 Text-to-SQL 赛道带来了一个有意思的思路：用图数据库来理解数据库 Schema。这和 Wren AI 的"语义层"路线形成了有趣的互补——前者自动化程度高、开箱即用，后者精度更高、可定制性更强。

最让我看好的是它的MCP 原生支持。Text-to-SQL 工具不应该是一个独立的 Web 应用，而应该融入到开发者的工作流中。QueryWeaver 做到了这一点。

FalkorDB 作为背后的图数据库公司，在技术底蕴上是没问题的。如果后续能支持更多 LLM、直连更多数据源，这个项目还是很有潜力的。

官方链接汇总：