QueryWeaver

<div align="center"> <h1>QueryWeaver (Text2SQL)</h1>

REST API · MCP · Graph-powered

QueryWeaver is an open-source Text2SQL tool that converts plain-English questions into SQL using graph-powered schema understanding. It helps you ask databases natural-language questions and returns SQL and results.

Connect and ask questions:

</div>

Get Started

Docker

💡 Recommended for evaluation purposes (Local Python or Node are not required)

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

Launch: http://localhost:5000

---

Use an .env file (Recommended)

Create a local .env by copying .env.example and passing it to Docker. This is the simplest way to provide all required configuration:

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

Alternative: Pass individual environment variables

If you prefer to pass variables on the command line, use -e flags (less convenient for many variables):

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

Note: QueryWeaver supports multiple AI providers. You can use OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, or AZURE_API_KEY. See the AI/LLM configuration section for details.

For a full list of configuration options, consult .env.example.

Memory TTL (optional)

QueryWeaver stores per-user conversation memory in FalkorDB. By default these graphs persist indefinitely. Set MEMORY_TTL_SECONDS to apply a Redis TTL (in seconds) so idle memory graphs are automatically cleaned up.

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

The TTL is refreshed on every user interaction, so active users keep their memory.

MCP server: host or connect (optional)

QueryWeaver includes optional support for the Model Context Protocol (MCP). You can either have QueryWeaver expose an MCP-compatible HTTP surface (so other services can call QueryWeaver as an MCP server), or configure QueryWeaver to call an external MCP server for model/context services.

What QueryWeaver provides

• The app registers MCP operations focused on Text2SQL flows:

  • list_databases
  • connect_database
  • database_schema
  • query_database

• To disable the built-in MCP endpoints set DISABLE_MCP=true in your .env or environment (default: MCP enabled).

• Configuration

• DISABLE_MCP — disable QueryWeaver's built-in MCP HTTP surface. Set to true to disable. Default: false (MCP enabled).

Examples

Disable the built-in MCP when running with Docker:

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

Calling the built-in MCP endpoints (example)

• The MCP surface is exposed as HTTP endpoints.

Server Configuration

Below is a minimal example mcp.json client configuration that targets a local QueryWeaver instance exposing the MCP HTTP surface at /mcp.

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

REST API

API Documentation

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

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

Overview

QueryWeaver exposes a small REST API for managing graphs (database schemas) and running Text2SQL queries. All endpoints that modify or access user-scoped data require authentication via a bearer token. In the browser the app uses session cookies and OAuth flows; for CLI and scripts you can use an API token (see tokens routes or the web UI to create one).

Core endpoints

• GET /graphs — list available graphs for the authenticated user
• GET /graphs/{graph_id}/data — return nodes/links (tables, columns, foreign keys) for the graph
• POST /graphs — upload or create a graph (JSON payload or file upload)
• POST /graphs/{graph_id} — run a Text2SQL chat query against the named graph (streaming response)

Authentication

• Add an Authorization header: Authorization: Bearer <API_TOKEN>

Examples

1. List graphs (GET)

curl example:

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

Python example:

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

2. Get graph schema (GET)

curl example:

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

Python example:

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

3. Load a graph (POST) — JSON payload

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

Or upload a file (multipart/form-data):

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

4. Query a graph (POST) — run a chat-based Text2SQL request

The POST /graphs/{graph_id} endpoint accepts a JSON body with at least a chat field (an array of messages). The endpoint streams processing steps and the final SQL back as server-sent-message chunks delimited by a special boundary used by the frontend. For simple scripting you can call it and read the final JSON object from the streamed messages.

Example payload:

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

curl example (simple, collects whole response):

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 example (stream-aware):

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)

Notes & tips

• Graph IDs are namespaced per-user. When calling the API directly use the plain graph id (the server will namespace by the authenticated user). For uploaded files the database field determines the saved graph id.
• The streaming response includes intermediate reasoning steps, follow-up questions (if the query is ambiguous or off-topic), and the final SQL. The frontend expects the boundary string |||FALKORDB_MESSAGE_BOUNDARY||| between messages.
• For destructive SQL (INSERT/UPDATE/DELETE etc) the service will include a confirmation step in the stream; the frontend handles this flow. If you automate destructive operations, ensure you handle confirmation properly (see the ConfirmRequest model in the code).

Python SDK

The QueryWeaver Python SDK allows you to use Text2SQL functionality directly in your Python applications without running a web server.

Installation

# SDK only (minimal dependencies)
pip install queryweaver

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

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

Quick Start

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)   # "F