> ## 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.
# Deletion
> Delete documents by filter. Relation-level delete_all, model-level helpers, and low-level API with into/partition/timeout controls.
Related: Indexer, CLI, Troubleshooting
Delete documents by filter from a collection. Use relation‑level convenience for “delete what I just filtered”, model‑level helpers for ad‑hoc deletes, or the low‑level API when you need full control.
Safety: With no filters, relation deletion uses a safe match‑all filter id:!=null. Prefer targeted filters; consider Indexer → Stale Deletes for recurring cleanup flows with guardrails.
## Relation‑level: delete\_all
```ruby theme={null}
# Delete all published=false books (compiled to filter_by)
SearchEngine::Book.where(published: false).delete_all
# Override physical collection and partition context if needed
SearchEngine::Book
.where(publisher_id: 123)
.delete_all(into: "books_20251011_120000_001", partition: 123, timeout_ms: 5_000)
```
* Compiles current where AST to filter\_by and sends DELETE /documents.
* When the relation has no predicates, falls back to id:!=null (match‑all).
* Options:
* into: physical collection name (skip alias resolution)
* partition: forwarded to the resolver (see below)
* timeout\_ms: read timeout override for the delete call
### Flow
```mermaid theme={null}
flowchart TD
R[Relation filters] --> C[Compile filter_by]
C --> D[Deletion.delete_by]
D --> H[DELETE /collections/:into/documents?filter_by]
```
## Model‑level: delete\_by
Use either a filter string or a Hash that will be converted safely.
```ruby theme={null}
# String form
SearchEngine::Book.delete_by("archived:=true && publisher_id:=123")
# Hash form (converted via Sanitizer)
SearchEngine::Book.delete_by(archived: true, publisher_id: 123)
# With options
SearchEngine::Book.delete_by(
{ archived: true }, into: "books_20251011_120000_001", partition: 123, timeout_ms: 2_000
)
```
Rules:
* Provide either a non‑blank String or a non‑empty Hash. An empty input raises.
* into: overrides the target physical collection.
* partition: is passed to the resolver (see next section).
* Return value is the number of deleted documents the server reports.
## Instance‑level: delete (single record)
Delete a single hydrated record by its document id.
```ruby theme={null}
book = SearchEngine::Book.find_by(book_id: 123123)
book.delete # => 1 when deleted, 0 when nothing matched
# Options (parity with relation delete_all)
book.delete(into: "books_20251011_120000_001", partition: 123, timeout_ms: 2_000)
```
Notes:
* The record id is taken from hydrated id when present, otherwise computed via the model’s identify\_by strategy.
* If the id cannot be determined, an error is raised.
* Calling delete on a Relation is not supported; use delete\_all.
## Low‑level helper: SearchEngine::Deletion.delete\_by
```ruby theme={null}
SearchEngine::Deletion.delete_by(
klass: SearchEngine::Book,
filter: "archived:=true",
into: nil, partition: nil, timeout_ms: nil
)
```
### Into resolution
The target collection is resolved in order:
* Explicit into: option when provided
* Contextual into from instrumentation (used during schema apply/indexation)
* SearchEngine.config.partitioning.default\_into\_resolver if configured
* Fallback to the model’s logical collection name (klass.collection)
This allows deletes to target a just‑created physical during blue/green apply before the alias is swapped.
### Timeouts
timeout\_ms: overrides the read timeout. When omitted, it falls back to
SearchEngine.config.stale\_deletes.timeout\_ms when set; otherwise the client default is used.
## When to use Indexer stale deletes
Prefer Indexer → Stale Deletes when you routinely delete by a known filter. It offers:
* Centralized stale rules on the model (declared inside index)
* Strict‑mode guardrails to block suspicious catch-alls
* Optional estimation and events for observability
Use relation/model deletion for one‑off cleanup or admin tooling where you have the exact filter already.
## Troubleshooting
* Empty input: delete\_by requires a filter string or a non‑empty hash
* Deleted 0 docs unexpectedly: check into: (physical vs alias) and filter
* Partitioned setups: pass partition: so your resolver can pick a target
* Timeouts: increase timeout\_ms for large deletes
Backlinks: Home, CLI, Indexer, Troubleshooting