Skip to main content

​
Overview

Use the update helpers when you need to patch existing documents in Typesense without re-mapping the full dataset. These APIs reuse the compiled schema and validation path, and respect partition/alias resolution. Related: Upsert, Deletion, Indexer.

​
APIs

​
Instance: SearchEngine::Base#update

  • Partially updates a hydrated record (uses its document id or identify_by fallback).
  • Signature: record.update(attrs, into: nil, partition: nil, timeout_ms: nil, cascade: nil).
  • Returns 1 on success, 0 if nothing was updated.
book = SearchEngine::Book.find_by(id: "B-1")
book.update(title: "New title", price_cents: 1299, cascade: true)
Notes:
  • cascade: true triggers a best-effort cascade reindex of referencing collections.
  • Fails when the id cannot be determined; include id in selection or define identify_by.

​
Relation: SearchEngine::Relation#update_all

  • Updates all documents matching the current relation filters.
  • Signature: rel.update_all(attrs, into: nil, partition: nil, timeout_ms: nil).
  • Empty relation filters fall back to a safe match-all id:!=null.
SearchEngine::Book.where(published: false).update_all(archived: true, timeout_ms: 2000)

​
Low-level: SearchEngine::Update.update_by

  • Filter-driven update without a relation.
  • Signature: Update.update_by(klass:, attributes:, filter: nil, hash: nil, into: nil, partition: nil, timeout_ms: nil).
  • Accepts either a Typesense filter string (filter:) or a Hash converted via the Sanitizer (hash:).
SearchEngine::Update.update_by(
  klass: SearchEngine::Book,
  attributes: { featured: true },
  hash: { publisher_id: 42 },
  into: "books_20251011_120000_001"
)

​
Options & Resolution

  • into: — override physical collection; defaults to alias or partition resolver.
  • partition: — forwarded to partition resolver and cascade contexts.
  • timeout_ms: — optional read timeout override for the update request.

​
When to use vs upsert/indexer

  • Use update: targeted patches to a known set of documents; small scope; you already know ids or filters.
  • Use upsert: when you need to re-map source records (ActiveRecord/SQL) or send pre-mapped hashes with schema validation.
  • Use indexer: for large-scale rebuilds, partitioned workflows, or when schema drift needs to be handled.

​
Safety tips

  • Provide explicit filters; match-all is allowed but should be intentional.
  • Keep payloads small; Typesense applies the provided fields as partial updates.
  • Combine with timeout_ms for long-running operations, and consider cascade: true on instance updates when referencers exist.