> ## 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.
# Cascading
> Keep referencing collections consistent when a referenced document changes. Discovery, partial vs full reindex, usage, and instrumentation.
Related: Schema, Indexer, Joins, Observability, References & JOINs — Deep dive
### Cascading updates for referenced collections
Keep referencing collections consistent when a referenced document changes. This page covers discovery of references, partial vs full reindex, usage, and emitted instrumentation.
#### Overview
* Discovery: Build a reverse reference graph from Typesense live schemas (preferred) using field-level reference (e.g., "authors.id"). Falls back to compiled local schemas from SearchEngine models when Typesense is unavailable.
* Scope: Single-hop only. Immediate cycles (A ↔ B) are detected and skipped.
* Reindex: On document update, attempt a targeted partial reindex of referencing collections when safe; otherwise perform a full reindex of each referencing collection.
```mermaid theme={null}
flowchart TD
U[Base#update(cascade: true)] --> T[Typesense partial update]
T --> C[SearchEngine::Cascade]
C --> G[Build reverse refs graph]
G -->|referencers| R1[Referrer collection 1]
G -->|referencers| R2[Referrer collection 2]
R1 -->|ActiveRecord + no Partitioner| P1[partial reindex by foreign_key]
R1 -->|else| F1[full reindex]
R2 -->|ActiveRecord + no Partitioner| P2[partial reindex by foreign_key]
R2 -->|else| F2[full reindex]
```
#### Reference discovery
* From Typesense: GET /collections → for each GET /collections/{name}; inspect each field’s reference value.
* Fallback: compile each registered model schema and use its reference annotations generated from belongs\_to :assoc (stored as "\.\", or ;async variant when enabled).
Notes:
* Only single-hop references are considered. Multi-hop is not supported.
* Immediate cycles (e.g., A references B and B references A) are skipped to avoid ping-pong reindex.
Manual targeted rebuild (when you opt into bi‑directional joins and still need a refresh):
```ruby theme={null}
# Refresh referencers by foreign key (example keys)
SearchEngine::Indexer.rebuild_partition!(
SearchEngine::Book,
partition: { author_id: [42] }
)
```
#### Partial vs full reindex
* Partial reindex is attempted only when both conditions hold:
* Referencing collection uses the ActiveRecord source adapter, and
* No custom Partitioner is configured for that collection.
* Partial strategy: call `Indexer.rebuild_partition!(Referrer, partition: { foreign_key => ids })` so the ActiveRecord source applies where(foreign\_key: ids).
* Full fallback:
* Triggered when partial is not eligible, or raises unexpectedly.
* Always used when context: :full.
#### Partitioned referencers and parallelism
* When a referencer collection defines partitioning via the index DSL (partitions, partition\_fetch), cascade full reindex will honor partition\_max\_parallel and process partitions concurrently, mirroring full indexation behavior. If partition\_max\_parallel \<= 1 or there is only one partition, processing remains sequential.
#### Usage
* Opt-in cascade on instance update:
```ruby theme={null}
record.update(name: "New Name", cascade: true)
```
* Explicit API:
```ruby theme={null}
# After updating an Author with id "42":
SearchEngine::Cascade.cascade_reindex!(source: Author, ids: ["42"], context: :update)
# After a full collection rebuild of Authors:
SearchEngine::Cascade.cascade_reindex!(source: Author, ids: nil, context: :full)
```
Behavior:
* context: :update: prefer partial reindex; fallback to full per referencer.
* context: :full: always full reindex for all referencers.
#### Instrumentation
Emits search\_engine.cascade.run via ActiveSupport::Notifications with keys:
* source\_collection (String)
* ids\_count (Integer)
* context (:update | :full)
* targets\_total (Integer)
* partial\_count, full\_count (Integers)
* skipped\_unregistered (Integer)
* skipped\_cycles (Array of pairs)
* outcomes (Array): `{ collection, mode: :partial | :full | :skipped_unregistered | :skipped_cycle }`
#### Caveats
* Single-hop only; deeper paths are out of scope.
* Partial reindex requires the ActiveRecord source and no Partitioner.
* Cascade runs best-effort; errors are swallowed when triggered from Base#update to preserve update semantics.
Backlinks: Schema · Indexer · Joins · Observability