Skip to main content
POST /v1/namespaces/{ns}/search führt bis zu drei gerankte Zweige über einer gefilterten Zeilenmenge aus. Alle Zweige sind optional; mindestens einer ist erforderlich. label und filter gelten für jeden Zweig.
Response – eine unabhängige gerankte Liste pro Zweig, mit In-Server-Ausführungszeit:

​
Filter

Zwei Formen werden akzeptiert:
  • Einzelne Gleichheit: {"property": "project", "value": "conare"} – direkt aus den Posting-Listen bedient.
  • Array-DSL: [property, op, value] mit Eq, NotEq, Gt, Gte, Lt, Lte, In (Array-Wert), kombinierbar mit ["And", [f1, f2, ...]] / ["Or", [...]] bis zu 16 Ebenen tief.
Der Vergleich ist typisiert: Zahlen vergleichen numerisch, Strings lexikografisch (Byte-Reihenfolge), Bools als false < true. Ein Typ-Mismatch oder eine fehlende Property matcht nichts – auch bei NotEq – und wirft nie einen Fehler. Unbekannte Operatoren, leere And-/Or-Listen und Nicht-Array-In-Werte ergeben 400 und nennen den Übeltäter.

​
Vektor-Zweig

Scores sind Kosinus-Ähnlichkeit auf L2-normalisierten Vektoren und stets exakt – der ANN-Index (IVF + RaBitQ-1-Bit-Codes) erstellt eine Shortlist der Kandidaten und rerankt sie anschließend gegen Vektoren voller Präzision. Optionen: Gefilterte Vektorsuche liefert genau die ANN-Ergebnisse der passenden Teilmenge – die Engine erweitert das Probing, um die Selektivität auszugleichen, sodass Filter dich nicht heimlich Recall kosten. Determinismus: Für einen fixen Indexzustand liefern identische Query-Bytes mit identischen Knöpfen bytegleiche Trefferlisten – bei beliebiger Thread-Zahl oder Nebenläufigkeit. Im Hintergrund spielt ein kontinuierlicher Sampler ~1 % der ANN-Queries gegen die Brute-Force-Wahrheit ab und veröffentlicht den Recall; der credential-freie GET /recall-slo-Endpunkt meldet die Recall-Gesundheit der Flotte.

​
Keyword-Zweig

BM25 (k1=1.2, b=0.75) über die text-Property. Tokenizer: kleinschreiben, an jedem nicht-alphanumerischen Zeichen splitten – kein Stemming, keine Stoppwörter (Wort-Tokenizer-Parität mit Turbopuffer). match steuert die Token-Kombination:
  • "auto" (Standard) – alle Tokens erforderlich; ergibt das weniger als max(5, top_k/8) Treffer, nochmal als Any-Token versuchen. Die Response meldet, welcher Modus lief ("mode": "and" / "or").
  • "all" – jedes Token erforderlich.
  • "any" – gewöhnliches disjunktives BM25.

​
Chronologischer Zweig

Ranked nach beliebiger Integer-Property, asc oder desc – der günstige „neueste zuerst”-Schenkel einer Hybrid-Query.

​
Properties projizieren

include_props steuert, was pro Treffer mitgeschickt wird: weglassen für nur id+score (keine Zusatzkosten), ein Name-Array übergeben, um nur diese Keys zu projizieren, oder true für die vollständige Property-Map. Projektion bedeutet, dass ein Reranker Treffer ohne zweiten Lookup-Roundtrip verarbeiten kann.

​
Turbopuffer-kompatibler Shim

POST /v2/namespaces/{ns}/query akzeptiert die Turbopuffer-Read-Form – {rank_by, filters, top_k, include_attributes} – und gibt {"rows": [{"id", "$dist", ...}]} zurück, wobei $dist die Kosinus-Distanz ist. rank_by: ["id", "asc"] mit filters: ["id", "Gt", cursor] liefert Cursor-Pagination/-Export. Nicht unterstützte Formen sind explizite 400s, die das Feld nennen – nie eine still veränderte Query.