std.graphdb

In-Memory-Graphdatenbank mit Labels, typisierten Properties, f64-Vektoren und drei Indizes (temporal, typ-basiert, Vektor-Ähnlichkeit). Persistenz über ein kompaktes Binärformat (LYXGDB). Enthält eine Graph-RAG-Funktion für KI-gestützte Kontextsuche (Vektorsuche + BFS-Traversal).

Einsatzbereiche: Wissensgraphen, semantische Suche, Empfehlungssysteme, temporale Ereignisgraphen, KI-Kontext (RAG).

→ Standard Library · std.db · std.hash · std.alloc · std.ml

std.graphdb.core          IDs, Timestamps
       │
  ┌────┴────┐
node      edge            Knoten + Kanten mit TLV-Properties
  └────┬────┘
      mem                 In-Memory-Store + Adjazenzliste
       │
     index                TemporalIndex · TypeIndex · VectorIndex
       │
  ┌────┴────┐
query      file           High-Level Query-API · Datei-Persistenz

Jedes Sub-Modul wird separat importiert:

import std.graphdb.core;
import std.graphdb.node;
import std.graphdb.edge;
import std.graphdb.mem;
import std.graphdb.index;
import std.graphdb.file;
import std.graphdb.query;

import std.graphdb.core;

GRAPH_ID_INVALID = 0 — ungültige/leere ID.

GraphIDFromStr erzeugt immer denselben Wert für denselben String — geeignet für stabile Knoten-IDs aus externen Bezeichnern.

import std.graphdb.node;

Ein Node ist ein alloc(GNODE_SIZE) Puffer (80 Bytes). Der Caller verwaltet das Speicherlayout und setzt die ID manuell:

var n: int64 := alloc(GNODE_SIZE);
GraphNodeInit(n);
poke64(n + GNODE_OFF_ID, GraphIDNew());    // ID muss explizit gesetzt werden

Labels sind kurze Typbezeichner (z.B. Person, Article). Intern \\0-getrennt in einem wachsenden Puffer.

Properties sind typisierte Schlüssel-Wert-Paare, intern als TLV-Stream kodiert.

Für GraphNodeSetF64 muss der f64-Wert als int64-Bitmuster übergeben werden:

var bits: int64 := 3.14 as int64;    // IEEE-754-Bits von 3.14
GraphNodeSetF64(n, "score"c, 5, bits);

GraphNodeGetStr gibt einen direkten Pointer in den internen Prop-Puffer zurück — gültig bis zum nächsten GraphNodeSetStr-Aufruf für denselben Node.

data muss ein Puffer mit dims × 8 Bytes (f64-Array) sein. Vorhandener Vektor wird ersetzt.

import std.graphdb.edge;

Eine Kante verbindet zwei Nodes per ID und hat einen Typ-String sowie TLV-Properties.

var e: int64 := alloc(GEDGE_SIZE);
GraphEdgeInit(e);
poke64(e + GEDGE_OFF_ID,        GraphIDNew());
poke64(e + GEDGE_OFF_SOURCE,    srcNodeId);
poke64(e + GEDGE_OFF_TARGET,    tgtNodeId);
poke64(e + GEDGE_OFF_CREATEDAT, GraphNow());    // Pflicht vor AddEdge!
GraphEdgeSetType(e, "KNOWS"c, 5);

Identische Signaturstruktur wie bei Nodes:

import std.graphdb.mem;

Verwaltet Nodes und Kanten in parallelen ID/Pointer-Arrays und einer Adjazenzliste (source-ID → edge-ID).

var s: int64 := alloc(GMEM_SIZE);
GraphMemStoreInit(s);

createdAt muss vor GraphMemStoreAddEdge gesetzt sein — der Store prüft peek64(e + GEDGE_OFF_CREATEDAT) != 0.

outBuf muss maxOut × 8 Bytes groß sein. Zurückgegeben wird die tatsächliche Anzahl gefundener Einträge.

import std.graphdb.index;

Drei unabhängige Indizes, die nach dem Befüllen des Stores mit *Build aufgebaut werden.

Sortierter Index über createdAt-Timestamps. Ermöglicht Zeitfenster-Abfragen.

Hash-basierter Index über den Kanten-Typ-String.

Cosinus-Ähnlichkeitssuche über Node-Embedding-Vektoren. Nur Nodes mit Vektor (GraphNodeSetVec) werden indiziert.

queryVec ist ein dims × 8 Byte großer int64-Puffer mit den f64-Rohdaten des Query-Vektors (als int64-Bitmuster).

outNodeIds und outScores müssen je topK × 8 Bytes groß sein.

import std.graphdb.file;

Binäres Dateiformat mit Magic LYXGDB\x01\x00. Speichert alle Nodes und Kanten inklusive Labels, Properties und Vektoren.

Dateiformat:

[Magic: 8B "LYXGDB\x01\x00"][nodeCount:8][edgeCount:8][flags:8]
pro Node: [id:8][labelsLen:8][labelsCount:8][propsLen:8][vecDims:8] + Daten
pro Edge: [id:8][source:8][target:8][edgeTypeLen:8][createdAt:8][propsLen:8] + Daten

GraphFileLoad ruft intern GraphMemStoreAddNode und GraphMemStoreAddEdge auf — der Store muss vorher mit GraphMemStoreInit initialisiert sein.

import std.graphdb.query;

High-Level Query-Kontext kombiniert Store + Indizes. Ein GraphQueryCtx (GQCTX_SIZE = 32 Bytes) verweist auf alle Komponenten.

var ctx: int64 := alloc(GQCTX_SIZE);
GraphQueryCtxInit(ctx, store);
GraphQueryCtxSetTemporalIdx(ctx, tidx);   // optional
GraphQueryCtxSetTypeIdx(ctx, typeidx);    // optional
GraphQueryCtxSetVectorIdx(ctx, vidx);     // optional

Um die 7-Argument-Grenze des Compilers zu umgehen, werden Pattern-Parameter in einem GQPAT_SIZE-Struct (32 Bytes) übergeben:

var pat: int64 := alloc(GQPAT_SIZE);
GraphQueryPatternInit(pat, srcNodeId, "KNOWS"c, 5);
GraphQueryPatternSetTs(pat, GraphNow() - 86400000);   // nur Kanten der letzten 24h (optional)
var out: int64 := alloc(100 * 8);
var found: int64 := GraphQueryPattern(ctx, pat, out, 100);

Kombiniert Vektorsuche mit BFS-Traversal für KI-Kontext-Retrieval:

// topK ähnlichste Knoten finden + depth Hops Umfeld einsammeln
var out: int64 := alloc(maxOut * 8);
var cnt: int64 := GraphGetContextForAI(ctx, queryVec, topK, depth, out, maxOut);

Ablauf intern:

1. GraphVectorIndexSearch → topK semantisch ähnliche Start-Nodes
2. BFS: für jeden aktuellen Node → GraphMemStoreNeighbors → Nachbarn einsammeln
3. Wiederholt depth Mal; bereits besuchte Nodes werden nicht doppelt ausgegeben

import std.graphdb.core;
import std.graphdb.node;
import std.graphdb.edge;
import std.graphdb.mem;
import std.graphdb.index;
import std.graphdb.file;
import std.graphdb.query;
import std.alloc;

fn main(): int64 {
    // Store anlegen
    var s: int64 := alloc(GMEM_SIZE);
    GraphMemStoreInit(s);

    // Nodes anlegen
    var n1: int64 := alloc(GNODE_SIZE);
    GraphNodeInit(n1);
    poke64(n1 + GNODE_OFF_ID, GraphIDFromStr("alice"c, 5));
    GraphNodeAddLabel(n1, "Person"c, 6);
    GraphNodeSetStr(n1, "name"c, 4, "Alice"c, 5);
    GraphNodeSetInt(n1, "age"c, 3, 30);
    GraphMemStoreAddNode(s, n1);

    var n2: int64 := alloc(GNODE_SIZE);
    GraphNodeInit(n2);
    poke64(n2 + GNODE_OFF_ID, GraphIDFromStr("bob"c, 3));
    GraphNodeAddLabel(n2, "Person"c, 6);
    GraphNodeSetStr(n2, "name"c, 4, "Bob"c, 3);
    GraphMemStoreAddNode(s, n2);

    // Kante anlegen
    var e: int64 := alloc(GEDGE_SIZE);
    GraphEdgeInit(e);
    poke64(e + GEDGE_OFF_ID,        GraphIDNew());
    poke64(e + GEDGE_OFF_SOURCE,    peek64(n1 + GNODE_OFF_ID));
    poke64(e + GEDGE_OFF_TARGET,    peek64(n2 + GNODE_OFF_ID));
    poke64(e + GEDGE_OFF_CREATEDAT, GraphNow());
    GraphEdgeSetType(e, "KNOWS"c, 5);
    GraphEdgeSetInt(e, "since"c, 5, 2020);
    GraphMemStoreAddEdge(s, e);

    // TypeIndex aufbauen und abfragen
    var tidx: int64 := alloc(GXIDX_SIZE);
    GraphTypeIndexInit(tidx);
    GraphTypeIndexBuild(tidx, s);

    var out: int64 := alloc(64 * 8);
    var found: int64 := GraphTypeIndexQuery(tidx, "KNOWS"c, 5, out, 64);
    // found = 1 (eine KNOWS-Kante)

    // Traversal: Nachbarn von n1
    var nb: int64 := alloc(64 * 8);
    var ncnt: int64 := GraphMemStoreNeighbors(s, peek64(n1 + GNODE_OFF_ID), nb, 64);
    // ncnt = 1 (Bob)

    // Persistenz
    GraphFileSave(s, "graph.lyxgdb"c, 12, 0);

    // Aufräumen
    GraphTypeIndexFree(tidx);
    free(tidx, GXIDX_SIZE);
    GraphNodeFree(n1); free(n1, GNODE_SIZE);
    GraphNodeFree(n2); free(n2, GNODE_SIZE);
    GraphEdgeFree(e);  free(e, GEDGE_SIZE);
    free(nb, 64 * 8);
    free(out, 64 * 8);
    GraphMemStoreFree(s);
    free(s, GMEM_SIZE);
    return 0;
}

• Speicherverwaltung: Alle Structs sind rohe alloc-Puffer — kein automatisches GC. GraphNodeFree/GraphEdgeFree geben die internen Puffer frei; der Struct-Puffer selbst muss mit free(ptr, GNODE_SIZE) etc. separat freigegeben werden. GraphMemStoreFree gibt nur die internen Arrays frei, nicht die Nodes/Kanten selbst.
• f64-Properties: GraphNodeSetF64 und GraphEdgeSetF64 erwarten IEEE-754-Bitmuster als int64. Konvertierung: var bits: int64 := myFloat as int64;
• TLV-Properties: Schlüssellänge ist auf 255 Bytes begrenzt (1 Byte im TLV-Header). Für längere Schlüssel ist GraphNodeSetStr mit einem Hash-Key zu bevorzugen.
• Indizes sind nicht live: GraphTemporalIndexBuild, GraphTypeIndexBuild und GraphVectorIndexBuild erzeugen einen Snapshot. Nach weiteren AddNode/AddEdge-Aufrufen muss der Index neu aufgebaut werden.
• VectorIndex-Score: GraphVectorIndexSearch gibt Cosinus-Ähnlichkeit × 1 000 000 als int64 zurück (absteigend sortiert). Score 1 000 000 = identische Vektoren.
• Edge-Voraussetzungen: Source- und Target-Node müssen beim GraphMemStoreAddEdge bereits im Store sein. createdAt muss ≠ 0 sein.

Letzte Aktualisierung: 2026-06-14