Exact phrase and proximity search
shamela_search_phraseRead-onlyIdempotent
بحث بالعبارة والتقارب
Exact-phrase and proximity search the regular search lacks. mode='phrase' matches the query words as a CONSECUTIVE phrase (e.g. «خيار المجلس» only where those two words are adjacent). mode='near' matches pages where the words occur within distance words of each other in any order (e.g. «بيع» near «قبض» within 5 words) — ideal for fiqh questions where related terms sit close but not adjacent. Two-stage: finds candidate pages where all words co-occur, then verifies adjacency/proximity in the full page text. Pass scope (book_ids/author_ids/category_ids) to cover large libraries reliably. Returns book name, author, printed page, and a snippet. Examples: shamela_search_phrase({query:'خيار المجلس'}), shamela_search_phrase({query:'بيع قبض', mode:'near', distance:5, scope:{category_ids:[17]}}).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'phrase' = exact consecutive words (default). 'near' = words within `distance` words, any order. | phrase |
| limit | No | Maximum number of results to return (1-100, default 20). | |
| query | Yes | Arabic phrase. In mode='phrase' the words must appear consecutively (exact phrase). In mode='near' the words must appear within `distance` words of each other in any order. | |
| scope | No | Restrict to books/authors/categories/period. Strongly recommended to scope large libraries. | |
| 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. | |
| distance | No | For mode='near': maximum word span from the FIRST to the LAST query word, counted inclusively — distance=1 means adjacent, distance=2 allows one word between two query words. Ignored for mode='phrase'. | |
| search_in | No | Which page sections to verify the phrase in: body (matn), foot (footnotes), comment. | |
| 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| books | No | ||
| query | No | ||
| offset | No | ||
| results | No | ||
| distance | No | ||
| has_more | No | ||
| returned | No | ||
| truncated | No | ||
| next_offset | No | ||
| scope_count | No | ||
| rows_dropped | No | ||
| total_verified | No | ||
| zero_hit_terms | No | ||
| scope_resolution | No | ||
| candidate_cap_hit | No | ||
| truncation_message | No | ||
| unattributable_books | No | ||
| total_candidates_scanned | No |