البحث

POST /namespaces/:namespace/query ابحث في مساحة أسماء حسب المعنى والكلمات المفتاحية؛ يعيد Conare ترتيب أفضل التطابقات ويعيد، لكل مستند، المقاطع التي تجيب.

curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'

const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});

Response

{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}

الخيارات

الخيار	النوع	الوظيفة
`query`	string، مطلوب	السؤال، حتى 8,000 حرف
`top_k`	integer، الافتراضي 10	عدد النتائج المُعادة، من 1 إلى 500
`filter`	object	مرشّح بيانات وصفية
`user`	string	مستندات هذا المستخدم فقط
`user_prefix`	string	المستخدمون الذين يبدأ اسمهم بهذه القيمة فقط، مثل `tenant-7:`
`answer`	boolean، الافتراضي `false`	يكتب إجابة أيضًا
`rerank`	boolean، الافتراضي `true`	يعيد ترتيب أفضل التطابقات؛ `false` أسرع
`rerank_depth`	integer، الافتراضي 20	عدد المقاطع الأعلى المُعاد ترتيبها، من 1 إلى 1,000
`hops`	integer، الافتراضي 1	`2` يبحث مجددًا انطلاقًا من أفضل النتائج (قفزتان)
`retrievers`	array، الافتراضي `["vector", "keyword"]`	واحد أو اثنان من `vector` (المعنى) و`keyword`
`exclude_ids`	array	حتى 10,000 معرّف مستند لاستبعادها
`max_results`	integer	تصفّح حتى 1,000 نتيجة، أو 5,000 مع نموذج مخصص
`cursor`	string	`next_cursor` الخاص بالصفحة السابقة

المخطط الكامل: الاستعلام في مساحة أسماء.

الاستجابة

الحقل	المعنى
`results`	الأفضل أولًا، نتيجة واحدة لكل مستند
`results[].id`، `metadata`، `user`	الخاصة بالمستند
`results[].text`	مقاطعه التي تجيب، الأفضل أولًا: أفضلها وحتى مقطعين آخرين يطابقان بدرجة قريبة، كل منها حتى نحو 3,000 بايت، مع سطر لا يحوي إلا `…` بين المقاطع غير المتتالية؛ اجلب المستند للحصول عليه كاملًا
`results[].score`	الأعلى أفضل؛ قارن ضمن استعلام واحد فقط
`results[].reranked`	هل قيّمه مُعيد الترتيب؛ تأتي النتائج غير المُعاد ترتيبها في الأخير
`answer`	الإجابة، مع `answer: true`
`next_cursor`	مع `max_results`، قيمة `cursor` للصفحة التالية؛ يُحذف في الصفحة الأخيرة
`took_ms`	زمن البحث بالميلي ثانية

الإجابات

يضيف "answer": true إجابة مكتوبة من أفضل المقاطع، في نحو ثانيتين إضافيتين.

Response

{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}

يكتبها نموذج لغوي من المقاطع التي عُثر عليها؛ راجع سياسة الخصوصية.
إذا لم يكن ذلك النموذج متاحًا، تحصل على النتائج دون answer.

قفزتان

يبحث "hops": 2 مجددًا انطلاقًا من أفضل النتائج، للأسئلة التي تحتاج إجابتها إلى حقائق من مستندين.

curl

curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'

يضيف نحو 0.3 ثانية: استخدمه للأسئلة التي تربط الحقائق ببعضها.
يعيد 400 invalid_request مع rerank: false، ومع max_results، وفي مساحات أسماء النماذج المخصصة.

الصفحات

الخطوة	أرسل
الصفحة الأولى	`query` و`max_results` (عدد النتائج المُرتَّبة مرة واحدة) و`top_k` (حجم الصفحة)
الصفحات التالية	`cursor` فقط (آخر `next_cursor`) و`top_k`
الصفحة الأخيرة	لا تحتوي على `next_cursor`

يدوم المؤشر 15 دقيقة. تقرأ الدالة queryPages() في SDK كل الصفحات.

البحث في كل مساحات الأسماء

POST /query الطلب نفسه عبر ما يصل إلى 100 مساحة أسماء، مع إعادة ترتيب النتائج معًا؛ يقصر prefix البحث على مساحات الأسماء التي تبدأ أسماؤها به.

curl

curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'

Response

{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}

الخيار أو الحقل	هنا
`prefix`	مساحات الأسماء التي تبدأ أسماؤها بهذه القيمة فقط
`rerank_depth`	الافتراضي 60، من 1 إلى 1,000
`exclude_ids`	يُكتب بصيغة `namespace/id`
`results[].namespace`	مساحة أسماء النتيجة
`namespaces`، `skipped_namespaces`	التي بُحث فيها، والتي تجاوزت أول 100

يعمل hops هنا أيضًا. المخطط الكامل: الاستعلام في كل مساحات الأسماء.

النتائج المنقوصة

إذا فشل جزء من البحث، يظل الاستعلام ناجحًا ويوضّح الترويسة Conare-Degraded ما تم تخطيه.

القيمة	المعنى
`rerank`، `rerank-partial`	لم يُعَد ترتيب بعض النتائج أو كلها (`reranked: false`)
`embed`	بُحث بالكلمات المفتاحية فقط
`keyword`، `keyword-terms`	كان الاستعلام أطول من أن يقرأه البحث بالكلمات المفتاحية كاملًا
`embed-next`	تعذّر البحث في جزء من مساحة الأسماء
`cursor`	لا يوجد `next_cursor`؛ ابحث مجددًا للحصول على صفحات أخرى
`embed-busy`، `embed-fallback`	أبطأ من المعتاد؛ النتائج غير متأثرة
`answer`	لا إجابة، النتائج فقط

إذا تعذّر البحث كليًا، يعيد الاستعلام 503.

البدء

الأساسيات

الملفات

المزامنة

النماذج

الأدوات

الخيارات

الاستجابة

الإجابات

قفزتان

الصفحات

البحث في كل مساحات الأسماء

النتائج المنقوصة

​الخيارات

​الاستجابة

​الإجابات

​قفزتان

​الصفحات

​البحث في كل مساحات الأسماء

​النتائج المنقوصة

الخيارات

الاستجابة

الإجابات

قفزتان

الصفحات

البحث في كل مساحات الأسماء

النتائج المنقوصة