Search page text (body and footnotes)
shamela_search_pagesبحث في صفحات الكتب
Search the body (matn) and footnotes (الحواشي) of every Shamela page the user has downloaded locally. AND-combines tokens; each token can match in any of the search_in fields. Default scope is the full downloaded library; pass scope (book_ids/author_ids/category_ids/period_*/downloaded_only/madhab/book_type/citable_only) to narrow. scope.madhab ('hanafi'|'maliki'|'shafii'|'hanbali') answers a school-specific fiqh question — it uses Shamela's school categories AND the main author's school, so it reaches مسائل فقهية and الفقه العام where no school is filed; books whose school is unknown are excluded, so leave it unset for comparative questions. scope.book_type excludes what is not an authored book (transcript/thesis/journal/electronic/manuscript), and scope.citable_only keeps only books whose page numbers match a real printed edition — set it whenever the answer will quote a page as a citation. options controls morphology (Arabic root expansion via AlKhalil — NOTE Arabic roots are ambiguous and the analyzer keeps every reading, so «كتب» also searches تبب/توب/وتب, i.e. perdition and repentance; the response returns morphology_expanded_to naming exactly what was searched, and results are a SUPERSET of the word you asked for), wildcards (*/? per token, cannot combine with morphology), and search_in subset (body/foot). Returns total_hits + paginated results with book name, author, printed-page label, and a snippet with ... around matches; coverage rolls up by category/century/book/author — EXACT (every matching page counted) whenever coverage.sample_is_complete is true, and otherwise a top-scoring sample of coverage.sampled_hits of total_hits, whose shares are then indicative rather than a census. by_category/by_century cover the whole sample; by_book/by_author are the largest coverage.top_n only, so they do not sum to it. Plus edition_groups whenever hits landed in two or more catalog entries of one work (several editions of the same book) — read those as one source, not several. preserve_diacritics/_hamza/_digits return OPTION_NOT_SUPPORTED here — use shamela_search_exact for those. Use shamela_search_titles for chapter title search instead. Examples: shamela_search_pages({query:'الكلام'}), shamela_search_pages({query:'استصناع', scope:{category_ids:[17]}}), shamela_search_pages({query:'كلم', options:{morphology:true}}).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (1-100, default 20). | |
| query | Yes | Arabic search phrase. Multiple words are AND-combined; each can match in body or footnotes. If a word does not exist in the library under the spelling you used, the spelling the books DO use is searched instead and reported in `respelled_terms` — say so when you quote the result, because the source writes the word differently. | |
| scope | No | Restrict the search to specific books, authors, categories, or a Hijri date range. Use shamela_list_categories / shamela_resolve to find IDs. | |
| 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 |
| offset | No | Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. | |
| options | No | Search options: morphology, wildcards, sort, search_in (body/foot), relax_when_empty. Defaults to body+foot, no toggles. preserve_* redirect to shamela_search_exact. | |
| exclude_pages | No | Exact pages to keep out — the pages a previous round already returned. Excluding these rather than whole books is what lets a follow-up search find MORE evidence in a book that has already contributed some. | |
| 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 |
| exclude_book_ids | No | Book ids to keep out of the results entirely. | |
| exclude_author_ids | No | Exclude every book by these authors. | |
| exclude_category_ids | No | Exclude every book on these shelves. | |
| exclude_work_group_ids | No | Exclude every catalogue entry of these works — all printings at once. This is the one to use after a round returned «صحيح البخاري - ط السلطانية»: excluding that book_id alone leaves the other seven entries of group 1681 free to return the same text again as if it were a second source. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| books | No | ||
| query | No | ||
| offset | No | ||
| results | No | ||
| coverage | No | ||
| has_more | No | ||
| returned | No | ||
| truncated | No | ||
| total_hits | No | ||
| next_offset | No | ||
| scope_count | No | ||
| rows_dropped | No | ||
| paging_ceiling | No | ||
| zero_hit_terms | No | ||
| respelled_terms | No | ||
| terms_truncated | No | ||
| relaxed_of_terms | No | ||
| scope_resolution | No | ||
| normalized_tokens | No | ||
| relaxed_min_match | No | ||
| truncation_message | No | ||
| morphology_fallback | No | ||
| unattributable_books | No | ||
| morphology_expanded_to | No |