dimgigov
c95bc4cd44
- Add mcp.md to: bg, fa, ru, tr, zh, ar - Add index.md to Bulgarian (bg) - Add 24 missing German (de) documentation files Translations for all supported languages now complete.
153 lines
7.5 KiB
Markdown
153 lines
7.5 KiB
Markdown
# BaraDB Architektur
|
|
|
|
## Überblick
|
|
|
|
BaraDB ist eine **multimodale Datenbank-Engine** in Nim, die Document (KV), Graph, Vector, Columnar und Full-Text Search Speicherung in einer einzigen Engine mit einer einheitlichen Abfragesprache namens **BaraQL** kombiniert.
|
|
|
|
## Schichten-Architektur
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ 1. CLIENT LAYER │
|
|
│ Binary Protocol │ HTTP/REST │ WebSocket │ Embedded │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ 2. QUERY LAYER (BaraQL) │
|
|
│ Lexer → Parser → AST → IR → Optimizer → Codegen │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ 3. EXECUTION ENGINE │
|
|
│ Document │ Graph │ Vector │ Columnar │ FTS │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ 4. STORAGE │
|
|
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ 5. DISTRIBUTED │
|
|
│ Raft Consensus │ Sharding │ Replication │ Gossip │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Schicht 1: Client-Layer
|
|
|
|
Mehrere Kommunikationsprotokolle:
|
|
|
|
- **Binärprotokoll** (`protocol/wire.nim`): Effizientes Big-Endian Binärprotokoll mit 16 Nachrichtentypen
|
|
- **HTTP/REST** (`core/httpserver.nim`): JSON-basierte REST API mit Multi-Threading
|
|
- **WebSocket** (`core/websocket.nim`): Vollduplex-Streaming
|
|
- **Embedded** (`storage/lsm.nim`): Direkter In-Process-Zugriff
|
|
|
|
### Verbindungsmanagement
|
|
|
|
- **Connection Pool** (`protocol/pool.nim`): Min/Max Verbindungslimits mit Idle-Timeout
|
|
- **Rate Limiting** (`protocol/ratelimit.nim`): Token-Bucket globale und per-Client Limits
|
|
- **Authentifizierung** (`protocol/auth.nim`): JWT mit HMAC-SHA256 und rollenbasierter Zugriff
|
|
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 mit auto-generierten Zertifikaten
|
|
|
|
## Schicht 2: Query-Layer (BaraQL)
|
|
|
|
Die BaraQL-Pipeline:
|
|
|
|
1. **Lexer** (`query/lexer.nim`): Tokenisiert Eingabe in 80+ Tokentypen
|
|
2. **Parser** (`query/parser.nim`): Rekursiver Descent-Parser produziert AST
|
|
3. **AST** (`query/ast.nim`): 300+ Zeilen mit 25+ Knotenarten
|
|
4. **IR** (`query/ir.nim`): Intermediate Representation für Ausführungspläne
|
|
5. **Optimizer** (`query/adaptive.nim`): Adaptive Cross-Modal Query-Optimierung
|
|
6. **Codegen** (`query/codegen.nim`): Übersetzt IR zu Speicheroperationen
|
|
7. **Executor** (`query/executor.nim`): Führt Pläne mit Parallelisierung aus
|
|
|
|
### Cross-Modal Planning
|
|
|
|
Der Optimizer (`query/adaptive.nim`) bestimmt die Ausführungsreihenfolge über Engines:
|
|
|
|
```
|
|
1. Selektivität für jedes Prädikat schätzen
|
|
2. Selektivstes Prädikat zuerst an seine Engine pushen
|
|
3. Bloom-Filter für KV-Lookups verwenden
|
|
4. Unabhängige Zweige parallelisieren
|
|
5. Results streamen um Materialisierung zu vermeiden
|
|
```
|
|
|
|
## Schicht 3: Execution Engine
|
|
|
|
### Document/KV Engine
|
|
- **LSM-Tree** (`storage/lsm.nim`): Write-optimierte Speicherung mit MemTable, WAL, SSTables
|
|
- **B-Tree Index** (`storage/btree.nim`): Geordneter Index für Bereichsscans mit COW
|
|
|
|
### Vector Engine (`vector/`)
|
|
- **HNSW Index** (`vector/engine.nim`): Hierarchical Navigable Small World Graph
|
|
- **IVF-PQ Index** (`vector/engine.nim`): Inverted File Index mit Product Quantization
|
|
- **SIMD Operations** (`vector/simd.nim`): AVX2-optimierte Distanzberechnungen
|
|
- **Quantization** (`vector/quant.nim`): Scalar, Product und Binary Quantization
|
|
|
|
### Graph Engine (`graph/`)
|
|
- **Adjacency List** (`graph/engine.nim`): Kanten-gewichteter gerichteter Graph
|
|
- **Algorithmen** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
|
|
- **Community Detection** (`graph/community.nim`): Louvain-Algorithmus
|
|
- **Pattern Matching** (`graph/community.nim`): Subgraph-Isomorphie
|
|
- **Cypher Parser** (`graph/cypher.nim`): Cypher-ähnliche Graph-Abfragen
|
|
|
|
### Full-Text Search (`fts/`)
|
|
- **Inverted Index** (`fts/engine.nim`): Term-Document Index
|
|
- **Ranking** (`fts/engine.nim`): BM25 und TF-IDF Scoring
|
|
- **Fuzzy Search** (`fts/engine.nim`): Levenshtein-Distanz-Matching
|
|
- **Multi-Language** (`fts/multilang.nim`): Tokenizer für EN, BG, DE, FR, RU
|
|
|
|
### Columnar Engine (`core/columnar.nim`)
|
|
- Perspalten-Speicherung für analytische Abfragen
|
|
- RLE und Dictionary-Kodierung
|
|
- SIMD-beschleunigte Aggregatfunktionen
|
|
|
|
## Schicht 4: Storage
|
|
|
|
- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom-Filter, Compaction
|
|
- **Page Cache** (`storage/compaction.nim`): LRU-Cache mit Trefferraten-Verfolgung
|
|
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-basierter Dateizugriff
|
|
- **Recovery** (`storage/recovery.nim`): WAL-Replay und Crash-Recovery
|
|
|
|
### Write Path
|
|
|
|
```
|
|
Client → Protocol → Auth → Parser → AST → IR → Codegen
|
|
→ StorageOp → MVCC Txn → WAL Write → MemTable → Commit
|
|
```
|
|
|
|
### Read Path
|
|
|
|
```
|
|
Client → Protocol → Auth → Parser → AST → IR → Codegen
|
|
→ StorageOp → MVCC Snapshot → MemTable → SSTable → Result
|
|
```
|
|
|
|
## Schicht 5: Distributed
|
|
|
|
- **Raft Consensus** (`core/raft.nim`): Leader Election, Log-Replikation
|
|
- **Sharding** (`core/sharding.nim`): Hash, Range und Consistent Hashing
|
|
- **Replication** (`core/replication.nim`): Sync, Async, Semi-Sync Modi
|
|
- **Gossip Protocol** (`core/gossip.nim`): SWIM-ähnliches Membership-Management
|
|
- **Distributed Transactions** (`core/disttxn.nim`): Two-Phase Commit
|
|
|
|
## Wichtige Designentscheidungen
|
|
|
|
1. **Reines Nim**: Keine Cython, Python oder Rust Abhängigkeiten
|
|
2. **Unified Storage**: Eine Engine-handelt KV, Graph, Vector, FTS und Columnar
|
|
3. **Embedded Mode**: Kann als Bibliothek oder Server laufen
|
|
4. **Binärprotokoll**: Custom effizientes Wire-Protokoll
|
|
5. **MVCC**: Multi-Version Concurrency Control
|
|
6. **Schema-First**: Stark typisiertes Schema-System mit Vererbung
|
|
7. **Cross-Modal**: Einheitliche Abfragesprache über alle Datenmodelle
|
|
8. **Formally Verified**: Kern-Algorithmen in TLA+ spezifiziert und mit TLC model-gecheckt
|
|
|
|
## Modulstatistiken
|
|
|
|
| Kategorie | Module | Codezeilen | Zweck |
|
|
|----------|--------|------------|-------|
|
|
| Core | 16 | ~4,200 | Server, Protokolle, Transaktionen, Distributed |
|
|
| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, Bloom, Compaction, mmap |
|
|
| Query | 7 | ~2,800 | Lexer, Parser, AST, IR, Optimizer, Codegen, Executor |
|
|
| Vector | 3 | ~1,200 | HNSW, IVF-PQ, Quantization, SIMD |
|
|
| Graph | 3 | ~1,000 | Adjacency List, Algorithmen, Community Detection |
|
|
| FTS | 2 | ~900 | Inverted Index, BM25, Fuzzy, Multi-Language |
|
|
| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, Pool, Auth, Rate Limit, SSL |
|
|
| Schema | 1 | ~600 | Typen, Links, Vererbung, Migrationen |
|
|
| Client | 2 | ~800 | Nim Binary Client, File Helpers |
|
|
| CLI | 1 | ~400 | Interaktive BaraQL Shell |
|
|
| **Total** | **49** | **~14,100** | |
|