developers

Developers Guide

Stand: 5. Dezember 2025
Version: 1.0.0
Kategorie: Development

---

Dieser Leitfaden richtet sich an Entwicklerinnen und Entwickler, die am Themis Multi‑Modell‑Datenbanksystem mitarbeiten.

Inhalte

• Lokales Setup (Windows)
• Build & Test
• Projektstruktur
• Server starten & nützliche Endpunkte
• AQL / Traversal, EXPLAIN/PROFILE
• Coding‑Guidelines & Stil
• Debugging & Troubleshooting
• Benchmarks

---

Lokales Setup (Windows, PowerShell)

Voraussetzungen:

• Windows 10/11
• CMake >= 3.20
• MSVC (Visual Studio 2019+)
• vcpkg

Setup (aus dem Repo‑Root):

# Dependencies und Toolchain einrichten
.\scripts\setup.ps1

# Build (Release)
.\scripts\build.ps1

Optional: Manuelles CMake

mkdir build; cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build . --config Release
ctest -C Release

Tests ausführen

Nach einem Build liegen die Binaries in build/Release/.

# Unit/Integration Tests
& "c:\\VCC\\VCCDB\\build\\Release\\themis_tests.exe"

Der aktuelle Stand (28.10.2025): Alle Tests grün. Siehe todo.md für Details zu stabilisierten Testbereichen.

Server starten

# Start Server
& "c:\\VCC\\VCCDB\\build\\Release\\themis_server.exe" --config config\\config.json

Nützliche Endpunkte:

• GET /health – Liveness Probe
• GET /stats – Strukturierte Server‑ & RocksDB‑Statistiken (JSON)
• GET /metrics – Prometheus Text Format
• POST /query – JSON‑Query (Equality/Range)
• POST /query/aql – AQL Query (FOR/FILTER/SORT/LIMIT/RETURN, Traversals)
• POST /graph/traverse – Low‑Level Graph‑Traversal (BFS)

AQL & Traversal, EXPLAIN/PROFILE

• AQL unterstützt u. a. FOR/FILTER/SORT/LIMIT/RETURN.
• Traversals: FOR v,e,p IN min..max OUTBOUND start GRAPH 'g' RETURN v|e|p
• Filterfunktionen: ABS, CEIL, FLOOR, ROUND, POW, DATE_TRUNC, DATE_ADD/SUB, NOW
• Boolesche Logik inkl. XOR, Short‑Circuit Evaluation.
• Konservatives Pruning am letzten Level (v/e‑Prädikate vor Enqueue)
• Konstanten‑Vorprüfung: FILTER ohne v/e‑Referenzen werden einmalig geprüft.

Profiling:

• Request‑Body Flag "explain": true aktivieren.
• Siehe docs/aql_explain_profile.md für die Metriken (z. B. edges_expanded, pruned_last_level, filter_evaluations_total, filter_short_circuits, frontier_limit_hits, result_limit_reached, per‑depth‑Frontier).
• Designnotiz zu sicheren Pfad‑Constraints: docs/path_constraints.md.

Projektstruktur

include/        # Öffentliche Header (storage, index, query, server, utils)
src/            # Implementierung (api, storage, index, query, server)
docs/           # Dokumentation
benchmarks/     # Benchmarks
build/          # Build‑Artefakte
config/         # Beispielkonfigurationen

Wichtige Einstiegspunkte:

• src/server/http_server.cpp – HTTP Routen & AQL Ausführung
• include/query/query_engine.h / src/query/query_engine.cpp – Query Engine
• include/index/* – Indizes (Graph, Secondary, Vector)
• include/storage/* – Base Entity & RocksDB Wrapper

Coding‑Guidelines

• C++20, konsequente Nutzung von string_view, span wo sinnvoll
• Fehlerpfade mit StatusOr<T>/tl::expected (falls vorhanden) oder klare Rückgabewerte + Logging
• Threadsicherheit: Keine globalen Singletons ohne Schutz; bevorzugt RAII und klare Besitzverhältnisse
• Tests: GoogleTest; jeweils Happy‑Path + 1–2 Edge‑Cases
• Metriken: Für neue öffentliche Operationen sinnvolle Counters/Gauges

Debugging & Troubleshooting

• Logs: themis_server.log, vccdb_server.log im Repo‑Root
• RocksDB Pfade in config/config.json prüfen (relative Pfade unter Windows empfohlen)
• Bei /stats und /metrics prüfen, ob RocksDB‑Werte plausibel sind
• Graph/AQL: Bei großen Traversals max_frontier_size und max_results im AQL‑Request setzen

Benchmarks

# CRUD Benchmark
& "c:\\VCC\\VCCDB\\build\\Release\\bench_crud.exe"

# Query Benchmark
& "c:\\VCC\\VCCDB\\build\\Release\\bench_query.exe"

# Vector Search Benchmark
& "c:\\VCC\\VCCDB\\build\\Release\\bench_vector_search.exe"

Beiträge & Workflow

• Branch vom main erstellen, PR mit kurzen, fokussierten Commits
• PR‑Checks: Build + Tests müssen PASS sein
• Dokumentation aktualisieren (README, docs/*, ggf. developers.md)
• Roadmap‑Updates in todo.md (Abschnitt thematisch verlinken)