> ## 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.
# 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.
```mermaid theme={null}
flowchart LR
subgraph Relation state
A[".joins(:authors)"] --> B["select_nested (include_fields)"]
A --> C["ast (where)"]
A --> D[orders]
end
B & C & D --> E[Compiler]
E --> F["include_fields/filter_by/sort_by"]
E --> G["_join context"]
```
## DSL
Declare associations on your model using belongs\_to / belongs\_to\_many / has\_one / has\_many:
```ruby theme={null}
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.
```ruby theme={null}
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: \\_id
* foreign\_key: \\_id
* has\_many (deterministic):
* collection: plural of the first argument
* local\_key: \\_id
* foreign\_key: \\_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:
```ruby theme={null}
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
# => # or nil
author.reviews
# => # (chainable)
author.reviews.where(published: true)
# => #
```
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)
```ruby theme={null}
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:
```ruby theme={null}
SearchEngine::Book
.joins(:authors, :orders)
.where(authors: { last_name: "Rowling" })
.where(orders: { total_price: 12.34 })
.order(authors: { last_name: :asc })
```
```mermaid theme={null}
flowchart LR
R[Relation] -- "joins(:authors)" --> S["State joins=[authors]"]
S -- "joins(:orders)" --> S2["joins=[authors, orders]"]
```
* 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.
```ruby theme={null}
# 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.
```ruby theme={null}
# 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
```ruby theme={null}
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