Query Weaver

QueryWeaver (Text2SQL)

REST API·MCP·图形电源

QueryWeaver是一个 开源Text2SQL 使用以下命令将普通英语问题转换为SQL的工具 基于图的模式理解。它可以帮助您向数据库提出自然语言问题，并返回SQL和结果。

连接并提问： 

 ](https://hub.docker.com/r/falkordb/queryweaver/)  

开始使用

码头工人

💡 建议用于评估目的（不需要本地Python或Node）

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

启动：http://localhost:5000

______________________________________________________________________

使用.env文件（推荐）

创建本地 .env 通过复制 .env.example 并将其传递给Docker。这是提供所有必需配置的最简单方法：

cp .env.example .env
# edit .env to set your values, then:
docker run -p 5000:5000 --env-file .env falkordb/queryweaver

替代方案：传递单个环境变量

如果您更喜欢在命令行上传递变量，请使用 -e 标志（对于许多变量来说不太方便）：

docker run -p 5000:5000 -it \
  -e APP_ENV=production \
  -e FASTAPI_SECRET_KEY=your_super_secret_key_here \
  -e GOOGLE_CLIENT_ID=your_google_client_id \
  -e GOOGLE_CLIENT_SECRET=your_google_client_secret \
  -e GITHUB_CLIENT_ID=your_github_client_id \
  -e GITHUB_CLIENT_SECRET=your_github_client_secret \
  -e AZURE_API_KEY=your_azure_api_key \
  falkordb/queryweaver

注意：QueryWeaver支持多个AI提供者。您可以使用 OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY，或 AZURE_API_KEY。请参阅 AI/LLM配置 详情请参阅第节。

有关配置选项的完整列表，请参阅 .env.example.

存储器TTL（可选）

QueryWeaver将每个用户的对话内存存储在FalkorDB中。默认情况下，这些图形会无限期保存。集 MEMORY_TTL_SECONDS 应用Redis TTL（以秒为单位），以便自动清理空闲内存图。

# Expire memory graphs after 1 week of inactivity
MEMORY_TTL_SECONDS=604800

TTL在每次用户交互时都会刷新，因此活动用户会保留他们的内存。

MCP服务器：主机或连接（可选）

QueryWeaver包括对模型上下文协议（MCP）的可选支持。您可以让QueryWeaver公开一个与MCP兼容的HTTP表面（这样其他服务就可以将QueryWeaver作为MCP服务器调用），也可以配置QueryWeaver为模型/上下文服务调用外部MCP服务器。

QueryWeaver提供什么

• 该应用程序注册了专注于Text2SQL流的MCP操作：

- list_databases - connect_database - database_schema - query_database

• 禁用内置MCP端点集 DISABLE_MCP=true 在你的 .env 或环境（默认：启用MCP）。

• 配置

• DISABLE_MCP --禁用QueryWeaver的内置MCP HTTP表面。设置为 true 禁用。违约： false （MCP已启用）。

示例

使用Docker运行时禁用内置MCP：

docker run -p 5000:5000 -it --env DISABLE_MCP=true falkordb/queryweaver

调用内置MCP端点（示例）

• MCP表面作为HTTP端点公开。

服务器配置

下面是一个最小的例子 mcp.json 针对本地QueryWeaver实例的客户端配置，该实例在以下位置公开MCP HTTP表面 /mcp.

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

REST API

API文档

Swagger用户界面：https://app.queryweaver.ai/docs

OpenAPI JSON：https://app.queryweaver.ai/openapi.json

概述

QueryWeaver公开了一个小型REST API，用于管理图形（数据库模式）和运行Text2SQL查询。所有修改或访问用户范围数据的端点都需要通过承载令牌进行身份验证。在浏览器中，应用程序使用会话Cookie和OAuth流；对于CLI和脚本，可以使用API令牌（请参阅 tokens 路由或web UI以创建一个）。

核心端点

• GET/graphs--列出经过身份验证的用户的可用图形
• GET/graphs/{graph_id}/data——返回图的节点/链接（表、列、外键）
• POST/graphs——上传或创建图形（JSON有效载荷或文件上传）
• POST/graphs/{graph_id}--对命名图运行Text2SQL聊天查询（流式响应）

认证

• 添加授权标头： Authorization: Bearer

示例

1. 列出图表（GET）

卷曲示例：

curl -s -H "Authorization: Bearer $TOKEN" \
   https://app.queryweaver.ai/graphs

Python示例：

import requests
resp = requests.get('https://app.queryweaver.ai/graphs', headers={'Authorization': f'Bearer {TOKEN}'})
print(resp.json())

1. 获取图模式（Get）

卷曲示例：

curl -s -H "Authorization: Bearer $TOKEN" \
   https://app.queryweaver.ai/graphs/my_database/data

Python示例：

resp = requests.get('https://app.queryweaver.ai/graphs/my_database/data', headers={'Authorization': f'Bearer {TOKEN}'})
print(resp.json())

1. 加载图形（POST）--JSON有效负载

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -d '{"database": "my_database", "tables": [...]}' \
   https://app.queryweaver.ai/graphs

或者上传一个文件（多部分/表单数据）：

curl -H "Authorization: Bearer $TOKEN" -F "file=@schema.json" \
   https://app.queryweaver.ai/graphs

1. 查询图形（POST）——运行基于聊天的Text2SQL请求

这 POST /graphs/{graph_id} 端点接受至少包含以下内容的JSON正文 chat 字段（消息数组）。端点将处理步骤和最终的SQL作为服务器发送的消息块进行流式传输，这些消息块由前端使用的特殊边界分隔。对于简单的脚本编写，您可以调用它并从流式消息中读取最终的JSON对象。

有效载荷示例：

{
   "chat": ["How many users signed up last month?"],
   "result": [],
   "instructions": "Prefer PostgreSQL compatible SQL"
}

curl示例（简单，收集整个响应）：

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -d '{"chat": ["Count orders last week"]}' \
   https://app.queryweaver.ai/graphs/my_database

Python示例（流感知）：

import requests
import 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": ["Count orders last week"]}, stream=True) as r:
      # The server yields JSON objects delimited by a message boundary string
      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)
                  if not part.strip():
                        continue
                  obj = json.loads(part)
                  print('STREAM:', obj)

注意事项和提示

• 图形ID是按用户命名的。当调用API时，直接使用普通图id（服务器将由经过身份验证的用户命名名称空间）。对于上传的文件 database 字段确定保存的图形id。
• 流式响应包括中间推理步骤、后续问题（如果查询不明确或偏离主题）和最终SQL。前端需要边界字符串 |||FALKORDB_MESSAGE_BOUNDARY||| 消息之间。
• 对于破坏性SQL（INSERT/UPDATE/DELETE等），服务将在流中包含一个确认步骤；前端处理此流。如果您将破坏性操作自动化，请确保正确处理确认（请参阅 ConfirmRequest 代码中的模型）。

开发包

QueryWeaver Python SDK允许您在Python应用程序中直接使用Text2SQL功能 不运行web服务器.

安装

# SDK only (minimal dependencies)
pip install queryweaver

# With server dependencies (FastAPI, etc.)
pip install queryweaver[server]

# Development (includes testing tools)
pip install queryweaver[dev]

快速开始

import asyncio
from queryweaver import QueryWeaver

async def main():
    # Initialize with FalkorDB connection
    qw = QueryWeaver(falkordb_url="redis://localhost:6379")

    # Connect a PostgreSQL or MySQL database
    conn = await qw.connect_database("postgresql://user:pass@host:5432/mydb")
    print(f"Connected: {conn.database_id}")  # "mydb"

    # Convert natural language to SQL and execute — pass the database_id
    # returned by connect_database (un-prefixed; namespacing is internal).
    result = await qw.query(conn.database_id, "Show me all customers from NYC")
    print(result.sql_query)    # SELECT * FROM customers WHERE city = 'NYC'
    print(result.results)       # [{"id": 1, "name": "Alice", "city": "NYC"}, ...]
    print(result.ai_response)   # "Found 42 customers from NYC..."

    await qw.close()

asyncio.run(main())

上下文管理器

async with QueryWeaver(falkordb_url="redis://localhost:6379") as qw:
    conn = await qw.connect_database("postgresql://user:pass@host/mydb")
    result = await qw.query(conn.database_id, "Count orders by status")
# close() runs automatically, awaiting any in-flight background memory writes.

多个实例

多个 QueryWeaver 实例可以在同一进程中并行运行。 每个都拥有自己的FalkorDB连接，并显式地传递它 每一个呼叫，所以没有共享的全局状态可以冲突。

async with QueryWeaver(falkordb_url="redis://host-a:6379", user_id="tenant_a") as a, \
           QueryWeaver(falkordb_url="redis://host-b:6379", user_id="tenant_b") as b:
    sales = await a.connect_database("postgresql://user:pass@host-a/sales")
    ops = await b.connect_database("postgresql://user:pass@host-b/ops")
    await a.query(sales.database_id, "Show top customers")
    await b.query(ops.database_id, "Count open tickets")

可用方法

高级查询选项

对于多回合对话、自定义指令或按请求LLM覆盖：

from queryweaver import QueryWeaver, QueryRequest

request = QueryRequest(
    question="Show their recent orders",
    chat_history=["Show all customers from NYC"],
    result_history=["Found 42 customers..."],
    instructions="Use created_at for date filtering",
    # Optional per-request LLM overrides — bypass env-based config
    custom_api_key="sk-...",
    custom_model="openai/gpt-4.1",
)

result = await qw.query("mydb", request)

处理破坏性操作

INSERT、UPDATE、DELETE操作需要确认：

result = await qw.query("mydb", "Delete inactive users")

if result.requires_confirmation:
    print(f"Destructive SQL: {result.sql_query}")
    # Execute after user confirms
    confirmed = await qw.execute_confirmed("mydb", result.sql_query)

需求

• Python 3.12+
• FalkorDB实例（本地或远程）
• OpenAI或Azure OpenAI API密钥（用于LLM）
• 目标SQL数据库（PostgreSQL或MySQL）

发展

按照以下步骤从源代码运行和开发QueryWeaver。

先决条件

• Python 3.12+
• uv（Python包管理器）
• FalkorDB实例（本地或远程）
• Node.js和npm（用于React前端）

安装和配置

快速入门（建议用于开发）：

# Clone the repo
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver

# Install dependencies (backend + frontend) and start the dev server
make install
make run-dev

如果您更喜欢手动设置或需要自定义环境，请使用uv：

# Install Python (backend) and frontend dependencies
uv sync

# Create a local environment file
cp .env.example .env
# Edit .env with your values (set APP_ENV=development for local development)

在本地运行应用程序

uv run uvicorn api.index:app --host 0.0.0.0 --port 5000 --reload

服务器将在以下时间可用http://localhost:5000

或者，存储库提供了运行应用程序的Make目标：

make run-dev   # development server (reload, debug-friendly)
make run-prod  # production mode (ensure frontend build if needed)

前端构建（需要时）

前端是一个现代的React+Vite应用程序 app/.在生产运行之前或前端更改之后构建：

make install       # installs backend and frontend deps
make build-prod    # builds the frontend into app/dist/

# or manually
cd app
npm ci
npm run build

OAuth配置

QueryWeaver支持谷歌和GitHub OAuth。为每个提供者创建OAuth凭据，并将客户端ID/机密粘贴到您的 .env 文件。

• 谷歌：设置授权来源和回调 http://localhost:5000/login/google/authorized
• GitHub：设置主页和回调 http://localhost:5000/login/github/authorized

特定于环境的OAuth设置

对于生产/临时部署，请设置 APP_ENV=production 或 APP_ENV=staging 在您的环境中启用安全会话Cookie（仅限HTTPS）。这可以防止OAuth CSRF状态不匹配错误。

# For production/staging (enables HTTPS-only session cookies)
APP_ENV=production

# For development (allows HTTP session cookies)
APP_ENV=development

重要：如果在登台/生产过程中出现“mismatching_state:CSRF警告！”错误，请确保 APP_ENV 设置为 production 或 staging 以实现安全的会话处理。

AI/LLM配置

QueryWeaver支持多个AI提供者。设置一个API键，QueryWeaver自动检测要使用的提供程序。

优先级顺序： Olama>OpenAI>Gemini>Anthropic>Cohere>Azure（默认）

\*Anthropic没有原生嵌入。您必须设置 VOYAGE_API_KEY 或 EMBEDDING_MODEL 对于嵌入，否则启动将失败并出现错误。

可选：覆盖默认模型

COMPLETION_MODEL=gemini/gemini-3-pro-preview
EMBEDDING_MODEL=gemini/gemini-embedding-001

两者都必须与API密钥的提供程序相匹配。

带有AI配置的Docker示例

使用OpenAI：

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

使用谷歌双子座：

docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e GEMINI_API_KEY=your_gemini_api_key \
  falkordb/queryweaver

使用Anthropic：

docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e ANTHROPIC_API_KEY=your_anthropic_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

测试

快速提示：许多测试需要FalkorDB可用。如果需要，使用附带的帮助程序在Docker中运行测试数据库。

先决条件

• 安装开发依赖项： uv sync
• 启动FalkorDB（参见 make docker-falkordb)
• 安装Playwright浏览器： uv run playwright install

快捷命令

建议：使用Make帮助程序准备开发/测试环境（安装依赖项和Playwright浏览器）：

# Prepare development/test environment (installs deps and Playwright browsers)
make setup-dev

或者，您可以运行E2E特定的设置脚本，然后手动运行测试：

# Prepare E2E test environment (installs browsers and other setup)
./setup_e2e_tests.sh

# Run all tests
make test

# Run unit tests only (faster)
make test-unit

# Run E2E tests (headless)
make test-e2e

# Run E2E tests with a visible browser for debugging
make test-e2e-headed

测试类型

• 单元测试：专注于单个模块和实用程序。与一起跑步 make test-unit 或 uv run python -m pytest tests/ -k "not e2e".
• 端到端（E2E）测试：通过Playwright和练习UI流、OAuth、文件上传、模式处理、聊天查询和API端点运行。使用 make test-e2e.

看 tests/e2e/README.md 获取完整的E2E测试说明。

CI/CD

GitHub Actions对推送和拉取请求运行单元和E2E测试。故障捕获屏幕截图和工件以进行调试。

故障排除

• FalkorDB连接问题：启动DB帮助程序 make docker-falkordb 或检查网络/主机设置。
• 剧作家/浏览器故障：安装带有 uv run playwright install 并确保系统deps存在。
• 缺少环境变量：复制 .env.example 并填写所需值。
• OAuth“mismatching_state:CSRF警告！”错误：设置 APP_ENV=production （或 staging)在您的HTTPS部署环境中，或 APP_ENV=development 用于HTTP开发环境。这可确保为您的部署类型正确配置会话Cookie。

项目布局（高层）

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

许可证

根据GNU Affero通用公共许可证（AGPL）授权。看 许可证.

版权所有FalkorDB有限公司2025