DX

Developer-experience helpers: to_params_json, to_curl, dry_run!, explain, generators, and console helpers.

Related: Debugging, Troubleshooting → DX

Developer‑experience helpers on Relation visualize compiled requests and enable a safe, zero‑I/O dry run.

• Relation#to_params_json(pretty: true) — redacted JSON body after compile. Pretty output has stable key ordering for copy/paste and diffs.
• Relation#to_curl — single‑line cURL with POST to the resolved endpoint, JSON body, and redacted API key.
• Relation#dry_run! — compiles and validates without network I/O; returns { url:, body:, url_opts: }.
• Relation#explain — extended overview with grouping, joins, presets/curation, conflicts, correlation ID preview (when present), and predicted events.

Helpers & examples

rel = SearchEngine::Book
        .where(active: true)
        .order(updated_at: :desc)
        .select(:id, :name)
        .page(2).per(20)

rel.to_params_json
# => "{\n  \"filter_by\": \"active:=***\", ... }"

rel.to_curl
# => "curl -X POST https://host/... -H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: ***' -d '{...}'"

rel.dry_run!
# => { url: "https://host:8108/collections/products/documents/search", body: "{...}", url_opts: { use_cache: true, cache_ttl: 60 } }

puts rel.explain # shows NOT IN formatting for membership negation

Event prediction (no emit)

Use rel.explain to preview which events would fire without emitting them:

Events that would fire: search_engine.compile → search_engine.joins.compile → search_engine.grouping.compile → search_engine.search

Redaction policy

• All helpers are pure and do not mutate the relation.
• dry_run! validates and returns a redacted body; no HTTP requests are made.
• Redaction follows observability rules, masking secrets and literals.

Generators & Console helpers

Install and scaffold minimal models using Rails generators:

rails g search_engine:install
rails g search_engine:model Product --collection products --attrs id:integer name:string

In rails console, use inline helpers: SE.q(“milk”), SE.ms { |m| m.add :books, SE.q("milk").per(5) }.

• Default model resolution: set SearchEngine.config.default_console_model (Class or String). If unset, the helper falls back to the single registered model; ambiguous cases raise with a hint.
• Options: SE.q accepts select:, per:, page:, and where:. Any remaining options are forwarded to the relation via options(…).

Backlinks: Quickstart, Relation, Multi‑search, Observability

Troubleshooting

• No default model configured: Set SearchEngine.config.default_console_model = ‘SearchEngine::Book’ or ensure only one model is registered.
• Unknown attribute type: Allowed types include string, integer, float, boolean, datetime, time, datetime_string, time_string, json. See Field selection → Guardrails and Troubleshooting.