graph

Der graph-Namespace versammelt die Kommandos, mit denen du den Beziehungs-Graph eines Vaults direkt ansprichst — Apparats internen Lese-Index, der aus deinen Markdown-Dateien aufgebaut wird. Mehr zum Modell der einzelnen Entität steht in den Grundbegriffen.

Grundgedanke

Der Graph ist abgeleitet, nicht primär: Wahrheit sind die Dateien, der Graph ist ein schneller Lesezugriff darauf. Eine korrupte oder gelöschte Graph-Datei ist ein Betriebs­ereignis, kein Datenverlust — graph rebuild stellt sie jederzeit aus den Dateien wieder her.

Solange du mit dem Dateisystem arbeitest (neue Datei anlegen, umbenennen, löschen), hält die Datei­beobachtung (graph watch, nur im Docker-Container) den Graph laufend aktuell. Auf dem Host oder wenn die Datei­beobachtung gerade nicht läuft, hält Apparat den Graph über zwei Mechanismen aktuell:

1. Bei jedem apparat-Aufruf prüft das Kommando, was sich seit dem letzten Mal an Dateien geändert hat, und zieht die Änderungen selektiv nach. Externe Bearbeitungen (Finder, git pull, anderer Editor) landen so bei der nächsten Nutzung automatisch im Graph.
2. Beim Start der Datei­beobachtung läuft derselbe Abgleich einmal vorab — der Watcher holt damit alles nach, was passiert ist, während er nicht lief.

Verfügbare Kommandos

• graph rebuild — den Graph eines Vaults vollständig aus content/ und assets/ neu aufbauen. Idempotent und wiederaufnahmefähig.
• graph watch — Datei­beobachtung im Container: hält den Graph laufend synchron, mit kleinem Wartezeit­fenster gegen Doppel-Events vom Editor.
• graph stats — Zusammenfassung des Graphs: Knoten-Zahlen, Typ- und Beziehungs-Verteilung, Dateigröße.

Graph als Lesequelle (opt-in)

Per Default ziehen Apparat-Kommandos ihre Liste der Entitäten, Typen, Tags und Sprachen aus dem Dateisystem — die Dateien sind die Wahrheit, der Graph ist nur Beschleuniger. Wer einen sehr großen Vault hat und den Graph-Index bereits nutzt, kann die Lesepfade umschalten:

APPARAT_VAULT_INDEX_DRIVER=graph apparat entity list

oder dauerhaft in der .env:

APPARAT_VAULT_INDEX_DRIVER=graph

Die Einschränkung: Der Graph muss für korrekte Reads aktuell sein. Im Container erledigt das der graph watch-Daemon. Auf dem Host bleibt filesystem der empfohlene Default, weil externe Änderungen den Graph auf graph-Treiber sonst unbemerkt veralten lassen würden.

Trash, Tombstones und Scan-Diagnosen kommen unabhängig vom Treiber immer vom Dateisystem — dort liegt die Wahrheit, der Graph führt sie nicht.

Was du im Graph findest

Der Graph enthält zwei Arten von Knoten und eine Reihe von Kanten:

• Entitäts-Knoten — je eine Markdown-Datei unter content/. Tragen Typ, Titel, Anlagedatum, Sprache sowie die freien Frontmatter-Felder, die nicht als Beziehungen erkannt wurden.
• Asset-Knoten — je eine Binärdatei unter assets/. Tragen den Anzeigenamen; weitere Metadaten leben auf den verknüpfenden Entitäten.
• Kanten — gerichtet und benannt:
  • Frontmatter-Beziehungen wie works_at, knows, references (Feld­namen werden zum Kanten­namen).
  • references aus Fließtext-Links.
  • embeds aus eingebetteten Asset-Verweisen (![](../assets/…)).

Wenn du selbst in den Graph schauen willst: die Datei liegt unter <vault>/.apparat/graph.sqlite und lässt sich mit jedem SQLite-Werkzeug öffnen. Das ist eine Notsicht — für die tägliche Arbeit nimmst du die Apparat-Kommandos.