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.
Filter
Zwei Formen werden akzeptiert:- Einzelne Gleichheit:
{"property": "project", "value": "conare"}– direkt aus Posting-Listen bedient. - Array-DSL:
[property, op, value]mitEq,NotEq,Gt,Gte,Lt,Lte,In(Array-Wert), kombiniert mit["And", [f1, f2, ...]]/["Or", [...]]bis zu 16 Ebenen tief.
false < true. Eine Typinkompatibilität oder eine fehlende Property matcht auf nichts – auch bei NotEq – wirft aber nie einen Fehler. Unbekannte Operatoren, leere And/Or-Listen und nicht-Array-In-Werte sind 400s, die den Verursacher benennen.
Vektor-Zweig
Scores sind Cosinus-Ähnlichkeit auf L2-normierten Vektoren und immer exakt – der ANN-Index (IVF + RaBitQ 1-Bit-Codes) macht eine Vorauswahl der Kandidaten und rerankt sie dann gegen Vektoren voller Präzision. Optionen:
Gefilterte Vektorsuche liefert exakt die ANN-auf-der-passenden-Teilmenge-Ergebnisse zurück – die Engine erweitert das Probing, um die Selektivität zu kompensieren, damit Filter Sie nicht stillschweigend Recall kosten.
Determinismus: Für einen festen Indexzustand geben identische Query-Bytes mit identischen Reglern byteidentische Trefferlisten zurück – bei beliebiger Thread-Zahl oder Nebenläufigkeit. Im Hintergrund wiederholt ein kontinuierlicher Sampler ~1 % der ANN-Abfragen gegen die Brute-Force-Ground-Truth und veröffentlicht den Recall; der anmeldedaten-freie
GET /recall-slo-Endpunkt meldet die Recall-Gesundheit der Flotte.
Keyword-Zweig
BM25 (k1=1.2, b=0.75) über der text-Property. Tokenizer: Kleinbuchstaben, Split an jedem nicht-alphanumerischen Zeichen – kein Stemming, keine Stopwords (Wort-Tokenizer-Parität mit Turbopuffer).
match steuert die Token-Kombination:
"auto"(Standard) – alle Tokens erforderlich; ergibt das weniger alsmax(5, top_k/8)Treffer, wird als any-Token wiederholt. Die Antwort meldet, welcher Modus lief ("mode": "and"/"or")."all"– jedes Token erforderlich."any"– gewöhnliches disjunktives BM25.
Chronologischer Zweig
Sortiert nach einer beliebigen Integer-Property,asc oder desc – die kostengünstige „Neueste zuerst”-Komponente einer hybriden Anfrage.
Properties projizieren
include_props steuert, was zu jedem Treffer mitgeliefert wird: weglassen für nur ID+Score (kein Extraaufwand), ein Namens-Array übergeben, um nur diese Schlüssel zu projizieren, oder true für die vollständige Property-Map. Projektion bedeutet, dass ein Reranker Treffer verarbeiten kann, ohne einen zweiten Lookup-Roundtrip.
Turbopuffer-kompatibler Shim
POST /v2/namespaces/{ns}/query akzeptiert die Turbopuffer-Leseform – {rank_by, filters, top_k, include_attributes} – und gibt {"rows": [{"id", "$dist", ...}]} zurück, wobei $dist die Cosinus-Distanz ist. rank_by: ["id", "asc"] mit filters: ["id", "Gt", cursor] ergibt Cursor-Paginierung/Export. Nicht unterstützte Formen sind explizite 400s, die das Feld benennen – niemals eine stillschweigend abweichende Abfrage.