# Advent AI library search syntax

Search runs over passages (chunks of a few hundred words) of every book and periodical in the
library. Matching is case-insensitive, but operator keywords must be written in CAPITALS
(`NEAR/5`, not `near/5`). Lowercase words are ordinary search text.

Precedence, tightest first: parentheses, phrases and compounds; proximity operators; NOT;
then AND / OR / XOR / OPT at equal priority, left to right. Use parentheses to be explicit.

| Operator | Forms | Meaning |
|---|---|---|
| And | space, `AND`, `&`, `+` | both in the passage |
| Or | `OR`, `\|` | either |
| Not | `NOT`, `!`, leading `-` | absent (`A BUT NOT B` = `A AND NOT B`); `!` touching a Bible reference means cited (below) |
| Xor | `XOR`, `^` | exactly one |
| Optional | `A OPT B` | B only raises the ranking |
| Phrase | `"to be or not"` | adjacent, in order |
| Near | `A NEAR B`, `A NEAR/n B` | within n words, either order (default 10) |
| Before / After | `A BEFORE/n B`, `A AFTER/n B` | ordered; no n = anywhere in the passage |
| Next | `A NEXT B` | B immediately follows A |
| Positional not | `A NOT NEAR/n B` (also NOT BEFORE / NOT AFTER / NOT NEXT) | both present, keep A only where B is not close |
| Ordered window | `"words in order" /10` | all words in order with up to 10 extra words |
| Unordered window | `"any order words" @7` | all words, any order, up to 7 extra words |
| Wildcards | `wom?n`, `work*`, `*tion` | `?` one character, `*` any run |
| Substring | `~effect` | same as `*effect*` |
| Word family | `go%` | go, goes, going, gone, went |
| Thesaurus | `love$` | the word family plus corpus synonyms (affection, charity…) |
| Heading scope | `[Contents Genesis] noah ark` | only passages under matching headings |
| Theme tag | `tag:prayer`, `tag:"second coming"` | passages tagged with the theme, whatever their words |
| Exact tag | `tag:=daily`, `tag:="daily sacrifice"` | only that one tag, not the tags containing its words |
| Person / place / date tag | `person:moses`, `place:"battle creek"`, `date:1844` | passages tagged with that person, place or date |
| Bible verse | `Romans 6:1-5`, `rom 6:1`, `1 Cor. 13:4`, `verse:"John 3"`, `Dan 11:1-40/OR` | passages that cite or allude to the verse |
| Cited verse | `!Romans 6:1`, `!verse:"John 3"` | only passages that cite the verse |
| Alluded verse | `~Romans 6:1`, `~verse:"John 3"` | only passages that allude to the verse |

Tags: every passage carries AI-extracted tags (themes, people, places, dates), each weighted
by how central it is. A tag term matches the tags that contain its words, in lemma form
(`tag:prayer` also covers answered prayer, secret prayer, prayer meeting), weighing how closely
each tag matches and how often the library uses it, and ranks passages where the tag is
central above passing mentions. Write tags short and plain (1–3 words, singular, lowercase),
as a subject index would. Tags combine with AND / OR / NOT / OPT but not with the proximity
operators; `words OPT tag:x` keeps the word matches and moves passages on the theme up.

Bible verses: a reference written anywhere in the query (full book name or abbreviation) finds
the passages that cite the verse or allude to it, cited ones ranked first, not its words. Put `!`
straight before the reference (no space) for only the passages that cite it (`!John 3:16`), or `~`
for only those that allude to it (`~John 3:16`); the mark covers the whole reference, a range or a
chapter included (`!Dan 11:1-40/OR`, `~Matt 24`). `!` with a space after it, `NOT` or `-` still
leave the passages out (`grace NOT John 3:16`; `-!John 3:16` leaves out only those citing it). A range
(`Romans 6:1-5`) means every verse in it: passages referring to all five. Add `/OR` to a range
(`Dan 11:1-40/OR`) for passages referring to any of its verses, those naming more of them first.
A chapter on its own (`Matt 24`) is a lookup too, except beside other words when its book name
is also an everyday word (`acts 2 grace`: write `verse:"Acts 2"`, or set it apart with an
operator, `grace OR acts 2`); it matches any reference inside that chapter, and the breakdown lists its
verses one by one with their counts. References combine with words, tags and each other using
AND / OR / NOT / OPT, never the proximity operators. Quote a reference (`"Rom. 6:1"`) to search
its printed words instead.

Examples:
- `"righteousness by faith" NEAR/20 law`
- `(sabbath OR "seventh day") AND rest% NOT sunday`
- `health$ BEFORE/15 temperance`
- `tag:prayer OR tag:"communion with god"`
- `"pray without ceasing" OPT tag:prayer`
- `Romans 6:1-5 grace`
- `Daniel 8:14 OR Hebrews 9:23`
- `Daniel 11:40-45/OR`
- `!Daniel 8:14 sanctuary` (passages citing the verse)
- `~Matthew 24:14` (passages alluding to the verse)

Not supported: sentence/paragraph windows (`/s`, `@p`, `#N`). An invalid query returns
`errors` (plain sentences) and no results.

## Narrowing a search

- `collectionIds`: content collections from `/api/v1/library/collections`; a parent covers its subtree.
- `sourceId`: one book or periodical edition (see `/api/v1/library/works/{kind}/{uniqueId}/scope`).
- `authorId`: only passages whose byline links to that author (find ids with `/api/v1/library/authors?q=`).
- `dateFrom` / `dateTo`: publication dates as `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. A start date
  means the beginning of that period and an end date its end, so `dateFrom=1850&dateTo=1855`
  covers 1 Jan 1850 to 31 Dec 1855. `/api/v1/library/timeline` shows which years have material.
  Ellen G. White's letters and manuscripts are dated by when they were written: their rows carry
  `writtenFrom`, `writtenTo` and `writtenPrecision` beside the book's publication date, and the
  date filters and date sort use the written date.

Each result row lists its linked `authors` (id, name, slug), so a hit leads straight to
`/api/v1/library/authors/{id}` and that author's other works.

## Paging

- `/search` ranks passages. The first 1,000 hits are reachable with `offset`; beyond that, pass
  the previous page's `cursor` back as `cursorDoc`, `cursorScore`, `cursorGeneration`.
  `stale: true` means the index changed under the cursor; start again from offset 0.
- `sort=oldest` or `sort=newest` orders `/search` by publication date instead of relevance
  (by `offset` within the first 1,000 hits; the cursor is for relevance order only).
- `/search/publications` groups hits by book or edition, most relevant first.
- `/search/count` returns only hit counts (cheap; good for refining a query).
- `/search/passages/{id}` opens one hit with its reader blocks, highlighted words and the
  previous/next passage ids; `/neighbours` reads around it.

## The Bible

`/api/v1/library/bible/search` (MCP `search_bible`) and `/bible/search/count` (`count_bible_matches`)
take this same language over the Bible's verses, where a passage is one verse. Narrow them with
`translation` (default kjv, or `all`), `scope` (old, new, a book, a chapter such as `Daniel 8`, or
a range such as `Matthew 5-7`) and `wordsOfJesus`; order with `order=relevance` or `order=bible`.
A phrase or proximity match that crosses a verse boundary comes back as a range (James 2:17-18)
after the verses, when no single verse of that chapter matched.

## Photos and illustrations

`/api/v1/library/images/search` (MCP `search_library_images`) takes this same language over the
pictures printed in the library's books and periodicals, where a passage is one picture: its
printed caption and what the AI saw in it (a description and keywords with plain synonyms).
`tag:` searches the keywords, `person:` and `place:` the people and places named, and a Bible
reference the passages a picture illustrates. Narrow with `types` (photograph, engraving, drawing,
painting, map, diagram, chart, cartoon, decoration, document, other), `orientations` (landscape,
portrait, square), `kind` (book or periodical), `collectionIds` and `dateFrom`/`dateTo`; order with
`sort=oldest` or `newest`. An empty query lists every picture within the filters, oldest first.