entity search

entity search findet Entitäten im aktuellen Vault. Drei Modi sind verfügbar — Volltext (Standard), Bedeutungssuche (--semantic) und eine kombinierte Suche aus beiden (--hybrid).

Eine Einordnung der Verfahren in die anderen Ähnlichkeits-Konzepte von Apparat steht in den Grundbegriffen.

Volltextsuche (Standard)

apparat entity search barrierefreiheit

Apparat sucht den Begriff in Titel, Tags und Fließtext aller Notizen. Treffer werden nach Relevanz sortiert — Titel-Treffer stehen vor Tag-Treffern, diese vor Body-Treffern, sodass die offensichtlichsten Fundstellen oben landen. Die Ausgabe hat dieselbe Spaltenform wie entity list, nur sortiert nach Relevanz statt alphabetisch:

Vault "recherche" — full-text matches for "barrierefreiheit":

Vault "recherche" — 3 entities
+-----------------------------+----------+----------+----------------------+----------------------------------------+
| Title                       | Type     | Id       | Tags                 | File                                   |
+-----------------------------+----------+----------+----------------------+----------------------------------------+
| Barrierefreiheit Recherche  | document | aaaaaaa1 | wcag                 | 2026-04-10--barrierefreiheit--…1.md    |
| Maria Beispiel              | person   | V1StGXRa | wcag, barrierefreih… | 2024-02-14--maria-beispiel--V1StGXRa.md|
| Notiz zu Schriftarten       | note     | NoTeX001 | typografie           | 2026-03-02--notiz-schrift--NoTeX001.md |
+-----------------------------+----------+----------+----------------------+----------------------------------------+

Die Suche ignoriert Groß-/Kleinschreibung und Diakritika: Barriere findet barriere, barrière und Barrière. Jeder Suchbegriff wirkt zusätzlich als Wortanfang, sodass barriere auch Barrierefreiheit findet. Mehrere Begriffe werden mit logischem UND verknüpft: apparat entity search "barriere recherche" verlangt beide Wörter, in irgendeiner Reihenfolge.

Operatoren im Suchtext

Der Suchtext versteht dieselben Operatoren wie das Suchfeld der Weboberfläche — du kannst Struktur- und Volltext-Filter direkt in einen String mischen:

apparat entity search "type:project tag:wcag created:>2025-01"

Operator	Wirkung
`type:project`	Nur Entitäten dieses Typs.
`tag:wcag` bzw. `#wcag`	Nur Entitäten mit diesem Tag.
`lang:de`	Nur Entitäten in dieser Inhaltssprache.
`created:2025-04` / `created:>2025-01` / `created:<7d`	Anlagedatum: ganzes Jahr, Monat oder Tag; mit `>`/`<` als offener Vergleich; `7d`/`2w`/`3m` relativ zu heute.
`id:V1StGXRa`	Direkter Griff auf eine NanoID. Eine allein eingegebene NanoID springt sofort zur Entität.
`links:maria-beispiel`	Nur Entitäten, die auf das Ziel verweisen (Slug, NanoID oder Dateiname).
`linked-by:apparat-projekt`	Nur Entitäten, auf die das genannte Ziel verweist.
`"barrierefreie formulare"`	In Anführungszeichen als zusammenhängende Wortfolge.
`barriere OR kontrast`	Eines der beiden Wörter genügt (ODER).
`-tag:entwurf` / `-veraltet`	Führendes `-` schließt Tag, Typ, Ziel oder Wort aus.

Gleiche Operatoren wirken untereinander als ODER (type:project type:document = Projekte oder Dokumente), verschiedene als UND (type:project tag:wcag = Projekt und wcag-getaggt). Die Flags --type und --tag sind Kurzform für ein vorangestelltes type:/tag: und lassen sich mit den Inline-Operatoren frei kombinieren.

Option	Bedeutung
`--limit=<n>`	Maximalanzahl der ausgegebenen Zeilen (Standard 10).
`--type=<t>`	Filter: nur Entitäten dieses Typs werden ausgegeben.
`--tag=<t>`	Filter: nur Entitäten mit diesem Tag.

Die Filter wirken nach der eigentlichen Suche — bei sehr engen Filtern kann es passieren, dass weniger als --limit Zeilen zurückkommen. In dem Fall einfach --limit höher setzen.

Hinweis: Die Volltextsuche braucht einen aufgebauten Graph-Index. Ein Vault ohne Graph-Index liefert „(no matches)" — Lösung: einmal apparat graph rebuild --vault=… laufen lassen.

Bedeutungssuche (`--semantic`)

apparat entity search "barrierefreie web-formulare" --semantic

Mit --semantic sucht Apparat nicht nach Wörtern, sondern nach Bedeutung. Eine Anfrage „barrierefreie Web-Formulare" findet auch eine Notiz mit dem Titel „WCAG-Kontrastregeln" — dieselbe Sache, andere Worte. Treffer kommen nach Distanz sortiert (kleiner = thematisch näher):

Vault "recherche" — semantic matches for "barrierefreie web-formulare":

  V1StGXRa  Maria Beispiel              person        d=0.3214  (title)
  Qw9pLm2n  Beispiel-Organisation       organization  d=0.4502  (body)
  …

Sinnvoll, wenn der Begriff im Vault gar nicht wörtlich auftaucht oder du nicht mehr weißt, wie du eine Notiz benannt hast.

Voraussetzungen:

Der Vektor-Index muss befüllt sein — siehe vector rebuild, vector stats.
Der Embedding-Dienst muss erreichbar sein — siehe vector ping. Die Anfrage selbst wird zur Laufzeit übersetzt.

Option	Bedeutung
`--limit=<n>`	Maximalanzahl der ausgegebenen Zeilen (Standard 10).
`--type=<t>`	Vorfilter: Nur Entitäten dieses Typs werden bewertet.
`--tag=<t>`	Vorfilter: Nur Entitäten mit diesem Tag werden bewertet.

Im Bedeutungs-Modus wirken --type und --tag als Vorfilter: Apparat wählt zuerst die Kandidaten anhand des Filters und sortiert dann nur diese nach Bedeutungs-Nähe. Praktischer Effekt: Bei engen Strukturfiltern (etwa „die einzigen drei Notizen vom Typ document") bleibt das Ergebnis konsistent gefüllt, statt durch einen zu kleinen Kandidaten-Pool abgeschnitten zu werden. Beide Filter sind kombinierbar (Schnittmenge): --type=person --tag=team-intern sucht nur unter Personen, die zusätzlich team-intern getaggt sind.

Kombinierte Suche (`--hybrid`)

apparat entity search "barrierefreie web-formulare" --hybrid

Mit --hybrid läuft Apparat beide Such-Pfade parallel — Volltext und Bedeutung — und mischt die Ergebnisse fair zusammen. Wer in einer der beiden Listen weit vorne steht, taucht auch im Mix oben auf:

Vault "recherche" — hybrid matches for "barrierefreiheit":

  V1StGXRa  Maria Beispiel              person          s=0.0331  fts+vec   (title)
  Qw9pLm2n  Beispiel-Organisation       organization    s=0.0167  vec only  (body)
  AzZyMnEc  Notiz zu Barrierefreiheit   note            s=0.0164  fts only  (title-fts)

Die Spalte fts+vec / fts only / vec only macht sichtbar, woher der Treffer kommt: Stichwort-Treffer ohne thematische Nähe (fts only) und thematisch passende Treffer ohne Stichwort (vec only) werden gemeinsam gerankt, nicht gegeneinander ausgespielt.

Voraussetzungen:

Der Vektor-Index muss befüllt sein.
Der Embedding-Dienst muss erreichbar sein.
Der Graph-Index ist Teil von Apparat und entsteht beim ersten graph rebuild; ein Vault ohne Graph-Index liefert nur Bedeutungs-Treffer.

Die Optionen --limit, --type, --tag wirken wie im Bedeutungs-Modus.

--semantic und --hybrid schließen sich gegenseitig aus — wer beide setzt, bekommt einen klaren Fehler.

Filter kombinieren (Volltextsuche)

Im Standardmodus sind Typ- und Tag-Filter direkt durchgereicht:

# Alle Artikel, in denen "wcag" vorkommt (Titel, Tags oder Body)
apparat entity search wcag --type=article

# Alle Notizen mit Tag "recherche", in denen "maria" auftaucht
apparat entity search maria --tag=recherche

Vault-Wahl

Wie bei allen anderen Kommandos:

apparat entity search wcag --vault=arbeit
apparat entity search "barrierefreie web-formulare" --semantic --vault=./mein-vault

Ohne --vault greift der übliche Auflösungs-Mechanismus (aktuelles Verzeichnis, einzelner registrierter Vault, interaktive Auswahl).

Verwandt

Ähnlichkeit — wann Volltext, wann Bedeutung, wann beides; und welche Lücke heute noch offen ist (Tippfehler-Toleranz im Suchfeld).
entity similar — die „zeig mir Entitäten ähnlich zu DIESER" Variante. Statt eines Suchtexts gibst du eine NanoID.
vector drift — wenn --semantic weniger Treffer liefert als erwartet, ist möglicherweise der Vektor-Index unvollständig.

Fehler

„Search term must not be empty" — Das positionale Argument fehlt oder besteht nur aus Leerzeichen.
--semantic ohne erreichbaren Embedding-Dienst — Die Anfrage kann nicht in Bedeutung übersetzt werden; siehe vector ping.
--limit mit nicht-numerischem oder Null-/Negativ-Wert — Apparat bricht mit Code 1 ab.