2025 11 11 temporal aggregation

Release Notes — Temporal Aggregation Support

Stand: 5. Dezember 2025
Version: 1.0.0
Kategorie: Release Notes

---

Datum: 11. November 2025 Autor: Entwickler-Repository-Commit

Kurzfassung

Dieses Release ergänzt die temporalen Abfragefunktionen der ThemisDB um serverseitige Aggregationen über Zeitfenster. Neu ist die API aggregateEdgePropertyInTimeRange in GraphIndexManager, die es erlaubt, numerische Kanten-Eigenschaften (z. B. cost, _weight) über eine Menge von Kanten zusammenzufassen (COUNT, SUM, AVG, MIN, MAX). Zusätzlich wurden Tests und Dokumentation ergänzt sowie kleinere Robustheits­fixes am Key-Leseverhalten implementiert.

Status: Produktiv bereit (Lokale Tests: Build + Unit-Tests erfolgreich)

---

Was neu ist

• API: GraphIndexManager::aggregateEdgePropertyInTimeRange(...)
  • Aggregationstypen: COUNT, SUM, AVG, MIN, MAX
  • Zeitfenster-Parameter: range_start_ms, range_end_ms
  • Optional: require_full_containment (nur vollständig enthaltene Kanten) und edge_type (Filter auf _type)
• Unit-Tests: tests/test_temporal_aggregation_property.cpp (4 Tests)
• Dokumentation: docs/temporal_time_range_queries.md erweitert, neue Release-Notes
• Robustheit: Lesepfade für Edge-Entitäten wurden gehärtet (Versuch, sowohl edge:<graphId>:<edgeId> als auch edge:<edgeId> zu lesen)

---

API (Kurzreferenz)

Signatur:

std::pair<GraphIndexManager::Status, GraphIndexManager::TemporalAggregationResult>
aggregateEdgePropertyInTimeRange(
    std::string_view property,
    GraphIndexManager::Aggregation agg,
    int64_t range_start_ms,
    int64_t range_end_ms,
    bool require_full_containment = false,
    std::optional<std::string_view> edge_type = std::nullopt
) const;

Rückgabe: TemporalAggregationResult { size_t count; double value; } —

• Für COUNT ist count die Anzahl der passenden Kanten (value wird 0 setzen).
• Für SUM/AVG/MIN/MAX ist count die Anzahl der Kanten mit numerischem Property, value das berechnete Aggregat.

Beispiel (C++):

auto [st, res] = graph.aggregateEdgePropertyInTimeRange(
    "cost",
    GraphIndexManager::Aggregation::SUM,
    1000, 2000,
    false,
    std::string_view("A")
);
if (st.ok) {
    std::cout << "count=" << res.count << " sum=" << res.value << "\n";
}

---

Implementierungsdetails / Hinweise

• Die Implementierung scannt die Adjazenz-Indices (graph:out:) und lädt pro gefundenem Edge die zugehörige Edge-Entity, um valid_from/valid_to und das numerische Property zu prüfen.
• Aus Kompatibilitätsgründen wird beim Laden der Entity zuerst der Key edge:<graphId>:<edgeId> versucht; falls nicht vorhanden, wird edge:<edgeId> als Fallback gelesen. Dies behebt Inkonsistenzen zwischen älteren und neueren Key-Formaten.
• Performance: Der globale Scan ist O(E) (E = Anzahl aller Kanten). Für High-Scale-Szenarien sind in zukünftigen Releases temporale Indizes oder ein Iterator/Streaming-API geplant.

---

Tests & Verifikation

Neu hinzugefügte Tests:

• tests/test_temporal_aggregation_property.cpp
  • Testfälle: SUM/AVG/MIN/MAX ohne Type, COUNT aller Kanten, Type-Filter (A), nonexistent property

Empfohlener lokaler Ablauf zum Verifizieren:

# Build (PowerShell)
.\build.ps1

# Run focused tests
.\build\Release\themis_tests.exe --gtest_filter=TemporalAggregationProperty*

In meiner Testausführung (Windows / MSVC) waren alle 4 Tests erfolgreich (PASS).

---

Geänderte Dateien (Übersicht)

• src/index/graph_index.cpp —
  • Implementierung von aggregateEdgePropertyInTimeRange
  • Fallback-Lesen von Edge-Entities
  • Anpassungen an getEdgeType_() und getEdgeWeight_() (robustes Lesen beider Key-Formate)
• tests/test_temporal_aggregation_property.cpp — Neue Unit-Tests
• CMakeLists.txt — Test-Registrierung (Hinzufügen der neuen Testdatei)
• docs/temporal_time_range_queries.md — Doku erweitert (API + Beispiele + Changelog)
• README.md — Kurzhinweis in "Recent changes"

---

Kompatibilität & Migration

• Die API ist rückwärtskompatibel; bestehende Codepfade, die Edges unter edge:<edgeId> ablegen, funktionieren weiterhin.
• Der Key-Fallback macht die Funktion tolerant gegenüber Mix aus alten und neuen Key-Formaten.
• Falls du in deinem Deployment ausschließlich das Format edge:<graphId>:<edgeId> verwenden willst, ist keine Aktion nötig. Umgekehrt sind keine Migrationsschritte erforderlich.

---

Empfehlungen & nächste Schritte

• Wenn du häufig globale Zeitfenster-Aggregationen ausführst, plane eine temporale Indexstruktur (B-Tree o.ä.), um O(E)-Scans zu vermeiden.
• Füge ein Streaming/Iterator-API hinzu, wenn Result-Sets sehr groß werden. Das reduziert Speicherbedarf auf der Serverseite.
• Überlege, ob Edge-Entities zentral ein Key-Format vereinheitlicht werden sollen (z. B. per Migrations-Tool). Der Fallback ist robust, aber ein einheitliches Format reduziert Missverständnisse.

---

Wenn du möchtest, erstelle ich daraus einen Git-Branch + PR-Text (Titel + beschreibende Commit-Message) und bereite die Änderungen für Review vor. Soll ich das erledigen?