JOINs

Declare associations, query across collections, select nested fields, and understand server vs client-side fallbacks.

Related: Observability, Field selection, Troubleshooting → Joins, References & JOINs — Deep dive

Server‑side joins require lightweight association metadata declared on your model class. This page documents the model‑level DSL, the per‑class registry, how the relation compiles joined selections/filters/sorts, and the instrumentation emitted during compile. It also documents the client‑side fallback for shared‑key joins when a Typesense reference is unavailable.

See example: examples/demo_shop/app/controllers/books_controller.rb.

Overview

• Declare associations on your model with belongs_to :name, has_one :name, and has_many :name (options: collection:, local_key:, foreign_key:; async_ref: for belongs_to).
• Select joins in queries with Relation#joins(*assocs); names validated against the model’s registry.
• Use nested include fields for joined collections; where/order can target joined fields using $assoc.field.
• Observe compile‑time summaries via search_engine.joins.compile without exposing raw literals.

DSL

Declare associations on your model using belongs_to / belongs_to_many / has_one / has_many:

class SearchEngine::Book < SearchEngine::Base
  collection "books"
  attribute :id, :integer
  attribute :author_id, :string  # Reference fields must be :string or [:string]

  # Auto‑resolve keys for a one‑to‑one/one‑to‑many style link
  belongs_to :author

  # For outgoing has‑style links (deterministic)
  has_many :orders, foreign_key: :book_id
end

• name (Symbol/String): logical association name.
• collection (Symbol/String): target Typesense collection name (auto‑resolved from name).
• local_key (Symbol/String): local attribute used as the join key (auto‑resolved; overrideable).
• foreign_key (Symbol/String): foreign key in the target collection (auto‑resolved; overrideable).
• async_ref (Boolean, belongs_to / belongs_to_many only): mark the reference asynchronous in schema.

Declaring references

When declaring a belongs_to or belongs_to_many association, the local_key attribute must be declared with type :string or [:string] in your model. Typesense requires reference fields to be strings, and the schema compiler validates this during compilation.

class SearchEngine::Order < SearchEngine::Base
  collection :orders

  # Reference fields must be :string or [:string]
  attribute :customer_id, :string
  attribute :book_ids, [:string]  # Array of references

  belongs_to :customer, local_key: :customer_id
  belongs_to_many :books, local_key: :book_ids
end

If you declare a reference field with a different type (e.g., :integer), schema compilation will raise an error with guidance to update the attribute declaration.

Auto‑resolution rules

• belongs_to / belongs_to_many (association‑name based):
  • collection: plural of the first argument
  • local_key: singular(name)_ids when the argument is plural; else singular(name)_id
  • foreign_key: singular(name)_id
• has_one (deterministic):
  • collection: plural of the first argument
  • local_key: <current_singular>_id
  • foreign_key: <current_singular>_id
• has_many (deterministic):
  • collection: plural of the first argument
  • local_key: <current_singular>_id
  • foreign_key: <current_singular>_ids

Override defaults with explicit collection:, local_key:, or foreign_key:.

Instance association readers (AR-like hop)

Declaring belongs_to, belongs_to_many, has_one, or has_many also defines an instance method with the same name that resolves referenced records using the join config.

Example:

module SearchEngine
  class Author < Base
    collection :authors
    attribute :author_id, :integer
    attribute :category_id, :integer, optional: true

    belongs_to :category
    has_many :reviews, foreign_key: :author_ids
  end
end

module SearchEngine
  class Category < Base
    collection :categories
    attribute :category_id, :integer

    has_many :authors, foreign_key: :category_id
    has_many :reviews
  end
end

module SearchEngine
  class Review < Base
    collection :reviews
    identify_by :review_id
    attribute :book_id, :string  # Reference fields must be :string
    attribute :author_ids, [:string], empty_filtering: true  # Array references must be [:string]
    attribute :category_ids, [:string], empty_filtering: true

    belongs_to :authors, async_ref: true
    belongs_to :categories, async_ref: true
  end
end

author = SearchEngine::Author.take
author.category
# => #<SearchEngine::Category ...> or nil

author.reviews
# => #<SearchEngine::Relation [...]]> (chainable)

author.reviews.where(published: true)
# => #<SearchEngine::Relation [...]]>

Behavior:

• belongs_to (singular name): returns a single record via find_by(foreign_key: local_value); returns nil when local value is nil.
• belongs_to (plural or when local value is an Array): returns a Relation scoped with where(foreign_key: local_array); empty array yields an empty relation.
• has_one (any name): returns a single record via find_by(foreign_key: local_value); returns nil when local value is nil.
• has_many (any name): always returns a Relation scoped with where(foreign_key: local_value); nil local value yields an empty relation.
• belongs_to_many (any name): always returns a Relation scoped with where(foreign_key: local_value); nil local value yields an empty relation. Use for shared-key one‑to‑many joins.

Notes:

• Methods are defined at declaration time; resolution uses the per‑class join_for(:name) and SearchEngine.collection_for(cfg[:collection]).
• Returned Relation is fully chainable (where, order, joins, etc.).
• Asynchronous belongs_to (async_ref: true) works the same; if the referenced target is missing, the singular call returns nil.

Backlinks: Models · Relation

Shared‑key example (generic)

module SearchEngine
  class Order < Base
    collection :orders
    attribute :order_id, :integer

    # one order → many shipments via shared order_id
    belongs_to_many :shipments, local_key: :order_id, foreign_key: :order_id
  end
end

module SearchEngine
  class Shipment < Base
    collection :shipments
    attribute :order_id, :integer

    # reverse hop: many shipments → one order
    has_one :order, local_key: :order_id, foreign_key: :order_id
  end
end

# Filtering by a joined field
SearchEngine::Order
  .joins(:shipments)
  .where(shipments: { carrier: 'UPS' })

Advanced behavior

• Client-side fallback can run when Typesense references are missing or shared keys are used.
• Asynchronous references are available via async_ref: true on belongs_to.

Quoting and type coercion: Joined-field values are coerced using the target model’s attribute types. If a joined field is typed as :string, numeric inputs are converted to strings and quoted in filter_by (e.g., $calculated_products(store_id:=“1070”)).

See References & JOINs — Deep dive for full rules and caveats.

Relation Usage

Use Relation#joins(*assocs) to select join associations on a query. Names are validated against the model’s joins_config and stored in the relation’s immutable state in the order provided. Multiple calls append:

SearchEngine::Book
  .joins(:authors, :orders)
  .where(authors: { last_name: "Rowling" })
  .where(orders: { total_price: 12.34 })
  .order(authors: { last_name: :asc })

• joins accepts symbols/strings; inputs are normalized to symbols.
• Unknown names raise SearchEngine::Errors::UnknownJoin with an actionable message that lists available associations.
• Order is preserved and duplicates are not deduped by default; explicit chaining is honored.
• For debugging, rel.joins_list returns the frozen array of association names in state.

Backlinks: Overview · Relation · Compiler · Observability · Field Selection

Filtering and Ordering on Joined Fields

With joins applied, you can reference joined collection fields in where and order using nested hashes. Joined left‑hand‑sides render as $assoc.field.

Input (Ruby)	Compiled filter_by	Compiled sort_by
where(authors: { last_name: "Rowling" })	$authors.last_name:=“Rowling”	–
where(orders: { total_price: 12.34 })	$orders.total_price:=12.34	–
order(authors: { last_name: :asc })	–	$authors.last_name:asc
order(“$authors.last_name:asc”)	–	$authors.last_name:asc

Notes:

• Base fields continue to work unchanged (e.g., where(active: true)).
• Mixed base and joined predicates interleave as usual; the compiler preserves grouping semantics.
• Raw order strings are accepted as‑is; ensure you supply valid Typesense fragments.

Nested field selection for joined collections

You can select fields from joined collections using a nested Ruby shape. These compile to Typesense include_fields with $assoc(field,…) segments.

# Full relation example
SearchEngine::Book
  .joins(:authors)
  .include_fields(:id, :title, authors: [:first_name, :last_name])

Compiles to:

$authors(first_name,last_name),id,title

• Input types: mix base fields (:id, “title”) and nested hashes (authors: [:first_name, :last_name]).
• Merging: multiple calls merge and dedupe. First mention wins ordering; later calls append only new fields.

# Merged across calls
SearchEngine::Book
  .include_fields(:id, authors: [:a])
  .include_fields(:title, authors: [:b, :a])
# => "$authors(a,b),id,title"

• Ordering policy: nested $assoc(…) segments are emitted first in association first-mention order, then base fields.
• Validation: association keys are validated against klass.joins_config (UnknownJoin on typos). Calling .joins(:assoc) before selecting nested fields is recommended; the compiler will still emit $assoc(…) even if joins wasn’t chained yet.

End-to-end example with filters and sort

rel = SearchEngine::Book
  .joins(:authors)
  .include_fields(authors: [:first_name])
  .where(authors: { last_name: "Rowling" })
  .order(authors: { last_name: :asc })
rel.to_typesense_params
# => { q: "*", query_by: "name, description", include_fields: "$authors(first_name)", filter_by: "$authors.last_name:=\"Rowling\"", sort_by: "$authors.last_name:asc" }

Internals: the returned params also include a reserved :_join key with join context for downstream components. See Compiler for the exact shape.

---

Common pitfalls

• Declare every association on the model before using .joins(:assoc).
• Use only single-hop paths like $assoc.field.
• Keep joined field names aligned with the target model attributes.

Deep dives

• Reference fields and async refs: References & JOINs — Deep dive
• Joined selection + grouping example: JOINs, Selection, and Grouping
• JOIN instrumentation and logs: Observability