> ## 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. # Relation > Immutable, chainable query object bound to a model class. Accumulates normalized query state without mutation. Related: Client, Compiler, Observability, DX See also: Debugging & Explain and DX helpers Relation is an immutable, chainable query object bound to a model class. It accumulates normalized query state without mutating previous instances. ## Quick start ```ruby theme={null} class SearchEngine::Book < SearchEngine::Base; end r_1 = SearchEngine::Book.all r_2 = r_1.where(category: 'fiction').order(:title).select(:id, :title).page(2).per(10) # r_1 is unchanged r_1.object_id != r_2.object_id #=> true r_1.empty? #=> true ``` ## Immutability Every chainer creates a new instance via copy-on-write. The original relation remains unchanged. ```ruby theme={null} r_1 = SearchEngine::Book.all r_2 = r_1.where(price: 10) r_1.object_id #=> 701... r_2.object_id #=> 702... r_1.empty? #=> true r_2.empty? #=> false ``` ## API * all: returns the relation itself (parity with AR). * where(\*args): add filters. Accepts Hash, String/Symbol, arrays thereof. * order(value): add order expressions. Accepts Hash or String. * select(\*fields) / exclude(\*fields) / reselect(\*fields): field selection DSL. See Field Selection and JOINs. * limit(n), offset(n), page(n), per(n): numeric setters; coerced with validation (see below). * options(opts = {}): shallow-merge additional options for future adapters. * empty?: true when state equals the default empty state. * inspect: AR-style preview that materializes up to 11 hydrated records and renders #\. The 11th slot is rendered as ... when there are more than 10 records. To restore the previous zero‑I/O concise summary, set SearchEngine.config.relation\_print\_materializes = false. See Materializers for execution methods (to\_a, each, first, last, take, pluck, ids, count, exists?). Note: .find(id) exists only on the model class as a convenience alias for find\_by(id: id). It is intentionally not available on relations. ## Lifecycle ```mermaid theme={null} flowchart LR A[Model.all] --> B[Relation] B --> C[where/order/select] C --> D[Pagination] D --> E[Compiler] E --> F[Typesense params] ``` See also: Compiler. See Client for execution context. *** ## Filtering with where Use where with hash input, a template, or a raw fragment. Each call ANDs predicates. ```ruby theme={null} SearchEngine::Book .where(published: true) .where(["price >= ?", 100]) .where("category_id:=[1,2,3]") ``` * Hash form validates fields when attributes are declared. * Template form uses ? placeholders and safe quoting. * Raw strings are passed through as an escape hatch. * Call .joins(:assoc) before filtering on joined fields. * Use .where.not(...) to negate predicates. For predicate parsing rules and AST details, see Query DSL. ## order / select / pagination ```ruby theme={null} SearchEngine::Book .order(updated_at: :desc) .select(:id, :title) .page(2).per(20) ``` * order(value): accepts a Hash like `{ field: :asc, other: :desc }` or a String like "field:asc,other:desc". Directions are case-insensitive and normalized to asc/desc. Duplicate fields are de-duplicated with last-wins semantics. * where\_geo(field, within\_radius: / within\_polygon:): geo filter by radius or polygon. See Geo Search. * order\_geo(field, from:, direction:): sort by distance from a reference point. See Geo Search. * order\_eval(expression, direction:): sort by a Typesense \_eval() conditional expression. See Geo Search. * select(\*fields): accepts symbols/strings or arrays; trims and de-duplicates preserving first occurrence. If the model declares attributes, unknown fields raise. See Field Selection. * limit(n) / offset(n): numeric. limit >= 1, offset >= 0. * page(n) / per(n): numeric. page >= 1, per >= 1. The per(n) method writes to per\_page internally. ### Compiled params and debugging * Relation#to\_typesense\_params: compile immutable state to a Typesense body params object. * Relation#to\_h: return the compiled params as a Hash (deterministic order). * Relation#inspect: preview hydrated results; control with SearchEngine.config.relation\_print\_materializes. For compilation rules and parameter mapping, see Compiler and Debugging.