POST /v1/namespaces/{ns}/search exécute jusqu’à trois branches classées sur un même jeu de lignes filtré. Toutes les branches sont optionnelles ; au moins une est requise. label et filter s’appliquent à chaque branche.
Filtres
Deux formes sont acceptées :- Égalité simple :
{"property": "project", "value": "conare"}— servie directement depuis les listes d’affichage. - DSL tableau :
[property, op, value]avecEq,NotEq,Gt,Gte,Lt,Lte,In(valeur tableau), composables via["And", [f1, f2, ...]]/["Or", [...]]jusqu’à 16 niveaux.
false < true. Une incompatibilité de type ou une propriété absente ne correspond à rien — y compris pour NotEq — sans jamais lever d’erreur. Les opérateurs inconnus, les listes And/Or vides et les valeurs In non tableaux sont des 400 nommant le fautif.
Branche vectorielle
Les scores sont une similarité cosinus sur des vecteurs L2-normalisés, et toujours exacts — l’index ANN (IVF + codes RaBitQ 1-bit) présélectionne les candidats, puis les rerank contre les vecteurs en pleine précision. Options :
La recherche vectorielle filtrée renvoie exactement les résultats ANN sur le sous-ensemble correspondant — le moteur élargit le sondage pour compenser la sélectivité, si bien que les filtres ne vous coûtent pas silencieusement en rappel.
Déterminisme : pour un état d’index fixe, des octets de requête identiques avec des paramètres identiques renvoient des listes de résultats identiques au bit — quel que soit le nombre de threads ou la concurrence. En coulisses, un échantillonneur continu rejoue ~1 % des requêtes ANN contre la vérité brute-force et publie le rappel ; l’endpoint sans identifiants
GET /recall-slo rapporte la santé de rappel de la flotte.
Branche mot-clé
BM25 (k1=1.2, b=0.75) sur la propriété text. Tokeniseur : minuscules, split sur chaque caractère non alphanumérique — pas de stemming, pas de mots vides (parité de tokeniseur mot avec Turbopuffer).
match contrôle la combinaison des tokens :
"auto"(défaut) — exige tous les tokens ; si cela produit moins demax(5, top_k/8)résultats, réessayer en mode any-token. La réponse indique quel mode a été utilisé ("mode": "and"/"or")."all"— chaque token requis."any"— BM25 disjonctif ordinaire.
Branche chronologique
Classe par n’importe quelle propriété entière,asc ou desc — la branche « du plus récent au plus ancien » économique d’une requête hybride.
Projeter des propriétés
include_props contrôle ce qui accompagne chaque résultat : omettez-le pour id+score seulement (aucun coût supplémentaire), passez un tableau de noms pour projeter uniquement ces clés, ou true pour la carte complète de propriétés. La projection signifie qu’un reranker peut consommer les résultats sans un second aller-retour.
Shim compatible Turbopuffer
POST /v2/namespaces/{ns}/query accepte la forme de lecture Turbopuffer — {rank_by, filters, top_k, include_attributes} — et renvoie {"rows": [{"id", "$dist", ...}]} avec $dist comme distance cosinus. rank_by: ["id", "asc"] avec filters: ["id", "Gt", cursor] fournit la pagination/l’export par curseur. Les formes non prises en charge sont des 400 explicites nommant le champ — jamais une requête silencieusement différente.