Document Search

Document search is designed so users can inspect matching text before opening a file.

Recommended UX Flow

1. Call POST /v1/search/suggestions while the user types.
2. Call POST /v1/search when the user submits or pauses.
3. Render Document and DocumentContent results with the returned snippet.
4. Show source.pageNumber when present.
5. Track the response searchId.
6. Open the full document only when the user explicitly chooses to.
7. Report preview and open events with POST /v1/search/interactions.

Rendering Document Results

For document-heavy views, prefer this layout:

• title: original filename
• subtitle: object key or storage path context
• preview: snippet
• context badge: Page {source.pageNumber} when available

This gives users enough context to decide whether a document is relevant without downloading or opening it first.

When the user opens the full document, report that interaction against the original searchId. That data is what later lets ranking favor results that are actually opened instead of merely shown.

Rendering DocumentContent Results

Use DocumentContent results when you want to emphasize the exact matching passage:

• keep the parent filename visible
• display the excerpt from snippet
• route to a document preview or viewer anchored to the matching page if your client supports it

Operational Notes

Document previews depend on indexed passage text. If preview text is missing:

• confirm the document is a supported text-extraction format
• trigger POST /v1/search/index/documents/{documentId}
• check GET /v1/search/index/status

For large legacy datasets, queue a backfill so older documents receive passage previews as well.

If clusters, locations, annotations, or document cards themselves are missing from universal search, run the asset backfill endpoint in addition to the document passage backfill.