> ## 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.
# ActiveRecordSyncable
> Keep a Typesense collection in sync with your ActiveRecord model. Upserts on create/update and deletes on destroy.
Related: Models, Indexer, Deletion, Client
## ActiveRecordSyncable (ActiveRecord Concern)
Keep a Typesense collection in sync with your ActiveRecord model. When enabled, the concern upserts on create/update and deletes on destroy so your Typesense documents mirror your database rows.
Note: Formerly named SearchEngine::Syncable. It has been renamed to SearchEngine::ActiveRecordSyncable.
### Quick start
```ruby theme={null}
class Product < ApplicationRecord
include SearchEngine::ActiveRecordSyncable
# Defaults: on: %i[create update destroy], collection: :books
search_engine_syncable
end
```
Callbacks run synchronously using `after_create_commit`/`after_update_commit`/`after_destroy_commit` by default (post-transaction). `SearchEngine.config.indexer.dispatch` does **not** affect these hooks. Use the background-job pattern below if you need async behavior.
With explicit options:
```ruby theme={null}
class Order < ApplicationRecord
include SearchEngine::ActiveRecordSyncable
search_engine_syncable collection: :orders, on: %w[create destroy]
end
```
### Defaults and validation
* collection: inferred from model name (tableize, e.g., Product → "books").
* Upserts require a SearchEngine::\ mapping for that logical collection.
* If the mapping is missing at boot, a warning is logged and the concern will attempt lazy resolution later. When still unavailable at upsert time, it logs and skips upsert (no exception).
* on: defaults to \[:create, :update, :destroy].
* Accepts a single symbol/string or an array; values are normalized case‑insensitively.
### What the concern does
* Registers callbacks on your AR model (installed once per class reload):
* after\_create\_commit → upsert document (post-transaction)
* after\_update\_commit → upsert document (post-transaction)
* after\_destroy\_commit → delete document (post-transaction)
* Upserts call your SearchEngine model: SearchEngine::\.upsert(record: ...) using your mapping (see Indexer and Models).
* Deletes compute the document id using the SearchEngine model’s identify\_by when present, otherwise fall back to record.id.
* Target collection resolution prefers alias → physical mapping when available (see Schema).
```mermaid theme={null}
sequenceDiagram
participant AR as ActiveRecord
participant SE as SearchEngine::
participant TS as Typesense
AR->>AR: after_create_commit / after_update_commit
AR->>SE: upsert(record)
SE->>TS: POST /collections/:into/documents/import (action=upsert)
AR->>AR: after_destroy_commit
AR->>TS: DELETE /collections/:into/documents/:id
```
### Lazy resolution & error handling
* Mapping resolution is best‑effort at boot; if unavailable, a one‑time warning is logged. The concern resolves the SearchEngine model lazily on first use.
* Upsert/delete errors are logged and swallowed to avoid interrupting AR lifecycle callbacks (see logs under search\_engine\_syncable).
### Instance helpers
* record.search\_engine\_record → fetch the associated Typesense document as a hydrated SearchEngine::\ instance.
* Uses the SearchEngine model’s identify\_by to compute id; falls back to record.id when not defined.
* Returns nil when the model mapping is unavailable or the document is missing.
```ruby theme={null}
doc = Book.first.search_engine_record
# => # or nil
```
* record.sync\_search\_engine\_record → map and upsert this ActiveRecord instance to the collection.
* Returns 1 when upserted, 0 on error; failures are logged.
```ruby theme={null}
Book.first.sync_search_engine_record
# => 1
```
### Performance & Async
The default `after_*_commit` callbacks execute **synchronously** but only after the database transaction commits.
* **Configuration Ignored**: The `SearchEngine.config.indexer.dispatch` setting (`:active_job` etc.) **does not apply** here. That setting controls bulk rebuilds only.
* **For High Throughput**: If you need background processing to avoid blocking user requests, disable the concern's auto-sync and manually enqueue a job.
```ruby theme={null}
class Product < ApplicationRecord
# Disable auto-sync
include SearchEngine::ActiveRecordSyncable
search_engine_syncable on: []
after_commit :enqueue_search_update, on: %i[create update destroy]
def enqueue_search_update
SearchIndexJob.perform_later(self.class.name, id)
end
end
# app/jobs/search_index_job.rb
class SearchIndexJob < ApplicationJob
def perform(class_name, id)
record = class_name.constantize.find_by(id: id)
return unless record
# Manual sync
record.sync_search_engine_record
end
end
```
### Callback timing
By default, `ActiveRecordSyncable` uses `after_create_commit` / `after_update_commit` / `after_destroy_commit` callbacks, which fire after the database transaction commits. This is safer — it avoids syncing documents for records that may be rolled back.
To restore the legacy in-transaction behavior (`after_create` / `after_update` / `after_destroy`):
```ruby theme={null}
SearchEngine.configure do |c|
c.syncable_callback_timing = :after_save
end
```
### Migration from Syncable
* Replace:
```ruby theme={null}
include SearchEngine::Syncable
```
with:
```ruby theme={null}
include SearchEngine::ActiveRecordSyncable
```
No other API changes are required; keep using search\_engine\_syncable.
### Troubleshooting
* "Upsert skipped: no SearchEngine model": create a SearchEngine model and mapping for the collection; see Models and Indexer.
* "Cannot delete without id": ensure your SearchEngine model defines identify\_by (or that the AR record’s id is usable).
* Unknown collection behavior: the concern resolves the target via alias or logical name; override collection: when needed.
### Reference
* Upserting helpers: Upsert
* Deletion helpers: Deletion
* Client wrapper: Client