docs(search): document the interactive and batch search modes

[tomaz-lc]

Details

Documents the optional mode field on POST /v1/search, which lets a client declare how it intends to consume a paginated search. interactive is the default and favors time to first results with smaller pages. batch favors total throughput over the whole result set with fewer, larger pages, so the complete set arrives after fewer round trips.

The field is an intent, not a size. The client never sends a row count, the server decides the page size, and results and their ordering are identical in both modes. Only the placement of page boundaries changes.

What is documented

• When to use each mode. Batch mode is for API and script clients, and for any query that is read all the way to the end: exports, bulk retrieval, backfills, scheduled jobs, and automation. Interactive stays the default for user-facing search, and for anything sampled rather than exhausted.
• The trade-off. Each individual page takes longer to come back in batch mode, the full result set arrives sooner, and time to the first row within a page is unchanged.
• How the field is sent. Once, on the POST that starts the search. Continuation pages fetched with the pagination token inherit it, so it is neither resent nor carried in the token. A request example shows the field in the body.
• That it is a hint, not an instruction. The server decides the mode each page runs in, and that decision can differ from what was requested in either direction: a search can run in batch mode without asking for it, and a search that asked for batch mode can run as interactive. What the selection is based on is documented as server-side and subject to change, so a client is told not to depend on a given search running in a given mode. Three things bound it: the server may select the mode itself, batch mode is enabled per organization, and batch mode applies only to a paginated search. A GROUP BY, an ORDER BY, or an aggregation over all records runs without pagination and is unaffected.
• What a refused request actually does. Asking for batch mode where it is not enabled does not pin the search to interactive. The client's field is dropped and the rest of the resolution runs, so an organization whose default is batch still gets batch. The page says the search runs in whatever mode the server would have chosen had the field not been sent.
• That it is safe to send. An unrecognized value, a differently-cased spelling such as "Batch", and a non-string value are all ignored and treated as though the field were omitted, so the request does not fail on the field.
• The three stats every page reports about what it actually ran as: searchMode, pageSize and paginatedByteCap, all omitted for a search that ran without pagination. A note explains that pageSize is not a promise about a row count, since a page can end below it or slightly above it.
• Batch mode as an efficiency practice, listed with the other ones. Every page costs a fixed amount of work and one network round trip regardless of how many rows it carries, so fewer and larger pages spend less of the run on that fixed cost. The saving grows with the number of pages fetched and is largest when the result set is read to the end. Throughput and total time change; the rows and their order do not.

Where it lives

The reference material is a new ## Search Modes section in docs/4-data-queries/query-limits-and-performance.md, placed after Data Sources and before Concurrent Queries. That page already documents pagination, page shape, the paged versus whole-timeline distinction that decides whether the mode applies at all, and the per-page stats, so the new material sits next to everything it refers to and reuses those anchors.

The same page gains ### Fetch Large Result Sets in Batch Mode under ## Writing Efficient and Performant Queries, alongside Prefer Projections, Narrow the Scope Early and the rest, plus one ### Anti-patterns entry for paging a large export to the end in the default interactive mode. A reader asking how to make a query faster lands in that section rather than in the reference one, so the advice lives there and links to Search Modes for how to request the mode and what comes back. Search Modes links forward to it in turn, so neither copy repeats the other.

docs/4-data-queries/index.md gains a short ### Choose a Search Mode subsection between Run an LCQL Query and Validate Query Syntax. That page is where the search request body is documented, so it carries the one-paragraph summary and the request example and links onward for the detail.

No new page is added, and no existing wording is rewritten beyond one sentence in the intro of the limits page that now also names search modes.

Checks

• mkdocs build --strict passes.
• markdownlint-cli2 with the repo config reports 0 errors across all pages.
• scripts/check-list-numbering.py, scripts/check-release-note-headings.py and scripts/check-release-feeds.py all pass against the built site, and pytest tests/ is green.
• The generated anchors (#search-modes, #when-to-use-batch-mode, #requesting-a-mode, #what-each-page-reports, #fetch-large-result-sets-in-batch-mode), the cross-page link from the Query Console page, and the links between the two new sections were verified in the built output.

🤖 Generated with Claude Code