> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# البحث

> شغّل فروع ANN المتجهي، وBM25 للكلمة المفتاحية، والترتيب الزمني على مجموعة صفوف مُصفَّاة واحدة عبر لغة فلاتر مُنمَّطة وtop_k لكل فرع مستقل.

`POST /v1/namespaces/{ns}/search` يُشغّل ما يصل إلى ثلاثة فروع مُرتَّبة على مجموعة صفوف مُصفَّاة واحدة. كل الفروع اختيارية؛ ويُشترط وجود واحد على الأقل. تنطبق `label` و`filter` على كل فرع.

```json theme={null}
{
  "label": "chunk",
  "filter": ["And", [["project", "Eq", "conare"], ["created_at_ms", "Gte", 1720000000000]]],
  "include_props": ["text", "created_at_ms"],
  "branches": {
    "vector":        {"embedding": [0.1, "..."], "top_k": 40},
    "keyword":       {"query": "raw query text", "top_k": 40},
    "chronological": {"attribute": "created_at_ms", "order": "desc", "top_k": 40}
  }
}
```

الاستجابة — قائمة مُرتَّبة مستقلة واحدة لكل فرع، مع زمن التنفيذ داخل الخادم:

```json theme={null}
{
  "vector":        {"hits": [{"id": "chunk-123", "score": 0.83}], "index": "ivf-rabitq", "server_us": 412},
  "keyword":       {"hits": [{"id": "chunk-9", "score": 14.2}], "mode": "and", "server_us": 200},
  "chronological": {"hits": [{"id": "chunk-7", "value": 1720000000000}], "server_us": 90}
}
```

## الفلاتر

يُقبل شكلان:

* **مساواة مفردة**: `{"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 بت) المرشحين، ثم يُعيد ترتيبهم مقابل متجهات كاملة الدقة. الخيارات:

| الحقل        | الافتراضي      | المعنى                                                                                                                    |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `mode`       | `"auto"`       | `"auto"` يختار ANN مقابل exact حسب التكلفة النموذجية؛ `"exact"` يُجبر القوة الغاشمة؛ `"ann"` يتطلب الفهرس (400 عند غيابه) |
| `nprobe`     | 7% من العناقيد | العناقيد التي تُفحص — ارفعها للاستدعاء، اخفضها لزمن الاستجابة                                                             |
| `oversample` | 4              | مضاعف عمق إعادة الترتيب (يعاد ترتيب `top_k × oversample` مرشحاً بدقة تامة)                                                |

يُعيد البحث المتجهي المُصفَّى تماماً نتائج 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` صريحة تسمّي الحقل — وليست أبداً استعلاماً مختلفاً بصمت.