Query Cookbook — Common Patterns

Copy minimal, production-ready patterns and adapt fields to your models. Use dry_run!/explain to debug without I/O.

Related: Relation, Query DSL, DX

Intro

Copy these minimal patterns and adapt fields to your models. Prefer dry_run! and explain to debug locally without network I/O.

Index of patterns

• Exact match
• Prefix/infix match
• Any of list (IN)
• Price range + sort
• Pagination
• Facet filters
• Faceting DSL
• Pinned/hidden curation
• Grouping top‑N
• Joins — basic
• Geo search + distance sort
• Viewport boost with _eval()
• Multi‑search two relations

Back to top ⤴

Recipes

Exact match

Small set lookup by ID.

SearchEngine::Book.where(id: 42)

Why it works / gotchas:

• Simple Eq predicate; validated field name
• Use arrays for IN (see below)
• Links: Query DSL → Builders

---

Prefix/infix match

Begins‑with or contains‑like filters via templates/raw.

SearchEngine::Book.where(["name PREFIX ?", "mil"])  # prefix
SearchEngine::Book.where("name:~=milk")               # infix (raw)

Why / gotchas:

• PREFIX is parsed to AST; infix shown as raw Typesense fragment
• Consider query text in q for full‑text; this is a filter
• Links: Query DSL, Compiler

---

Any of list (IN)

Match any of several brands.

SearchEngine::Book.where(author_id: [1, 2, 3])

Why / gotchas:

• Non‑empty arrays only; values coerced per attribute type
• Links: Query DSL → Parsing examples

---

Price range + sort

Use two comparators for numeric ranges.

SearchEngine::Book
  .where(["price >= ?", 100])
  .where(["price <= ?", 200])
  .order(price: :asc)

Why / gotchas:

• Typesense has no range literal in filter_by; use >= and <=
• Links: Compiler → Quoting & types

---

Pagination

Classic page/per; prefer this over limit/offset unless you need offset math.

SearchEngine::Book.page(2).per(20)

Why / gotchas:

• page >= 1, per >= 1; wins over limit/offset
• Links: Relation → order/select/pagination

---

Facet filters

Combine multiple filters with AND semantics across calls.

SearchEngine::Book
  .where(category: "dairy")
  .where(author_id: [1, 2])
  .where(["price <= ?", 500])

Why / gotchas:

• Each where appends; compiled with AND
• Links: Query DSL → Where it fits

---

Pinned/hidden curation

Pin two IDs and hide one; keep network‑safe while inspecting.

rel = SearchEngine::Book.pin("p_12", "p_34").hide("p_99")
rel.dry_run!

Why / gotchas:

• Curation keys are body‑only; redacted in logs
• Hide wins when an ID is both pinned and hidden
• Links: Curation, Observability

---

Grouping top‑N

First hit per group, up to N hits inside each.

SearchEngine::Book.group_by(:author_id, limit: 2)

Why / gotchas:

• group_limit caps hits per group; pagination applies to number of groups
• Links: Grouping

---

Joins — basic

Filter on a joined collection field.

SearchEngine::Book
  .joins(:authors)
  .where(authors: { last_name: "Rowling" })
  .include_fields(authors: [:first_name])

Why / gotchas:

• Call .joins(:assoc) before referencing $assoc.field
• Links: Joins, Compiler

---

Geo search + distance sort

Filter by radius and sort nearest-first; access distance on results.

results = SearchEngine::Venue
  .where_geo(:location, within_radius: { lat: 54.69, lng: 25.28, radius: "10 km" })
  .order_geo(:location, from: { lat: 54.69, lng: 25.28 })
  .to_a

Why / gotchas:

• Field must be declared as :geopoint in the model
• geo_distance_meters is available on hits when order_geo is used
• Links: Geo Search

---

Viewport boost with _eval()

Boost documents inside a map viewport polygon, with distance tiebreaker.

SearchEngine::Venue
  .order_eval("location:(54.72,25.35, 54.72,25.22, 54.67,25.22, 54.67,25.35)", direction: :desc)
  .order_geo(:location, from: { lat: 54.69, lng: 25.28 })
  .to_a

Why / gotchas:

• order_eval wraps the expression in _eval() — do not add _eval() yourself
• Weighted form: order_eval([{ expr: "...", weight: 3 }, { expr: "...", weight: 1 }])
• Links: Geo Search → order_eval

---

Multi‑search two relations

Send two labeled relations in one round‑trip.

res = SearchEngine.multi_search do |m|
  m.add :books, SearchEngine::Book.where(category: "dairy").per(5)
  m.add :publishers,   SearchEngine::Publisher.where(["name PREFIX ?", "mil"]).per(3)
end

Why / gotchas:

• Per‑search params compiled independently; order preserved by labels
• Links: Multi‑search

---

Debug each recipe

Use explain or dry_run! to preview without I/O:

rel = SearchEngine::Book.where(active: true).order(updated_at: :desc).per(10)
puts rel.explain
rel.dry_run!

Redaction policy hides literals and secrets; bodies remain copyable.

Back to top ⤴

Edge‑case callouts

• Quoting: strings double‑quoted; booleans and null literal; arrays flattened one level
• Boolean coercion: only for boolean‑typed fields; strings “true”/“false” accepted
• Empty arrays: invalid for membership; provide at least one value
• Reserved characters: prefer templates with placeholders to avoid manual escaping
• Ambiguous names: unknown fields raise with suggestions when attributes are declared
• Sort vs group order: sort applies before grouping; group order preserved

---

Related links: Query DSL, Compiler, DX, Observability, Joins, Grouping, Presets, Curation

Faceting DSL

Add facets and facet queries:

rel = SearchEngine::Book
  .facet_by(:author_id, max_values: 20)
  .facet_query(:price, "[0..9]", label: "under_10")

res = rel.execute
res.facet_values("author_id") # => array of { value:, count:, ... }

See Faceting for details.