> ## Documentation Index
> Fetch the complete documentation index at: https://nikita-shkoda.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Hit Limits
> Cap backend work early and validate total hits after fetch. DSL, compiler mapping, and DX surfaces.
This page explains how to cap or validate the number of matching hits for a query.
* Early limit: proactively cap work at the backend when supported.
* Post‑fetch validation: assert a hard upper bound on total hits and raise when exceeded.
## DSL usage
Verbatim:
```ruby theme={null}
SearchEngine::Book.limit_hits(1_000).validate_hits!(max: 10_000)
```
Common combinations:
* Apply only an early limit to avoid over‑fetching when you only need a small page.
* Add a post‑fetch validator to guard against unexpectedly broad queries in production.
## Compiler mapping
* Early limit: The Typesense API has no canonical total‑hits cap parameter. As a conservative fallback, the compiler lowers per\_page when it exceeds the early limit. This avoids over‑fetching on the first page but does not emulate a hard cap across pages.
* Validation note: A non‑transmitted internal note is attached for DX so dry\_run! and explain can show that a validator will run.
## Materializers
The validator runs once per materialization and only after the first response is available, using the backend’s total hits field (found). It applies to:
* to\_a, each, first, last, take, pluck, ids
* count, exists? (via a minimal metadata fetch)
For multi‑search, each search is validated independently.
## Troubleshooting
* Repeated errors: Narrow your filters or increase validate\_hits!(max:).
* Multi‑search failures: Treat offending searches independently; raise or log details with labels where available.
* per lower than expected: This is the conservative per\_page adjustment from limit\_hits(n); increase your early limit if appropriate.
## DX surfaces
* dry\_run! shows the compiled body with any per\_page adjustment and notes about a pending validator.
* explain summarizes early limit, per adjustment, and the validator threshold.
## Backlinks
* Relation Guide
* DX
* Materializers
* Observability
* Troubleshooting