Batch search (several queries)
shamela_search_batchبحث مجمَّع بعدة استعلامات
Run up to 12 scoped searches in ONE call and get back a single merged, deduplicated result set. Built for assembling evidence for one question from several wordings at once: each probe is {query, mode:'and'|'phrase'|'near', scope, limit}, they execute concurrently, and pages found by more than one probe are returned ONCE with every probe id that found them (probe_ids) — which is corroboration across wordings, not a duplicate. Every row carries match_quality ('exact_phrase'|'near'|'all_terms'|'relaxed') and matched_in_section ('body'|'footnote'|'both') so a near miss can never be read as a located quotation once results are merged, and a modern editor's footnote is never quoted as the author's own words. Every row also carries work_group_id, and edition_groups names any work present here under several catalog entries — read those as ONE source, not as several that corroborate each other. scope is REQUIRED on every probe (one of book_ids/author_ids/category_ids/madhab): unscoped, Lucene ranks by term frequency across all 8,594 books, so «التيمم» returns a poetry anthology ahead of the fiqh manuals. A probe that fails or times out is reported in its own slot and does NOT discard the others; incomplete is then true and a thin result must NOT be read as the library being silent. Each completed probe carries qualifiers — terms_truncated, zero_hit_terms, respelled_terms, paging_ceiling, coverage.at_cap, candidate_cap_hit, scope_resolution, unattributable_books — the same caveats the single-call search returns, per probe; the block is present only on status:'ok', so a probe WITHOUT it has not been checked and must not be recorded as searched. scope_resolution.dropped lists book ids the catalogue does not hold, which were never searched — the guard against reading an invented id's silence as the library's. Example: shamela_search_batch({probes:[{query:'الوتر واجب', scope:{category_ids:[14,19], citable_only:true}}, {query:'حكم صلاة الوتر', mode:'near', distance:5, scope:{madhab:'hanafi'}}]}).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| shape | No | How much of each hit to return. 'full' (default) is every field on every row, including the snippets — ask for this when the answer will QUOTE the page. 'brief' keeps book_id/page_id, printed_page, match_quality and matched_in_section and hoists book metadata into a top-level `books` dictionary keyed by book_id, but carries NO snippet: it answers which pages these are, how well each matched and how to cite them, for a fraction of the characters, so far more rows survive the budget. 'index' returns book_id/page_id only, for choosing what to read before paying to read it. Requires the 'shape.full_brief_index' capability (see shamela_brief). | full |
| probes | Yes | The searches to run. They execute concurrently and their results are merged, deduped by (book_id, page_id) and attributed back to the probes that found each page. | |
| deadline_ms | No | Wall-clock budget for the whole batch. Probes still running when it expires are reported with status='timeout' and contribute nothing. A timeout is NOT a negative finding — it means the question was not fully asked. | |
| response_format | No | Output format for the human-readable text. 'markdown' (default) is best for direct display; 'json' returns the same data as a single JSON code block; 'none' skips the rendered text entirely and returns a one-line pointer, leaving `structuredContent` as the whole answer. The structured data is returned in `structuredContent` regardless of this setting, so a caller that parses it should pass 'none' — the character budget is measured over BOTH channels, and the unread copy is otherwise spending most of it. Requires the 'response_format.none' capability (see shamela_brief). | markdown |
| max_total_passages | No | Hard cap on merged rows returned. Rows are ordered by match quality then probe agreement before the cut, so the cap drops the weakest evidence rather than an arbitrary tail. `truncated` says whether it fired. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| books | No | ||
| probes | No | ||
| by_book | No | ||
| results | No | ||
| truncated | No | ||
| incomplete | No | ||
| rows_dropped | No | ||
| edition_groups | No | ||
| truncation_message | No | ||
| total_unique_passages | No |