Reviewing chunks

Retrieval does not search your document. It searches the pieces your document was cut into. This page is about looking at those pieces and fixing the ones that are wrong.

Most of the time you never need to. Open this screen when an answer is wrong in a way the model cannot explain — a citation that points at a page number, a heading that arrived detached from the paragraph under it, an agent that keeps quoting a disclaimer nobody asked about.

Seeing what was indexed

Open a collection, then a document. The left pane shows the original file; the right pane lists its chunks in order. For a PDF, each chunk is drawn as a coloured box over the page it came from, so you can see exactly where one ends and the next begins. Selecting a chunk on either side highlights it on the other.

If the file cannot be rendered — an unusual PDF, a format with no visual form — switch to Parsed text to see what the parser actually extracted. That view is worth a look on its own: retrieval only ever sees the parsed text, so anything missing there is missing everywhere, and that is a parsing problem rather than a chunking one.

On a collection chunked hierarchically, the chunk list and the parsed-text view both group passages under a header naming the section, its page range and its size, and the page view draws a dashed outline around the section’s passages. Disabling a passage removes it from the section an agent receives as well as from search; merging two passages is only possible within a section — “Merge with next” is unavailable across a section boundary.

curl -s "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents/$DOC_ID/chunks" \
  -H "Authorization: Bearer $KOVAC_API_KEY"

The four things you can do to a chunk

Edit its text, when the parser mangled something — a table flattened into a run-on line, a ligature that came through as a control character. Editing re-embeds that chunk, so the change reaches retrieval immediately.

Split it, when two unrelated topics ended up together. You choose the character offset to cut at, and the two halves keep the original’s metadata.

Merge it into its neighbour, in either direction, when one idea was cut in half — the classic case being a heading stranded from the paragraph it introduces.

Disable it, when the text is fine but retrieval should not see it: page furniture, a repeated legal footer, a table of contents. A disabled chunk stays visible here, dimmed, and stops appearing in every search — from the preview, from agents, from the API. It is not deleted, and you can re-enable it. Prefer disabling over deleting the document when only part of it is noise.

# Disable one chunk. Toggling `enabled` does not re-embed anything.
curl -s -X PATCH \
  "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents/$DOC_ID/chunks/$CHUNK_ID" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled": false}'

The rule worth knowing before you start

Re-chunking a document discards every manual edit to it.

Chunk edits belong to the chunks that exist now. Re-chunking builds new ones from the parsed text — different boundaries, different count — and there is nothing for the old edits to attach to. So the platform does not try to reapply them, and does not silently drop them either: when a document has hand-edited chunks, a re-chunk asks you to confirm first, and says so in as many words.

A document with manual edits is marked edited in the document table, so you can tell before you act.

This matters because re-chunking is not always something you set out to do. Changing a collection’s chunking settings, or re-indexing after an embedding-model change, re-chunks everything in it. If you have curated a document by hand, settle the collection’s settings first and curate afterwards — not the other way round.

Trying settings before committing to them

If a document looks badly cut, the problem is usually the collection’s chunking settings rather than that one file. You can see what different settings would produce without changing anything:

curl -s -X POST \
  "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents/$DOC_ID/chunk-preview" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"chunk_strategy": "structure", "chunk_size": 800}'

The preview chunks the stored parsed text and returns the result and its statistics. Nothing is written, nothing is re-embedded, and the document’s real chunks are untouched — so comparing fixed against structure on a document you know well is a cheap way to decide.

Checking that it worked

Curation is only useful if retrieval agrees. The Search preview screen runs the same hybrid-plus-rerank pipeline an agent’s search tool uses, so a query there is the real answer to “would this still come back?”

Turn on the candidate view while you are there. It shows what was retrieved before reranking, which separates two failures that look identical from the outside: a chunk that was retrieved and ranked below the cut-off, and a chunk that was never retrieved at all. The first is a ranking problem. The second is a retrieval one, and no amount of reranking will fix it.