QueryWeaver (Text2SQL)

REST API · MCP · Graph-powered

QueryWeaver — это open-source Text2SQL инструмент, который преобразует вопросы на простом английском языке в SQL с помощью понимания схемы на основе графов. Он позволяет задавать базам данных вопросы на естественном языке и возвращает SQL и результаты.

Подключайтесь и задавайте вопросы:

Начало работы

Docker

💡 Рекомендуется для целей оценки (локальные 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 включает необязательную поддержку Model Context Protocol (MCP). Вы можете либо позволить QueryWeaver предоставлять MCP-совместимый HTTP-интерфейс (чтобы другие сервисы могли вызывать QueryWeaver как MCP-сервер), либо настроить QueryWeaver для вызова внешнего MCP-сервера для моделей/контекстных сервисов.

Что предоставляет QueryWeaver - Приложение регистрирует MCP-операции, ориентированные на Text2SQL-процессы: - list_databases - connect_database - database_schema - query_database

• Чтобы отключить встроенные MCP-эндпоинты, установите DISABLE_MCP=true в вашем .env или окружении (по умолчанию: MCP включён).
• Конфигурация

• DISABLE_MCP — отключает встроенный MCP HTTP-интерфейс QueryWeaver. Установите true, чтобы отключить. По умолчанию: false (MCP включён).

Примеры

Отключение встроенного MCP при запуске с Docker:

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 UI: https://app.queryweaver.ai/docs

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

Обзор

QueryWeaver предоставляет небольшой REST API для управления графами (схемами базы данных) и выполнения Text2SQL-запросов. Все эндпоинты, которые изменяют или получают доступ к данным в области пользователя, требуют аутентификации через bearer-токен. В браузере приложение использует сессионные cookie и OAuth-потоки; для CLI и скриптов вы можете использовать API-токен (см. маршруты tokens или веб-интерфейс для его создания).

Основные эндпоинты - GET /graphs — список доступных графов для аутентифицированного пользователя - GET /graphs/{graph_id}/data — возвращает узлы/связи (таблицы, колонки, внешние ключи) для графа - POST /graphs — загрузка или создание графа (JSON-полезная нагрузка или загрузка файла) - POST /graphs/{graph_id} — выполнение Text2SQL чат-запроса к указанному графу (потоковый ответ)

Аутентификация - Добавьте заголовок авторизации: Authorization: Bearer <API_TOKEN>

Примеры

1) Получение списка графов (GET)

Пример с curl:

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())

2) Получение схемы графа (GET)

Пример с curl:

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())

3) Загрузка графа (POST) — JSON-полезная нагрузка

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

Или загрузка файла (multipart/form-data):

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

4) Запрос к графу (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)

Примечания и советы - Идентификаторы графов имеют пространство имён для каждого пользователя. При прямом вызове API используйте обычный идентификатор графа (сервер сам назначит пространство имён по аутентифицированному пользователю). Для загруженных файлов поле database определяет сохранённый идентификатор графа. - Потоковый ответ включает промежуточные этапы рассуждений, уточняющие вопросы (если запрос неоднозначен или не по теме) и итоговый SQL. Фронтенд ожидает строку границы |||FALKORDB_MESSAGE_BOUNDARY||| между сообщениями. - Для разрушительных SQL-запросов (INSERT/UPDATE/DELETE и т. д.) сервис включает этап подтверждения в потоке; фронтенд обрабатывает этот процесс. Если вы автоматизируете разрушительные операции, убедитесь, что правильно обрабатываете подтверждение (см. модель ConfirmRequest в коде).

Python SDK

Python SDK QueryWeaver позволяет использовать функциональность Text2SQL непосредственно в ваших Python-приложениях без запуска веб-сервера.

Установка

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

Доступные методы

Дополнительные параметры запроса

Для многоходовых бесед, пользовательских инструкций или переопределений LL на каждый запрос:

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 (локальный или удалённый)
• Ключ API OpenAI или Azure OpenAI (для 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 поддерживает Google и GitHub OAuth. Создайте учётные данные OAuth для каждого провайдера и вставьте идентификаторы клиентов/секреты в ваш файл .env.

• Google: задайте авторизованный источник и обратный вызов http://localhost:5000/login/google/authorized
• GitHub: задайте домашнюю страницу и обратный вызов http://localhost:5000/login/github/authorized

Настройки OAuth для конкретного окружения

Для production/staging развертываний установите 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 Warning!" на staging/production, убедитесь, что APP_ENV установлен в production или staging, чтобы включить безопасную обработку сессий.

Конфигурация AI/LLM

QueryWeaver поддерживает несколько AI-провайдеров. Установите один API-ключ, и QueryWeaver автоматически определит, какого провайдера использовать.

Порядок приоритета: Ollama > 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-ключа.

Примеры Docker с AI-конфигурацией

Использование OpenAI:

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

Использование Google Gemini:

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, если необходимо.

Предварительные требования

• Установите dev-зависимости: 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

В качестве альтерality, вы можете запустить сценарий настройки для 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 и проверяют пользовательские интерфейсы, OAuth, загрузку файлов, обработку схем, чат-запросы и API-эндпоинты. Используйте make test-e2e.

См. tests/e2e/README.md для полных инструкций по E2E-тестам.

CI/CD

GitHub Actions запускают модульные и E2E-тесты при пушах и pull request'ах. При сбоях сохраняются скриншоты и артефакты для отладки.

Устранение неполадок

• Проблемы с подключением к FalkorDB: запустите помощник БД make docker-falkordb или проверьте сетевые/хост-настройки.
• Сбои Playwright/браузера: установите браузеры с помощью uv run playwright install и убедитесь, что присутствуют системные зависимости.
• Отсутствующие переменные окружения: скопируйте .env.example и заполните требуемые значения.
• Ошибки OAuth "mismatching_state: CSRF Warning!": Установите APP_ENV=production (или staging) в вашем окружении для HTTPS-развертываний, или APP_ENV=development для HTTP-среды разработки. Это гарантирует правильную настройку сессионных cookie для вашего типа развертывания.

Структура проекта (высокоуровнево)

• api/ – бэкенд FastAPI
• app/ – фронтенд React + Vite
• tests/ – модульные и E2E тесты

Лицензия

Лицензировано под GNU Affero General Public License (AGPL). См. LICENSE.

Copyright FalkorDB Ltd. 2025