A New Approach: Graph‑Database‑Powered Text‑to‑SQL Tool QueryWeaver

Background

FalkorDB, a company focused on ultra‑fast, multi‑tenant graph databases for GenAI, powers QueryWeaver. Its core product uses a Property Graph model with OpenCypher, claims benchmark latency 496× faster than Neo4j and 6× lower memory, and supports full‑text, vector similarity, and range indexes, as well as a built‑in GraphRAG SDK for retrieval‑augmented generation.

Core Idea of QueryWeaver

Instead of feeding table schemas directly to a large language model, QueryWeaver first converts the database schema into a graph—tables become nodes and foreign‑key relationships become edges. During a natural‑language query, the system traverses this graph to locate relevant tables, making multi‑table JOIN reasoning more intuitive for the LLM.

Key Features

Graph‑powered schema understanding : stores and traverses schema relationships in FalkorDB.

REST API + MCP dual interface : traditional RESTful endpoints and native Model Context Protocol support for AI tools like Claude and Cursor.

Multi‑LLM support : defaults to Azure OpenAI, also works with OpenAI (text‑embedding‑ada‑002, gpt‑4.1).

Conversation memory : each user’s dialogue context is persisted in FalkorDB, with optional TTL cleanup.

Streaming response : returns intermediate reasoning steps and final SQL, allowing the front‑end to show the AI’s “thinking”.

Google/GitHub OAuth login : enterprise‑grade authentication.

Comparison with Wren AI

Core approach : QueryWeaver uses graph‑DB schema understanding; Wren AI builds a semantic layer.

Schema handling : QueryWeaver auto‑creates a relationship graph; Wren AI requires manual semantic modeling.

Onboarding : QueryWeaver runs with a single Docker command; Wren AI needs time to set up the semantic model.

MCP support : native in QueryWeaver, absent in Wren AI.

Data source : QueryWeaver imports schema (no direct DB connection); Wren AI connects directly to PostgreSQL, MySQL, Snowflake, etc.

LLM options : QueryWeaver supports Azure OpenAI/OpenAI; Wren AI supports multiple providers including Gemini, Claude, Ollama.

SQL validation : QueryWeaver streams reasoning; Wren AI executes SQL internally for verification.

Visualization : QueryWeaver shows a graphical schema; Wren AI generates charts and reports.

GitHub stars : QueryWeaver 336 ★ vs. Wren AI 13.3k ★.

Installation

Run the container with a single Docker command:

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

Access the UI at http://localhost:5000. To configure an API key, copy the example env file and edit it:

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

Alternatively, pass secrets via environment variables:

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

# Using 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 Integration

QueryWeaver includes an MCP server with four operations: list_databases: list available databases. connect_database: connect to a specific database. database_schema: retrieve the schema. query_database: execute a natural‑language query.

Add the following to your MCP client configuration:

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

Example scenario: while coding in Claude Desktop or Cursor, ask “How many new users registered last month?” and QueryWeaver translates the request to SQL behind the scenes.

REST API Usage

List available graphs (schemas):

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

Perform a streaming natural‑language query:

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)
            if not part.strip():
                continue
            obj = json.loads(part)
            print('STREAM:', obj)

The streaming response includes intermediate reasoning steps and the final SQL.

Source Development

To run from source or contribute:

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

# Install and start
defaultmake install
make run-dev

Prerequisites: Python 3.12+, pipenv, Node.js (React + Vite), and a FalkorDB instance. Project structure: api/ – FastAPI backend. app/ – React + Vite frontend. tests/ – unit and end‑to‑end tests.

Conversation Memory

Each user’s session is stored in FalkorDB and persists indefinitely unless a TTL is set. Example to auto‑clean after one week of inactivity:

# 1 week inactivity cleanup
MEMORY_TTL_SECONDS=604800

Active users have their TTL refreshed automatically.

Who Is It For?

Data analysts – ask questions in natural language without writing SQL.

AI application developers – integrate Text‑to‑SQL via REST or MCP.

Claude/Cursor users – query databases directly from AI IDEs.

Technical teams – need an open‑source, AGPL‑licensed solution.

Limitations

LLM choice limited to Azure OpenAI and OpenAI; no local Ollama support.

Does not connect directly to databases; requires manual schema upload.

Community is small (336 ★) compared to alternatives.

No built‑in visual reporting; only returns SQL and query results.

Conclusion

QueryWeaver introduces a novel graph‑database‑driven approach to schema understanding for Text‑to‑SQL, complementing Wren AI’s semantic‑layer method. Its strengths are rapid, out‑of‑the‑box usage and native MCP support, while future improvements could include more LLM options, direct database connections, and richer visualizations.

Official links:

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

Online demo: https://app.queryweaver.ai

FalkorDB docs: https://docs.falkordb.com/

FalkorDB website: https://falkordb.com

Swagger API: https://app.queryweaver.ai/docs

Discord community: https://discord.gg/b32KEzMzce