> ## 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.
# Multi-search Guide
> Patterns for federating multiple labeled searches: builder DSL, per-search overrides, result handling, Rails controller usage, and DX.
Concise reference for running multiple labeled searches in a single Typesense round‑trip, handling results, and applying safe URL‑level caching.
* What it is: federates multiple Relations into one request; results are mapped back to labels in order.
* When to use: homepage modules, typeahead+categories, federated search blocks; prefer it over multiple sequential calls to reduce latency.
* When not to use: completely independent pages with different lifecycles or when strong isolation/errors per request are critical.
### Builder DSL
Use `SearchEngine.multi_search(common: …) { |m| m.add(label, relation) }`. The common: hash is shallow‑merged into each compiled relation payload; per‑search values from the relation win on key conflicts.
Required verbatim example:
```ruby theme={null}
res = SearchEngine.multi_search(common: { query_by: SearchEngine.config.default_query_by }) do |m|
m.add :books, SearchEngine::Book.where(category_id: 5).per(5)
m.add :publishers, SearchEngine::Publisher.where("name:~rud").per(3)
end
res[:books].to_a
```
Minimal variations:
* Override pagination per search while inheriting common::
```ruby theme={null}
res = SearchEngine.multi_search(common: { q: "milk", per_page: 50, query_by: SearchEngine.config.default_query_by }) do |m|
m.add :books, SearchEngine::Book.all.per(10) # per_page=10 overrides common 50
m.add :publishers, SearchEngine::Publisher.all # inherits per_page=50
end
```
* Add field selection per search:
```ruby theme={null}
res = SearchEngine.multi_search(common: { q: "*", query_by: SearchEngine.config.default_query_by }) do |m|
m.add :books, SearchEngine::Book.select(:id, :name).per(6)
m.add :publishers, SearchEngine::Publisher.select(:id).per(3)
end
```
See example controller: examples/demo\_shop/app/controllers/search\_controller.rb.
### Per‑search overrides
Per‑relation chainers and options(...) override or augment common: on a per‑entry basis:
* where/filters → filter\_by
* order → sort\_by
* select/exclude → include\_fields/exclude\_fields
* page/per → page/per\_page
* options(q: ..., query\_by: ..., infix: ...) map into the compiled body
Example (per‑search query\_by and filters override common:):
```ruby theme={null}
res = SearchEngine.multi_search(common: { q: params[:q].presence || "*", query_by: SearchEngine.config.default_query_by }) do |m|
m.add :books, SearchEngine::Book.where(active: true).options(query_by: "name,description").per(6)
m.add :publishers, SearchEngine::Publisher.where(["name PREFIX ?", params[:q].to_s.first(12)]).per(3)
end
```
Guardrails:
* Consistent query\_by per collection: ensure each collection’s fields exist; unknown fields raise during compile when strict field checks are enabled.
* URL‑only knobs: use\_cache, cache\_ttl live at the URL level and are filtered from both common: and per‑search bodies.
### Result handling with MultiResult
SearchEngine.multi\_search returns SearchEngine::Multi::ResultSet (hash‑like). If you prefer a dedicated wrapper, use SearchEngine.multi\_search\_result which returns SearchEngine::MultiResult.
* Hash‑like access: res\[:books] (matches the labels you added)
* Each entry is a SearchEngine::Result with #to\_a, #found, #empty?, #raw, etc.
* Order is preserved; labels are case‑insensitive symbols internally.
From the snippet above, res\[:books].to\_a returns hydrated hits for the :books entry.
Example with MultiResult directly:
```ruby theme={null}
mr = SearchEngine.multi_search_result(common: { q: params[:q].presence || "*", query_by: SearchEngine.config.default_query_by }) do |m|
m.add :books, SearchEngine::Book.per(6)
m.add :publishers, SearchEngine::Publisher.per(3)
end
products = mr[:books]
publishers = mr[:publishers]
count = products&.found.to_i
empty = publishers&.empty?
```
Partial failures: if Typesense returns per‑entry error statuses inside a 200 response, inspect entry.raw to branch UI gracefully (avoid raising globally):
```ruby theme={null}
entry = mr[:publishers]
if (code = entry&.raw&.fetch("code", 200).to_i) != 200
# render a soft error for this box, keep other boxes
else
# render hits
end
```
### Controller usage patterns (Rails)
Keep controllers thin; build relations with only request‑dependent inputs and pass a single multi‑result to the view.
```ruby theme={null}
class HomeController < ApplicationController
def index
q = params[:q].to_s
page = params[:page]
per = params[:per]
common = { q: q.presence || "*", query_by: SearchEngine.config.default_query_by }
books_rel = SearchEngine::Book.where(active: true).per(6)
publishers_rel = SearchEngine::Publisher.where(["name PREFIX ?", q.first(24)]).per(3)
@results = SearchEngine.multi_search_result(common: common) do |m|
m.add :books, books_rel
m.add :publishers, publishers_rel
end
# Suggested fragment cache key derived from stable URL inputs
@cache_key = ["home/index", params.slice(:q, :page, :per, :filters).to_unsafe_h]
end
end
```
Caching notes:
* Prefer URL/request‑level cache keys derived from stable inputs (e.g., params.slice(:q, :page, :per, :filters)).
* Multi‑search uses URL‑level cache knobs from config: `{ use_cache: SearchEngine.config.use_cache, cache_ttl: SearchEngine.config.cache_ttl_s }`.
* Per‑relation options(use\_cache:, cache\_ttl:) are not applied in the multi‑search path; set them via config for multi‑search.
* Consider setting HTTP cache headers at the controller/edge layer based on those inputs; avoid embedding secrets.
### Compile flow
```mermaid theme={null}
flowchart LR
R[Relations] --> M[Multi builder]
M --> C[Compiler (per search)]
C --> P[Multi payload]
P --> CL[Client]
CL --> TS[Typesense]
TS --> MR[MultiResult]
```
### DX & debugging
Prefer network‑safe introspection for demos and debugging:
```ruby theme={null}
rel = SearchEngine::Book.where(category_id: 5).per(5)
rel.dry_run! # => { url:, body:, url_opts: } with redaction
rel.to_curl # one‑liner with redacted API key
puts rel.explain # multi‑line overview (no network I/O)
```
* See the DX page for details and redaction policy.
* For fully offline tests/examples, use the stub client approach in the Testing page.
### Presets & Curation in multi‑search
Applied per relation. Each m.add carries its own preset/curation context and compiles independently.
* Presets: per‑search preset and preset\_mode (merge/only/lock) are honored during compile.
* Curation: pinned\_hits, hidden\_hits, curation\_tags, filter\_curated\_hits are emitted body‑only when present.
See the dedicated Presets and Curation docs for details and caveats.
### Edge cases & troubleshooting
* Misaligned query\_by: ensure each collection’s fields exist; validate with rel.explain and rel.dry\_run!.
* Unknown fields: selection and filtering validate against declared attributes; fix names or disable strictness per environment.
* Mixed grouping: grouping options are compiled per relation; UI should handle grouped vs non‑grouped results independently.
* Differing per/page: expected; each box paginates independently.
* Partial failures: the helper augments raised API errors with failing label when the HTTP status is non‑2xx; for 2xx with per‑entry errors, inspect result.raw per label and degrade gracefully.
* Redaction: never print API keys or raw filter\_by directly; use dry\_run!, to\_curl, or explain which apply redaction.
***
### Related links
* Multi-search
* Client
* Relation Guide
* DX
* Observability
* Testing
* Troubleshooting