🦆 クアック・クラスタ

DuckDB と Ray を組み合わせたサーバーレス分散 SQL クエリエンジン

クアック・クラスタは、オブジェクトストレージ（例：AWS S3 や Google Cloud Storage）に保存されたデータに対して、複雑な SQL クエリを直接実行できる高性能かつサーバーレスの分散 SQL エンジンです。Python、Ray 分散計算フレームワーク、および超高速 DuckDB アナリティクスデータベースを組み合わせており、大規模ビッグデータシステムに代わる軽量で理想的な選択肢となります。

✨ 主な特徴

• サーバーレス & 分散 – Ray クラスター上でスケーラブルに SQL を実行し、サーバーインフラを管理する必要はありません。
• 高速 SQL 処理 – DuckDB のメモリ内カラム指向ベクトル化エンジンと Apache Arrow を活用した極めて高速な分析が可能です。
• データの所在でクエリ実行 – Parquet、CSV などをオブジェクトストレージやローカルファイルシステムから直接読み込み、ETL は不要です。
• Python ネイティブ統合 – Python で構築されており、データサイエンス・エンジニアリング・ML のワークフローにシームレスに組み込めます。
• オープンソーススタック – FastAPI、Ray、DuckDB、SQLGlot などを採用しています。

🏛️ 構成図

ユーザー → コーディネーター (FastAPI + SQLGlot) → Ray クラスター
                                         ↘︎
                          ┌───────────────────────┐
                          │ ワーカー 1              │
                          │ (Ray Actor + DuckDB)   │
                          └────────▲────────────────┘
                                   │
                          ┌────────▼────────────────┐
                          │ ワーカー N              │
                          │ (Ray Actor + DuckDB)   │
                          └────────▲────────────────┘
                                   │
                        データソース (S3 / GCS / ローカル)

1. クライアント が標準的な SQL クエリをコーディネーターの API エンドポイントへ送信。
2. コーディネーターがクエリを解析し、対象ファイル（例：

   s3://my-bucket/data/*.parquet

   ）を特定して分散実行計画を構築。
3. Ray がタスクを複数のワーカーへディスパッチしてオーケストレーション。
4. 各 ワーカー は自身のデータサブセットに対し埋め込み DuckDB インスタンスで処理。
5. 部分結果はコーディネーターで集約され、クライアントへ返却。

この設計により、大量ファイル集合上での SQL クエリを大規模並列処理（MPP）で実行できます。

🚀 始め方

前提条件

• Docker

• make

  （Linux/macOS には標準装備、Windows は WSL 経由で利用可）

インストール & 起動

# 1. リポジトリをクローン
git clone https://github.com/your-username/quack-cluster.git
cd quack-cluster

# 2. サンプルデータ生成（./data に Parquet ファイル作成）
make data

# 3. クラスター構築・起動
#    Ray のヘッドノード + N 個のワーカーノードを起動
make up scale=2

クラスターは稼働中です！
Ray ダッシュボードは http://localhost:8265 で確認できます。

👨‍🏫 チュートリアル：分散 SQL クエリの実行

任意の HTTP クライアント（curl、Postman 等）を使い、

http://localhost:8000/query

curl -X POST \
     http://localhost:8000/query \
     -H 'Content-Type: application/json' \
     -d '{
           "sql": "SELECT product, SUM(sales) AS total_sales FROM \"data_part_*.parquet\" GROUP BY product ORDER BY product"
         }'

期待される出力

{
  "result": [
    {"product":"A","total_sales":420.0},
    {"product":"B","total_sales":400.0},
    {"product":"C","total_sales":300.0}
  ]
}

🚀 Postman でテスト

1. コレクションと環境をインポート

   • documentation/postman_collection/QuackCluster_API_Tests.json

   • documentation/postman_collection/QuackCluster_postman_environment.json

2. 環境を有効化 – Postman で「Quack Cluster Environment」を選択。

3. リクエスト送信 – ベース URL は

   http://127.0.0.1:8000

   に設定されています。

💡 サポートされる SQL 機能

SELECT

FROM

WHERE

GROUP BY

ORDER BY

LIMIT

COUNT()

SUM()

AVG()

MIN()

MAX()

INNER JOIN

LEFT JOIN

FULL OUTER JOIN

WITH

OVER (PARTITION BY ...)

"s3://my-data/2025/**/*.parquet"

SELECT * EXCLUDE (...)

SELECT COLUMNS('<regex>')

🛠️ 開発・管理コマンド

make up scale=N

make down

make logs

make build

make test

make clean

🗺️ プロジェクトロードマップ

• ✅ 分散 JOIN 機能
• ✅ ウィンドウ関数（OVER, PARTITION BY）
• 🔜 メタデータカタログ統合（Apache Iceberg、Delta Lake）
• 🔜 開発者体験を向上させる専用 Python SDK

🤝 貢献

ご協力大歓迎です！Issue を立てるか Pull Request を送信してください。すべてのコア設計決定とテストは人間によってレビューされ、品質が保証されています。

🤖 AI 主導開発

本プロジェクトでは AI ツールを活用して開発速度とドキュメント作成を加速していますが、重要なアーキテクチャ設計・デバッグ・最終テストはすべて人間によって行われます。

📄 ライセンス

MIT © 2026 Quack‑Cluster。詳細は LICENSE ファイルをご覧ください。