Queryweaver

🚀 QueryWeaver

QueryWeaverは、グラフベースのスキーマ理解を用いて、英語の質問をSQLに変換するオープンソースのText2SQLツールです。このツールを使えば、データベースに自然言語で質問を投げかけ、SQLとその結果を取得することができます。

接続と質問:

🚀 クイックスタート

Docker

💡 評価目的に推奨 (ローカルのPythonまたはNodeは不要)

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

起動: http://localhost:5000

.envファイルの使用 (推奨)

.env.exampleをコピーしてローカルの.envファイルを作成し、それをDockerに渡します。これは必要なすべての設定を提供する最も簡単な方法です。

cp .env.example .env
# .envを編集して値を設定し、次に:
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

注意: Azure OpenAIではなく直接OpenAIを使用するには、上記のコマンドでAZURE_API_KEYをOPENAI_API_KEYに置き換えてください。

すべての設定オプションのリストについては、.env.exampleを参照してください。

🔧 MCPサーバー: ホストまたは接続 (オプション)

QueryWeaverは、Model Context Protocol (MCP) のオプションサポートを備えています。QueryWeaverがMCP互換のHTTPインターフェースを公開することで、他のサービスがQueryWeaverをMCPサーバーとして呼び出すことができます。または、QueryWeaverを設定して、モデル/コンテキストサービスのために外部のMCPサーバーを呼び出すこともできます。

QueryWeaverが提供するもの

• アプリは、Text2SQLフローに焦点を当てたMCP操作を登録します:

  • list_databases
  • connect_database
  • database_schema
  • query_database

• 組み込みのMCPエンドポイントを無効にするには、.envまたは環境でDISABLE_MCP=trueを設定します (デフォルト: 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でMCP HTTPインターフェースを公開するローカルのQueryWeaverインスタンスを対象とした最小限のmcp.jsonクライアント設定の例です。

{
   "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は、グラフ (データベーススキーマ) の管理とText2SQLクエリの実行のための小規模なREST APIを公開しています。ユーザースコープのデータを変更またはアクセスするすべてのエンドポイントは、ベアラートークンによる認証を必要とします。ブラウザでは、アプリはセッションクッキーとOAuthフローを使用します。CLIやスクリプトでは、APIトークンを使用できます (トークンを作成するには、tokensルートまたはウェブUIを参照してください)。

主要なエンドポイント

• GET /graphs — 認証されたユーザーに利用可能なグラフのリストを返します。
• GET /graphs/{graph_id}/data — グラフのノード/リンク (テーブル、列、外部キー) を返します。
• POST /graphs — グラフをアップロードまたは作成します (JSONペイロードまたはファイルアップロード)。
• POST /graphs/{graph_id} — 指定されたグラフに対してText2SQLチャットクエリを実行します (ストリーミングレスポンス)。

認証

• Authorizationヘッダーを追加します: 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}エンドポイントは、少なくともchatフィールド (メッセージの配列) を含むJSONボディを受け付けます。このエンドポイントは、処理手順と最終的な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:
      # サーバーはメッセージ境界文字列で区切られたJSONオブジェクトを生成します
      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 3.12以上
• pipenv
• FalkorDBインスタンス (ローカルまたはリモート)
• Node.jsとnpm (TypeScriptフロントエンド用)

インストールと設定

クイックスタート (開発に推奨):

# リポジトリをクローンする
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver

# 依存関係をインストール (バックエンド + フロントエンド) し、開発サーバーを起動する
make install
make run-dev

手動で設定するか、カスタム環境が必要な場合は、Pipenvを使用します。

# Python (バックエンド) とフロントエンドの依存関係をインストールする
pipenv sync --dev

# ローカルの環境ファイルを作成する
cp .env.example .env
# .envを編集して値を設定する (ローカル開発の場合はAPP_ENV=developmentを設定する)

アプリをローカルで実行する

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

サーバーはhttp://localhost:5000で利用可能になります。

あるいは、リポジトリはアプリを実行するためのMakeターゲットを提供しています。

make run-dev   # 開発サーバー (リロード、デバッグに便利)
make run-prod  # 本番モード (必要に応じてフロントエンドのビルドを確認する)

フロントエンドのビルド (必要な場合)

フロントエンドはapp/にあるTypeScriptアプリです。本番実行前またはフロントエンドの変更後にビルドします。

make install       # バックエンドとフロントエンドの依存関係をインストールする
make build-prod    # フロントエンドをapp/public/js/app.jsにビルドする

# または手動で
cd app
npm ci
npm run build

OAuth設定

QueryWeaverはGoogleとGitHubのOAuthをサポートしています。各プロバイダーのOAuth資格情報を作成し、クライアントID/シークレットを.envファイルに貼り付けます。

• Google: 承認済みのオリジンとコールバックをhttp://localhost:5000/login/google/authorizedに設定します。
• GitHub: ホームページとコールバックをhttp://localhost:5000/login/github/authorizedに設定します。

環境固有のOAuth設定

本番/ステージングデプロイメントの場合は、環境でAPP_ENV=productionまたはAPP_ENV=stagingを設定して、セキュアなセッションクッキー (HTTPSのみ) を有効にします。これにより、OAuth CSRF状態の不一致エラーを防ぐことができます。

# 本番/ステージング (HTTPSのみのセッションクッキーを有効にする)
APP_ENV=production

# 開発 (HTTPセッションクッキーを許可する)
APP_ENV=development

重要: ステージング/本番環境で "mismatching_state: CSRF Warning!" エラーが発生する場合は、セキュアなセッション処理を有効にするために、APP_ENVをproductionまたはstagingに設定してください。

AI/LLM設定

QueryWeaverは、Text2SQL変換にAIモデルを使用し、Azure OpenAIとOpenAIの両方を直接サポートしています。

デフォルト: Azure OpenAI

デフォルトでは、QueryWeaverはAzure OpenAIを使用するように構成されています。すべての3つのAzure資格情報を設定する必要があります。

AZURE_API_KEY=your_azure_api_key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-12-01-preview

代替方法: 直接OpenAIを使用する

Azureではなく直接OpenAIを使用するには、単にOPENAI_API_KEY環境変数を設定します。

OPENAI_API_KEY=your_openai_api_key

OPENAI_API_KEYが提供されると、QueryWeaverは自動的にOpenAIのモデルを使用するように切り替わります。

• 埋め込みモデル: openai/text-embedding-ada-002
• 補完モデル: openai/gpt-4.1

この設定はapi/config.pyで自動的に処理されます — 適切なAPIキーを提供するだけで済みます。

AI設定を伴うDockerの例

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

直接OpenAIを使用する場合:

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

🧪 テスト

簡単な注意: 多くのテストにはFalkorDBが利用可能である必要があります。必要に応じて、Dockerでテスト用のDBを実行するためのヘルパーを使用してください。

前提条件

• 開発用の依存関係をインストールする: pipenv sync --dev
• FalkorDBを起動する (see make docker-falkordb)
• Playwrightブラウザをインストールする: pipenv run playwright install

クイックコマンド

推奨: Makeヘルパーを使用して開発/テスト環境を準備する (依存関係とPlaywrightブラウザをインストールする)。

# 開発/テスト環境を準備する (依存関係とPlaywrightブラウザをインストールする)
make setup-dev

あるいは、E2E固有のセットアップスクリプトを実行してから、手動でテストを実行することもできます。

# E2Eテスト環境を準備する (ブラウザをインストールし、その他の設定を行う)
./setup_e2e_tests.sh

# すべてのテストを実行する
make test

# 単体テストのみを実行する (高速)
make test-unit

# E2Eテストを実行する (ヘッドレス)
make test-e2e

# デバッグ用にブラウザを表示してE2Eテストを実行する
make test-e2e-headed

テストの種類

• 単体テスト: 個々のモジュールとユーティリティに焦点を当てます。make test-unitまたはpipenv run pytest tests/ -k "not e2e"で実行します。
• エンドツーエンド (E2E) テスト: Playwrightを介して実行され、UIフロー、OAuth、ファイルアップロード、スキーマ処理、チャットクエリ、およびAPIエンドポイントをテストします。make test-e2eを使用します。

完全なE2Eテストの手順については、tests/e2e/README.mdを参照してください。

CI/CD

GitHub Actionsは、プッシュとプルリクエスト時に単体テストとE2Eテストを実行します。失敗すると、デバッグ用にスクリーンショットとアーティファクトがキャプチャされます。

⚠️ トラブルシューティング

• FalkorDBの接続問題: DBヘルパーを起動するmake docker-falkordbまたはネットワーク/ホスト設定を確認してください。
• Playwright/ブラウザの失敗: pipenv run playwright installでブラウザをインストールし、システムの依存関係が存在することを確認してください。
• 環境変数が不足している: .env.exampleをコピーし、必要な値を入力してください。
• OAuth "mismatching_state: CSRF Warning!" エラー: HTTPSデプロイメントの場合は環境でAPP_ENV=production (またはstaging) を設定し、HTTP開発環境の場合はAPP_ENV=developmentを設定します。これにより、デプロイメントタイプに適したセッションクッキーが正しく構成されます。

📁 プロジェクトのレイアウト (大まかな概要)

• api/ – FastAPIバックエンド
• app/ – TypeScriptフロントエンド
• tests/ – 単体テストとE2Eテスト

📄 ライセンス

GNU Affero General Public License (AGPL)の下でライセンスされています。詳細はLICENSEを参照してください。

Copyright FalkorDB Ltd. 2025