ExplainDB: 理解しやすさを追求したデータベースシステム
ExplainDB: A Database System Built for Understandability (github.com)
要約
ExplainDBは、データベースシステムの教育を目的として開発された、理解しやすさを重視したデータベースシステムです。Pythonで実装された教育用DBMSとJupyter Notebookのコレクションで構成されており、データベースの概念を段階的に学習できるようになっています。ブラウザ上で簡単に試せる環境も提供されています。
全文翻訳
ExplainDB - 理解しやすさを追求したデータベースシステム
[画像: License: AGPL v3] [画像: Python 3.12] [画像: uv] [画像: Code style: black] [画像: Jupyter notebooks] [画像: Last commit] [画像: GitHub stars] [画像: Binder]
データベースシステムコースの教材:Jupyter Notebookのコレクションと、Pythonで実装された教育用DBMS(system/パッケージ)です。このコードを使用した講義はYouTubeで公開されています:Database Systems 2024/25(Prof. Dr. Jens Dittrich、Big Data Analytics Group、Saarland University)。
ブラウザで試す
バッジをクリックすると、インストール不要でmybinder.org上のJupyterLabでノートブックを開くことができます。初回起動時、リポジトリ変更後、または長時間の停止後には、Binderが環境を構築するため数分かかることがあります。セッションは一時的で、非アクティブ状態が続くと、または最長数時間で終了し、すべての変更は失われます。保持したいノートブックはダウンロードしてください(File → Download)。mybinder.orgは無料の公開サービスです。個人情報や機密データをアップロードしたり、Binderセッションでパスワードを入力したりしないでください。
ノートブック
ノートブックは、チュートリアルの章ごとにグループ化されており、各トピックを説明し、それを実装するコードを示しています。起動バッジはBinder上で直接ノートブックを開きます。
ストレージとデータレイアウト
| ノートブック | トピック | 起動 |
|---|---|---|
| Data-Layout | 行指向 vs. 列指向レイアウト:異なるクエリに対して各レイアウトがどれだけ読み込む必要があるか | [画像: Open Data-Layout on Binder] |
| MVCC-Playground | クリックして操作ごとに実行することでトランザクションのスケジュールを構築:MVCCストア上で、シリアライザブル、スナップショット分離下、または検証なしで実行 | [画像: Open MVCC-Playground on Binder] |
| RAID-Nesting-Trade-offs | RAID 0配列のネストとそのシーケンシャル読み込みパフォーマンスへの影響 | [画像: Open RAID-Nesting-Trade-offs on Binder] |
インデックス
| ノートブック | トピック | 起動 |
|---|---|---|
| B-tree | B⁺ツリーを段階的に構築:分割とリーフチェーンの可視化付き | [画像: Open B-tree on Binder] |
| Bitmaps-and-Bloom-Filters | ビットマップインデックス、その圧縮(WAH)、および「値が存在するかどうか」を高速にチェックするためのブルームフィルター | [画像: Open Bitmaps-and-Bloom-Filters on Binder] |
| Bit-Sequences-in-Pandas | Pandasにおけるブールマスクをビットシーケンスとして使用:行のフィルタリングとマスクのAND結合 | [画像: Open Bit-Sequences-in-Pandas on Binder] |
| Christmas-Tree | Radixトライとディスクリプタトライ:バッファリングおよび「クリスタルボール」バリアント付き | [画像: Open Christmas-Tree on Binder] |
| Recursive-Model-Index | ソート済みデータを検索するための学習済みインデックス(RMI) | [画像: Open Recursive-Model-Index on Binder] |
クエリ処理
| ノートブック | トピック | 起動 |
|---|---|---|
| Result-DB | 2つのJOINを含むクエリを演算子のパイプライン(プッシュモデル)として実行 | [画像: Open Result-DB on Binder] |
| CodeGen | Result-DBクエリのPythonコードを生成し、実行する | [画像: Open CodeGen on Binder] |
| Shared-Scan | 複数の同時クエリがデータスキャンを共有する | [画像: Open Shared-Scan on Binder] |
| External-Merge-Sort | メインメモリを超えるサイズのデータをソート:チャンクをソートし、それらをマージする | [画像: Open External-Merge-Sort on Binder] |
| Top-k | 全行をソートせずに ORDER BY title LIMIT 10 を実行 | [画像: Open Top-k on Binder] |
| Online-Aggregation | スキャン完了前に集計値の実行推定値を取得 | [画像: Open Online-Aggregation on Binder] |
クエリ最適化
| ノートブック | トピック | 起動 |
|---|---|---|
| PlanEnumeration | JOIN順序列挙アルゴリズム(DPsize, DPsub, DPccp) | [画像: Open PlanEnumeration on Binder] |
| Distributed-Joins | 複数のノードにまたがるJOINの実行 | [画像: Open Distributed-Joins on Binder] |
多次元
| ノートブック | トピック | 起動 |
|---|---|---|
| Z-Order-Curve | Zコード(モートンコード):局所性を保ちながら2次元データを1次元にマッピング | [画像: Open Z-Order-Curve on Binder] |
system/ パッケージの中身
読み込みを目的とし、速度を追求しない小規模DBMS。system/interfaces/ のインターフェースが契約を運び、他のフォルダがそれを実装します:
- ストレージ (
storage/):ストレージ階層(DRAM、キャッシュ、SSD、ディスク)とRAIDブロック割り当て(RAID 0/1/4/5)、信頼性とパフォーマンスのコストモデル。 - インデックス (
indexes/):B⁺ツリー、ビットマップインデックス(等価・範囲エンコード)、ブルームフィルター、Radixトライ、「クリスマスツリー」(ノードバッファ付きRadixトライ)。 - ビットシーケンス (
indexes/bit_sequences.py):ビットマップインデックスで使用されるプレーンおよびWAH圧縮ビットシーケンス。 - トランザクションストア (
stores/):バージョン管理されたキーバリューストアとMVCC(マルチバージョン同時実行制御)、ジャーナリング機能付き、インデックスも備えています。 - クエリ処理 (
query_processing/):スキャン、フィルター、ハッシュJOIN、セミJOIN、カウントなどの演算子、およびWHERE句述語。 - ソートとキュー (
query_processing/sorting.py,query_processing/queues/):インメモリおよびディスクバックのキューを備えた外部マージソート。 - クエリ最適化 (
query_optimization/):JOINグラフ(チェーン、スター、サイクル、クリーク)、カーディナリティ推定、C_outコスト関数、動的計画法によるJOIN順序付けのためのプランテーブル。
DBMS.py がこれらの部分を連携させます。ストア、準備済みクエリ、クエリ最適化を管理します。これらすべてに対する単体テストはsystem/tests/にあります。
ストアコアのRustへのAI生成ポート(開発中)はgenerated/rust/にあります。言語モデルがPythonコードから生成します(Pythonを変更してから再生成)。Rustの命名規則が許す範囲でPython名を使い、ポートされた部分のPythonテストのRust版も含まれます。詳細はgenerated/rust/README.mdを参照してください。ここには、両方のストアを比較するベンチマーク(benchmarks/)の説明も含まれています。
uv を使った環境設定
このリポジトリは、Pythonバージョンと依存関係の管理にuvを使用しています。uvは適切なPythonインタープリタを自動的にインストールするため、別途Pythonをインストールする必要はありません。
1. uv のインストール
-
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh -
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
代替手段(Homebrew, pipxなど)については、uvのインストールドキュメントを参照してください。
2. リポジトリのクローン
git clone https://github.com/explaindb/explaindb.git
cd explaindb
3. 依存関係のインストール
uv sync
これにより、.venv/に仮想環境が作成され、必要に応じてPython 3.12がインストールされ、uv.lockからすべての必要なパッケージがインストールされます。
4. Jupyter Notebook の実行
uv run jupyter notebook
これにより、現在のディレクトリのファイル一覧が表示されるブラウザウィンドウが開きます。ノートブックはnotebooks/ディレクトリにあります。そこから開いてください。プロジェクト環境内で任意のコマンドを実行するには、uv runを前に付けて実行します。手動での環境アクティベーションは不要です。
または、PyCharmのようなIDEでノートブックを実行することもできます。その場合、IDEのインタープリタをuvによって作成された.venv/に設定してください。
テストの実行
uv run python -m unittest discover system/tests/
APIドキュメント
ソースdocstringから生成されたAPIドキュメントは、オンラインでhttps://bigdata.uni-saarland.de/software/explaindb/index.htmlで利用可能です。ローカルでのビルド方法については、CONTRIBUTING.mdを参照してください。
貢献
コードフォーマット、docstring規約、依存関係、ノートブック、APIドキュメントのメンテナンス方法については、CONTRIBUTING.mdを参照してください。
ライセンス
ExplainDBはGNU Affero General Public License v3.0(AGPL-3.0)の下でライセンスされています。Copyright (C) 2026 Prof. Dr. Jens Dittrich, Saarland University。
貢献者
コミット数順:
AnthropicによるAIコーディングアシスタントであるClaudeの協力も得ており、コミットでは共同著者としてクレジットされています。