CLI

Operator-focused tasks for schema lifecycle and indexing. Thin facades over documented APIs with structured instrumentation.

Related: TUIT, Troubleshooting → CLI, Observability → OpenTelemetry

Operator-focused tasks for schema lifecycle and indexing. All tasks are thin facades over documented APIs with small, structured instrumentation.

Commands

rails 'search_engine:schema:diff[collection]'
rails 'search_engine:schema:apply[collection]'
rails 'search_engine:schema:rollback[collection]'
rails 'search_engine:schema:prune_orphans[collection]'
rails 'search_engine:index:rebuild[collection]'
rails 'search_engine:index:rebuild_partition[collection,partition]'
rails 'search_engine:index:delete_stale[collection,partition]'
rails search_engine:doctor

• collection: either a fully-qualified class name (e.g., SearchEngine::Book) or a logical identifier (e.g., book/books).
• partition: opaque partition key. Numeric strings are parsed as integers; otherwise treated as strings.

Usage

• Show tasks: rails -T | grep search_engine
• Diff schema: rails ‘search_engine:schema:diff[SearchEngine::Book]’
• Apply schema: rails ‘search_engine:schema:apply[books]’
• Rollback schema: rails ‘search_engine:schema:rollback[books]’
• Prune orphans: rails ‘search_engine:schema:prune_orphans[books]’ (or omit [collection] for all)
• Rebuild all partitions: rails ‘search_engine:index:rebuild[SearchEngine::Book]’
• Rebuild a partition: rails ‘search_engine:index:rebuild_partition[SearchEngine::Book,42]’
• Delete stale docs: rails ‘search_engine:index:delete_stale[books,42]’
• Doctor diagnostics: rails search_engine:doctor

Note: rails -T always prints task names without quotes (e.g., rails search_engine:index:rebuild[collection]). When invoking tasks that use brackets, wrap the whole invocation in quotes to avoid shell globbing, e.g., rails ‘search_engine:index:rebuild[products]’.

Tip about commas: quote or avoid spaces inside brackets.

rails 'search_engine:index:rebuild_partition[SearchEngine::Book,42]'

Environment flags

• DRY_RUN=1: For index:rebuild, preview first batch only (no HTTP); for index:delete_stale, show filter hash and estimation (if enabled) without deleting.
• DISPATCH=inline|active_job: Override dispatch mode for rebuild tasks (defaults from config).
• VERBOSE=1: Print additional details (e.g., schema diff JSON and dry-run sample line). For doctor, shows untruncated hints.
• FORMAT=json: Machine-readable output. For doctor, prints { ok, summary, checks }.
• STRICT=1: For index:delete_stale, treat missing filter as violation.
• TIMEOUT=seconds: For doctor, override per-request timeout for health/API calls.
• HOST/PORT/PROTOCOL: For doctor, temporary overrides to test connectivity.

Exit codes

Code	Meaning
0	Success
1	Error
2	Rollback not possible
3	Strict safety violation
10	Schema drift detected (diff)

Behavior summary

• schema:diff: Compares compiled schema vs the active physical (via alias). Prints compact summary; VERBOSE=1 dumps details. Exits 10 when drift exists.
• schema:apply: Creates a new physical, reindexes (all partitions), swaps alias, drops old physicals per retention. Prints a compact summary.
• schema:rollback: Swaps alias to previous retained physical. Exits 2 when none available.
• schema:prune_orphans: Scans physical collections matching the timestamped naming pattern and drops any that are not alias targets. Optional [collection] scopes to one logical name; omit to scan all. Prints dropped/kept counts.
• index:rebuild: If partitions DSL exists, enumerates and dispatches per partition; otherwise a single inline run. DRY_RUN=1 maps only the first batch and prints a preview. Does not perform alias swaps or retention cleanup; use schema:apply for blue/green and retention.
• index:rebuild_partition: Rebuilds a single partition; respects DISPATCH or config defaults.
• index:delete_stale: Compiles stale rules (declared inside index) into an OR‑merged filter and deletes by filter. If no rules produce a filter: warns and exits 0, or 3 with STRICT=1. DRY_RUN=1 prints preview without deleting.
• doctor: Validates config/ENV presence, connectivity (health), API key validity, alias resolution for registered collections, compiles a dry-run single search and a multi-search without I/O, reports logging mode, and OpenTelemetry status. Prints human-readable by default or JSON with FORMAT=json. Exits 1 on any failure.

Doctor flow

Backlinks: Observability → OpenTelemetry, Installation, Configuration

See also: Configuration and Observability for logging and OTel.

Live progress

On TTY terminals, schema lifecycle and indexation tasks display animated progress using braille spinners and per-partition progress bars. Each lifecycle step (Presence, Schema, Indexing, Retention) shows real-time status via StepLine. Parallel partition imports render a multi-line LiveRenderer with doc-based progress percentages and elapsed time. On non-TTY (CI, pipes), output falls back to static one-line-per-event logging.

For StepLine, Spinner, and LiveRenderer, see Observability → Live progress (TTY).

Safety notes

• Stale deletes never run with an empty filter. A short hash of the filter is printed for traceability.
• Partition keys are opaque. Numeric strings are converted to integers; other values remain strings.
• Failed indexation during schema:apply prevents the alias swap; the new physical is left for inspection. See Schema → Failed indexation safety.

See also

• Schema — compiler, diff, apply! and rollback
• Indexer — import flow, dry-run, partitioning, dispatcher
• Observability