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:

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::
  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:
  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:):

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:

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):

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.

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

DX & debugging

Prefer network‑safe introspection for demos and debugging:

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