البحث

طريقتان للبحث. البحث الدلالي يبحث بالكلمات والمعنى في القرآن والكتب والموسوعات، للعثور على نتائج مرتبطة بالسؤال حتى إن لم تتطابق معه في الكلمات. البحث بالكلمات يطابق الكلمات نفسها ويبرزها في النتائج، ويناسب الإكمال التلقائي والبحث عن عبارة بعينها.

البحث الدلالي

GET/hybrid-search

المعامل	الحالة	الوصف
`q`	مطلوب	السؤال أو كلمات البحث، بالعربية أو بأي لغة مدعومة. ما بين علامتي اقتباس يُبحث عنه حرفيًا.
`type`	اختياري	`aya`، `book`، `card` مفصولة بفواصل. عند عدم تحديده، تظهر الأنواع الثلاثة معًا مرتبة حسب صلتها بالسؤال، وبحد أقصى نتيجتين من الكتاب الواحد أو البطاقة الواحدة.
`lang`	اختياري	لغة القارئ. يشمل البحث هذه اللغة والعربية، وتُستخدم في حقل `translation` لكل آية (الافتراضي `ar`).
`langs`	اختياري	لغات البحث البديلة، مفصولة بفواصل، أو `all` للبحث بجميع اللغات.
`surah`	اختياري	أرقام سور مفصولة بفواصل، لقصر النتائج على آيات هذه السور.
`book`	اختياري	معرّفات الكتب المطلوب البحث في مقاطعها فقط.
`enc`	اختياري	معرّفات الموسوعات المطلوب البحث في بطاقاتها فقط.
`category`	اختياري	مفاتيح تصنيف `"<table>:<item>"` مفصولة بفواصل: البطاقات الموجودة في أي منها. يقتصر البحث عند استخدامه على البطاقات.
`prop`	اختياري	شرط خاصية `"<id>=<value>"`. يمكن تكراره للحصول على البطاقات التي تحقق جميع الشروط. يقتصر البحث عند استخدامه على البطاقات.
`ratio`	اختياري	الوزن النسبي للبحث بالمعنى مقابل البحث بالكلمات، من 0 إلى 1 (الافتراضي 0.75). `0` كلمات فقط، و`1` معنى فقط.
`exact`	اختياري	`true`: البحث عن الكلمات كما كُتبت، متجاورة وبالترتيب نفسه، دون استخدام البحث بالمعنى.
`limit`	اختياري	من 1 إلى 50، والافتراضي 10.
`offset`	اختياري	الافتراضي 0. الحد الأقصى لمجموع `offset + limit` هو 1000.
`facets`	اختياري	`categories` يضيف `categoryCounts`، و`props` يضيف `propCounts`: عدد البطاقات المطابقة في كل تصنيف أو قيمة خاصية.
`format`	اختياري	`hits`: إرجاع النتائج ببنية `GET /search` (`hits`، `_formatted`، `metadata`).
`intent`	اختياري	`off`: يبحث في كل الأنواع حتى لو حدد السؤال نوعًا. (في الوضع العادي “كتاب عن…” يعيد كتبًا فقط.)

curl "https://islamenc.com/api/hybrid-search?q=فضل الصدقة&limit=6&lang=en"

{
  "query": "فضل الصدقة",
  "filters": { "type": null, "langs": null, "surah": null, "book": null, "enc": null, "category": null, "prop": null, "ratio": 0.75, "exact": false, "intent": null },
  "semantic": true,
  "semanticHits": 18,
  "reranked": false,
  "mixed": true,
  "timings": { "embed": 0, "meili": 152, "rerank": 0, "db": 7, "total": 165 },
  "results": [
    {
      "type": "aya",
      "score": 0.7588,
      "surah_no": 2,
      "aya_no": 271,
      "surah_name": "البَقَرَة",
      "aya_uthmani": "إِن تُبۡدُواْ ٱلصَّدَقَٰتِ فَنِعِمَّا هِيَۖ ...",
      "translation": "271. If you disclose your Sadaqât (alms-giving), it is well; ...",
      "matched_lang": "ar"
    },
    {
      "type": "book",
      "score": 0.8133,
      "lang": "ar",
      "phrase_id": "17f637d4-3a97-4747-9382-4e15d7727f44",
      "book_title": "المنتقى من المتجر الرابح في ثواب العمل الصالح",
      "chapter_id": 6585,
      "project_id": 226,
      "chapter_name": "المنتقى من المتجر الرابح في ثواب العمل الصالح",
      "text": "ثواب الصدقة\nعن أبي هريرة رضي الله عنه أن رسول الله ..."
    },
    {
      "type": "card",
      "score": 0.802,
      "lang": "ar",
      "title": "الصدقة",
      "card_id": "22413",
      "enc_id": "114",
      "categories": ["11:136", "11:4", "11:511"],
      "props": { "t40": ["40:4"] },
      "text": "الصدقة\nإن من محاسن الدين الإسلامي الحث على الصدقة؛ ..."
    }
  ]
}

أنواع النتائج

`type`	الحقول	الرابط
`aya`	`surah_no`، `aya_no`، `surah_name`، `aya_uthmani`، `translation` (بلغة `lang`)، `matched_lang`	`https://islamenc.com/{lang}/quran/{surah_no}/{aya_no}`
`book`	`project_id`، `book_title`، `chapter_id`، `chapter_name`، `phrase_id`، `lang`، `text` (المقطع المطابق)	`https://islamenc.com/{lang}/books/{project_id}`
`card`	`card_id`، `enc_id`، `title`، `lang`، `text`، `categories`، `props`	`https://islamenc.com/{lang}/enc/{enc_id}/card/{card_id}`

يمثل score درجة التطابق في محرك البحث، من 0 إلى 1. استخدمه للمقارنة بين نتائج النوع نفسه، وليس بين الأنواع المختلفة. اعرض النتائج بترتيبها في results؛ إذ يرتبها نموذج إعادة الترتيب حسب صلتها بالسؤال، باستخدام مقياس موحد لجميع الأنواع، دون ترتيب ثابت لظهور كل نوع.

مؤشرات الاستجابة

الحقل	المعنى
`semantic`	`true` إذا استُخدم البحث بالمعنى. وتكون `false` إذا لم يكتمل تحليل السؤال خلال المهلة المحددة (نحو 1.5 ثانية عند بطء الخدمة)، فيقتصر البحث على الكلمات. يُحفظ التحليل عند اكتماله، ويمكن إعادة إرسال السؤال بعد قليل للحصول على نتائج البحث بالمعنى.
`semanticHits`	عدد النتائج الأولية التي جاءت من البحث بالمعنى.
`mixed`	`true` إذا كان البحث في عدة أنواع.
`timings`	الزمن بالميلي ثانية لكل مرحلة: تحليل السؤال، ومحرك البحث، وإعادة الترتيب، وقراءة قاعدة البيانات.

تقسيم النتائج وعدّها

يُرجع format=hits النتائج بالبنية المستخدمة في صفحة البحث بالموقع، مع تمييز الكلمات المطابقة وحقل hasMore:

curl "https://islamenc.com/api/hybrid-search?q=فضل الصدقة&limit=9&offset=9&format=hits&facets=categories"

{
  "hits": [
    { "id": "aya_2_271", "type": "aya", "title": "البَقَرَة - 271", "text": "...", "_formatted": { "text": "..." }, "metadata": { "surah_no": 2, "aya_no": 271, "surah_name": "البَقَرَة" } }
  ],
  "categoryCounts": { "11:4": 12, "11:136": 9 },
  "hasMore": true,
  "processingTimeMs": 165
}

تُميَّز الكلمات المطابقة بوسم <em> داخل _formatted. ينطبق ذلك على البحث بالكلمات فقط، لأن البحث بالمعنى لا يعتمد على تطابق كلمات محددة.

فهم نية السؤال

إذا حدد السؤال نوع المحتوى المطلوب، يقتصر البحث عليه: “كتاب عن الصيام” يعيد كتبًا فقط، و“آيات عن الصبر” آيات فقط، و“حديث عن النية” بطاقات أحاديث فقط. أرسل intent=off للبحث في كل الأنواع مهما كان السؤال.

البحث بالكلمات

GET/search

يبحث عن الكلمات نفسها، مع مراعاة الأخطاء الإملائية، ويميّز الكلمات المطابقة في النتائج. وهو أسرع من البحث الدلالي، ويناسب البحث عن عبارة محددة أو تقديم اقتراحات للإكمال التلقائي.

المعامل	الحالة	الوصف
`q`	مطلوب	الكلمات.
`type`	اختياري	`aya`، `book`، `card` مفصولة بفواصل.
`encId`	اختياري	بطاقات موسوعة واحدة فقط.
`lang`	اختياري	لغة المحتوى المطلوب البحث فيه (الافتراضي العربية مع لغات الموقع).
`surah`	اختياري	رقم سورة: آياتها فقط.
`category`، `prop`	اختياري	كما في البحث الدلالي.
`facets`	اختياري	`categories`: يضيف `categoryCounts`.
`limit`، `offset`	اختياري	تقسيم النتائج إلى صفحات.

{
  "hits": [
    {
      "id": "aya_6546",
      "type": "aya",
      "lang": ["ar", "en"],
      "title": "آل عِمران - 17",
      "text": "ٱلصَّٰبِرِينَ وَٱلصَّٰدِقِينَ ...",
      "metadata": { "surah_no": 3, "aya_no": 17, "surah_name": "آل عِمران" },
      "_formatted": { "title": "<em>آل</em> عِمران - 17", "text": "<em>ٱلصَّٰبِرِينَ</em> ..." }
    }
  ],
  "query": "الصبر",
  "processingTimeMs": 12,
  "limit": 2,
  "offset": 0,
  "estimatedTotalHits": 1480,
  "totalHits": 1000,
  "capped": true
}

يحتوي metadata على المعرّفات اللازمة لإنشاء رابط النتيجة: surah_no وaya_no للآية، وproject_id وchapter_id لمقطع الكتاب، وenc_id وcard_id للبطاقة. وتعني capped أن حساب العدد الكلي للنتائج توقف عند 1000.

الاقتراحات

GET/search/suggestions

المعامل	الحالة	الوصف
`q`	مطلوب	النص الذي أدخله المستخدم حتى الآن.
`type`	اختياري	`aya`، `book`، `card`.
`encId`	اختياري	موسوعة واحدة فقط.
`lang`	اختياري	لغة المحتوى.

يُرجع عددًا محدودًا من العناوين والمقاطع التي تبدأ بالنص المُدخل أو تحتوي عليه، لاستخدامها في قائمة الإكمال التلقائي:

[
  {
    "text": "الصبر وانتظار الفرج من أعظم العبادات - فضيلة الشيخ محمد بن عثيمين",
    "type": "phrase",
    "title": "مشروع هدايات - المجموعة الخامسة - الصبر وانتظار الفرج من أعظم العبادات",
    "metadata": { "phrase_id": "...", "project_id": 231, "chapter_id": 6029 },
    "snippets": [ { "id": "phrase_...", "text": "...", "_formatted": { "text": "..." } } ]
  }
]

التصنيفات

GET/search/categories

يعرض تصنيفات البطاقات في جميع الموسوعات، مع عدد البطاقات في كل تصنيف، بالبنية نفسها المستخدمة في GET /enc/{id}/categories. استخدمه لإضافة خيار تصفية حسب التصنيف إلى واجهة البحث.