POST /v1/namespaces/{ns}/search يُشغّل ما يصل إلى ثلاثة فروع مُرتَّبة على مجموعة صفوف مُصفَّاة واحدة. كل الفروع اختيارية؛ ويُشترط وجود واحد على الأقل. تنطبق label وfilter على كل فرع.
الفلاتر
يُقبل شكلان:- مساواة مفردة:
{"property": "project", "value": "conare"}— تُقدَّم مباشرة من قوائم الترحيل. - DSL بمصفوفة:
[property, op, value]معEq,NotEq,Gt,Gte,Lt,Lte,In(قيمة مصفوفة)، مُركَّبة بـ["And", [f1, f2, ...]]/["Or", [...]]حتى 16 مستوى.
false < true. عدم تطابق النوع أو خاصية غائبة لا يطابق أي شيء — بما في ذلك في NotEq — ولا يُنتج خطأ أبداً. المعاملات غير المعروفة، وقوائم And/Or الفارغة، وقيم In غير المصفوفة تُنتج 400 تسمّي المصدر.
الفرع المتجهي
الدرجات هي تشابه جيب التمام على متجهات موحّدة L2، وهي دقيقة دائماً — يختصر فهرس ANN (IVF + رموز RaBitQ ذات 1 بت) المرشحين، ثم يُعيد ترتيبهم مقابل متجهات كاملة الدقة. الخيارات:
يُعيد البحث المتجهي المُصفَّى تماماً نتائج ANN على المجموعة الفرعية المطابقة — يوسّع المحرك الفحص للتعويض عن الانتقائية، بحيث لا تُكلّفك الفلاتر ضمنياً استدعاء أقل.
الحتمية: لحالة فهرس ثابتة، تُعيد بايتات الاستعلام المتطابقة بمعاملات متطابقة قوائم مطابقات متطابقة بايتاً ببايت — عند أي عدد خيوط أو مستوى تزامن. خلف الكواليس، تُعيد عيّنة مستمرة تشغيل ~1% من استعلامات ANN مقابل الحقيقة الأساسية بالقوة الغاشمة وتنشر الاستدعاء؛ تُبلّغ نقطة النهاية
GET /recall-slo بدون بيانات اعتماد عن صحة استدعاء الأسطول.
فرع الكلمة المفتاحية
BM25 (k1=1.2, b=0.75) على خاصية text. المُقسِّم اللفظي: تصغير الأحرف، وتقسيم على كل حرف غير أبجدي رقمي — بدون تجذير، وبدون كلمات إيقاف (تطابق مُقسِّم الكلمات مع Turbopuffer).
match يتحكم في دمج الرموز:
"auto"(الافتراضي) — يتطلب كل الرموز؛ إذا أنتج ذلك أقل منmax(5, top_k/8)مطابقة، يعيد المحاولة بأي رمز. تُبلّغ الاستجابة عن الوضع الذي تم تشغيله ("mode": "and"/"or")."all"— كل رمز مطلوب."any"— BM25 انفصالي عادي.
الفرع الزمني
يُرتِّب حسب أي خاصية عددية صحيحة،asc أو desc — الساق الرخيصة “الأحدث أولاً” لاستعلام هجين.
إسقاط الخصائص
include_props يتحكم فيما يرافق كل مطابقة: احذفه للحصول على id+score فقط (بلا تكلفة إضافية)، مرِّر مصفوفة أسماء لإسقاط تلك المفاتيح فقط، أو true لخريطة الخصائص الكاملة. يعني الإسقاط أن مُعيد الترتيب يمكنه استهلاك المطابقات دون رحلة بحث ثانية.
طبقة توافق Turbopuffer
POST /v2/namespaces/{ns}/query يقبل شكل قراءة Turbopuffer — {rank_by, filters, top_k, include_attributes} — ويُعيد {"rows": [{"id", "$dist", ...}]} مع $dist كمسافة جيب التمام. rank_by: ["id", "asc"] مع filters: ["id", "Gt", cursor] يُعطي ترقيم/تصدير بمؤشر. الأشكال غير المدعومة هي 400 صريحة تسمّي الحقل — وليست أبداً استعلاماً مختلفاً بصمت.