> ## 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. # 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 ⤴](#query-cookbook-%E2%80%94-common-patterns) ## Recipes ### Exact match Small set lookup by ID. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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. ```ruby theme={null} 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: ```ruby theme={null} 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 ⤴](#query-cookbook-%E2%80%94-common-patterns) ## 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: ```ruby theme={null} 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.