entity link

Setzt eine typisierte Beziehung von einer Entität zu einer anderen. Die Beziehung landet im Frontmatter der Quell-Entität als YAML-Mapping mit target-Schlüssel — das ist der stabile Anker für den späteren Graph, plus den Apparat-gepflegten Komfort-Feldern label und path.

Grundaufruf

apparat entity link V1StGXRa Qw9pLm2n --rel=works_at

Das fügt im Frontmatter von V1StGXRa den Eintrag:

works_at:
  target: Qw9pLm2n
  label: Organisation XY
  path: ./2023-05-01--organisation-xy--Qw9pLm2n.md

label wird aus dem title-Feld der Zielentität kopiert. Beim nächsten Schreiben von V1StGXRa durch Apparat (z.B. via entity edit, entity meta, entity rename) wird der Wert aktualisiert, falls sich der Titel von Qw9pLm2n geändert hat.

Mehrere Beziehungen desselben Typs

Fügst du dieselbe Beziehung nochmal mit einem anderen Ziel hinzu, wandelt Apparat das Feld in eine Liste um:

apparat entity link V1StGXRa Bx7tYu3v --rel=knows
apparat entity link V1StGXRa Fg6hJk4l --rel=knows

Ergibt:

knows:
  - target: Bx7tYu3v
    label: Max Mustermann
    path: ./2024-02-14--max-mustermann--Bx7tYu3v.md
  - target: Fg6hJk4l
    label: Anna Schmidt
    path: ./2025-08-09--anna-schmidt--Fg6hJk4l.md

Solange es nur einen Eintrag gibt, schreibt Apparat ihn als Top-Level-Mapping (ohne Listen-Wrapper). Ab dem zweiten Eintrag wird es eine Liste.

Interaktive Auswahl des Relations-Namens

Ohne --rel fragt Apparat interaktiv:

 ┌ Relation name
 │ ▀ works_at  knows  talks_about  references  …
 │

Autocomplete zeigt die Relations-Namen, die bereits im Vault verwendet werden — dieselbe Drift-Vermeidungs-Logik wie bei Typen und Tags. Gibst du eine abweichende Form ein (WorksAt, works at), normalisiert Apparat sie zu works_at und bietet gegebenenfalls die kanonische Vault-Schreibweise zur Übernahme an:

 "works_at" matches existing relation "works_at". Use the canonical spelling? [Y/n]

Auch wenn dein Beziehungsname nach der Normalisierung neu ist, prüft Apparat ihn gegen die existierenden — fängt etwa einen Tippfehler wie --rel=works_t gegen ein bestehendes works_at. Du bekommst eine Auswahl zwischen deiner Eingabe und dem ähnlichen Bestandswert. Im nicht-interaktiven Modus erscheint dasselbe als kurze Hinweiszeile, deine Beziehung wird mit der genuinen Schreibung gesetzt. Eine Übersicht aller Ähnlichkeits-Verfahren liegt in den Grundbegriffen.

Konventionen für Relations-Namen

Der Relations-Name folgt den Frontmatter-Key-Konventionen aus der Spec:

Englisch, kleingeschrieben, snake_case (works_at, knows, talks_about).
Verbhaft wo möglich (works_at statt employer, knows statt acquaintance).
Keine Umlaute, Bindestriche oder Leerzeichen.

Apparat normalisiert Drift auf dem Eingabe-Weg:

WorksAt / worksAt / WORKS_AT → works_at
works at / works-at → works_at

Fehlschläge auf dem Normalisierungs-Weg brechen den Import mit klarer Meldung ab. Reservierte Frontmatter-Keys (id, type, created, updated, language, title, tags, representations, external) kannst du nicht als Relations-Namen verwenden — das würde Apparat-Kernfelder überschreiben und wird abgelehnt.

Vault wählen

Wie üblich — ohne --vault übernimmt Apparat die Auflösung (CWD → einziger registrierter Vault → interaktive Auswahl), mit --vault=… explizit.

apparat entity link V1StGXRa Qw9pLm2n --rel=works_at --vault=arbeit

Kein automatischer Gegen-Link

Apparat legt bewusst keine automatische Gegenrichtung an. entity link V1StGXRa Qw9pLm2n --rel=works_at erzeugt works_at auf Maria, aber keinen employs-Eintrag auf Organisation XY. Das liegt daran, dass inverse Beziehungsnamen in der Spec nicht als Gegen-Paar definiert sind — es gibt kein works_at ↔ employs-Mapping. Wenn du die Gegenrichtung willst, setze sie explizit:

apparat entity link Qw9pLm2n V1StGXRa --rel=employs

Fehler

„Source/Target entity id "…" is not a valid NanoId" — die Positional-Argumente müssen 8-stellige NanoIDs aus [A-Za-z0-9] sein.
„No source/target entity with id "…" in vault "…"" — zur angegebenen NanoID existiert im Vault keine Entität.
„Source and target must be different entities" — entity link verbietet Self-Links.
„Entity "…" already has relation "…" to target "…"" — die Beziehung existiert bereits. Für Reorder oder Ersatz nutze entity meta zum manuellen Bearbeiten.
„--rel is required in non-interactive mode" — im Script-Modus muss --rel gesetzt sein.
„"…" is a reserved frontmatter key and cannot be used as a relation name" — du hast z.B. --rel=type versucht. Reservierte Keys sind tabu.
„"…" is not a valid snake_case relation name" — nach Normalisierung bleibt kein snake_case-konformer Name übrig.

Wirkung im Vault

entity link ändert ausschließlich das Frontmatter der Quelle — die Zielentität bleibt unverändert. Eine Beziehung wieder zu entfernen, ist Aufgabe von entity unlink. Apparat prüft auch nicht, ob eine Beziehung wie works_at zwischen den gewählten Typen sinnvoll ist — die Schemafreiheit gilt auch hier.