新思路，圖數據庫加持的Text2SQL神器

大家好，我是 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 登錄：企業級的認證體系，不是玩具項目

既然都是 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

這是 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 協議）

當然也不是完美的：

1. LLM 選擇有限：目前只支持 Azure OpenAI 和 OpenAI 直連，不像 Wren AI 那樣支持 Ollama 本地模型，對數據安全要求高的團隊不太友好

2. 不直連數據庫：需要手動上傳 Schema（JSON 或文件），不能像 Wren AI 那樣直接對接 PostgreSQL/MySQL

3. 社區規模較小：336 Star，相比 Wren AI 的 13.3k Star，生態還在早期

4. 缺少可視化報表：只返回 SQL 和查詢結果，沒有自動生成圖表的功能

QueryWeaver 給 Text-to-SQL 賽道帶來了一個有意思的思路：用圖數據庫來理解數據庫 Schema。這和 Wren AI 的"語義層"路線形成了有趣的互補——前者自動化程度高、開箱即用，后者精度更高、可定制性更強。

最讓我看好的是它的MCP 原生支持。Text-to-SQL 工具不應該是一個獨立的 Web 應用，而應該融入到開發者的工作流中。QueryWeaver 做到了這一點。

FalkorDB 作為背后的圖數據庫公司，在技術底蘊上是沒問題的。如果后續能支持更多 LLM、直連更多數據源，這個項目還是很有潛力的。

官方鏈接匯總：

• GitHub：https://github.com/FalkorDB/QueryWeaver

• 在線體驗：https://app.queryweaver.ai

• FalkorDB 文檔：https://docs.falkordb.com/

• FalkorDB 官網：https://falkordb.com

• Swagger API 文檔：https://app.queryweaver.ai/docs

• Discord 社區：https://discord.gg/b32KEzMzce

制作不易，如果這篇文章覺得對你有用，可否點個關注。給我個三連擊：點贊、轉發和在看。若可以再給我加個，謝謝你看我的文章，我們下篇再見！