DOCUMENT SEARCH & ANSWERS
What is a passage?
A piece of a document small enough to be about one thing: a few paragraphs under one heading, with its page number. It is the unit a search finds and an assistant cites.
- Employee Handbook 202749 pages
- One result for fifty topics
- You still have to read it
- Nothing to cite but the file
- One result for one topic
- Opens on the right page
- Small enough to quote and to cite
The problem with whole documents
Suppose a search over documents could only return files. You ask how long you have to file an expense claim, and the result is the Employee Handbook 2027: correct, and nearly useless. The handbook is 49 pages long. The answer is one sentence on page 29. The search has done the easy part and left you the hard one.
The same problem is worse for an AI assistant. Hand a model the whole handbook for every question and three things go wrong: it costs more and takes longer each time, most of what the model reads has nothing to do with the question, and when it answers there is nothing to point to but the file. An answer that can only say "it is in the handbook" is not an answer anyone can check.
The fix for both is the same, and it is old: do not treat the document as the unit. Treat a piece of it as the unit, and keep track of where each piece came from.
What a passage is
A passage is a stretch of a document small enough to be about one thing. In practice that means a few paragraphs under one heading: the section on filing deadlines, the section on annual leave balances, one clause of a contract. Each passage is stored with the text itself and with enough labels to find its way home: the document it belongs to, the heading it sits under, the page it is on, and its position in the reading order.
The filing deadline passage in the handbook is passage 28, on page 29, under the heading "Filing deadline and claim preparation". Those labels are what turn a matching piece of text into something a person can act on. "Submit claims within 10 working days" is a sentence. "Employee Handbook 2027, page 29" is a source.
The idea adapts to the kind of file. In a presentation the natural piece is a slide; in a spreadsheet, a sheet; in a transcript, a span of time. What stays constant is that the piece is small, self-contained, and knows where it came from.
How passages are cut
- Follow the structureStart a new passage at each heading, and keep paragraphs whole.heading → paragraphs
- Keep to a sizeA few hundred words, so a passage stays about one thing.about 300 words
- Overlap a littleRepeat a sentence or two, so nothing is lost at the cut.a sentence or two
- Label itEach passage keeps its heading, its page and its place in the document.page 29 · passage 28
The cutting follows the document's own structure first. A heading starts a new passage, because the author already decided that what follows is a separate subject. Paragraphs are kept whole, because a paragraph cut in half is two halves of a thought.
Structure alone is not enough, since some sections run for pages. So there is a size limit as well, usually a few hundred words; about 300 words is a common target. A long section becomes several passages, each still under the same heading.
The last detail is overlap. Where a long section is cut, the next passage repeats a sentence or two from the end of the previous one. It looks wasteful and is deliberate: an answer that straddles the cut would otherwise belong fully to neither passage, and be found by neither.
Why size matters
Passage size is the one setting in a document search system that genuinely trades one good against another.
Make passages large, a page or more, and each one carries plenty of context, but the thing you were looking for is diluted by everything around it. A search by meaning scores the passage on what it is about overall, and a page about six subjects is not strongly about any of them. The model reading it gets more noise with its signal.
Make them small, a sentence or two, and each one is sharply about one thing, but stripped of what gives it sense. "Within 10 working days" matches a question about deadlines beautifully and no longer says what the deadline is for. The heading label helps here, which is one reason it is kept.
A few paragraphs under one heading is where most systems settle, because that is roughly the size at which a human author also thinks one thing has been said.
Passages and meaning
Search by meaning depends on passages more than keyword search does. A model turns a piece of text into coordinates that stand for what it is about, and compares those with the coordinates of the question; Keyword vs semantic vs hybrid search explains how. One set of coordinates for a whole handbook would have to stand for joining, leave, travel and IT at once, and would sit near none of them. One set per passage puts the expense deadline where a question about expense deadlines will find it.
This is also why a document usually gets a second, separate entry made from its summary. That entry answers "which files are about this subject"; the passages answer "where does it say so". How documents become searchable shows both views of one search.
Passages and citations
When an assistant answers from documents, the passage is what it cites. The model is given a handful of passages, each with a number, and marks its statements with the numbers it relied on. A citation is therefore not a vague pointer to a file. It is a link to a specific few paragraphs, with a heading and a page, that either support the statement or do not. How an AI answer gets its citations follows one answer through that process.
That only works because the passage is the exact text of the document. It is not a summary and not a paraphrase. What the person opens when they click a citation is what the author wrote.
When passages go wrong
Cutting text is mechanical, and documents are not always cooperative. A table that runs across two pages can be split between two passages, each holding half the rows. A numbered list can lose its introduction, so that step four arrives without the sentence saying what the steps are for. Running headers and footers, the document title and "page 29 of 49" printed on every page, end up inside every passage and add a little noise to each.
None of this is fatal, and it is better known than discovered. Overlap repairs some of it. Hybrid search repairs more, because the right words still match even when the meaning has been diluted. And a document that searches badly is nearly always a document that was hard to read in the first place: a scan with no text behind it, or a layout where the reading order is ambiguous to a person too.
What to look for
Passages are an internal detail until they are not, so it is worth seeing them. A good system lets you open any document and read its passages in order, with their headings and pages, exactly as the search and the assistant see them. If a document keeps giving poor answers, that view is where the reason shows: a section that was cut badly, a page that came out empty, a table that turned into a column of loose numbers.
Sizes are usually counted in tokens, the units a language model reads, at roughly four characters each; a passage of about 400 tokens is around 300 words, and an overlap of about 40 tokens is a sentence or two. Each passage gets a stable id derived from its document and its position, so indexing a changed document again replaces its passages in place and removes any that no longer exist.
A passage record carries the text, the heading, the page number, character and token counts, and a copy of the parent document's filterable fields - workspace, category, tags, type - so a filter on those can be applied to passages directly, without a join. The vector for search by meaning is stored on the same record.