Client

Thin wrapper around the official typesense Ruby gem. Single-search and federated multi-search with URL/common cache knobs and normalized errors.

Related: Relation, Multi-search, DX

SearchEngine::Client

A thin wrapper around the official typesense Ruby gem that provides single-search and federated multi-search. It enforces that cache knobs live in URL/common params (never in per-search bodies) and normalizes gem/network failures into SearchEngine::Errors.

Usage

Prefer SearchEngine.client to get the configured client instance. It respects SearchEngine.config.client when set, returns OfflineClient in test mode, or creates a new Client instance:

client = SearchEngine.client
client.search(collection: "books", params: { q: "milk", query_by: "name" },
              url_opts: { use_cache: true })
client.multi_search(
  searches: [
    { collection: "books", q: "milk", query_by: "name", per_page: 5 },
    { collection: "authors", q: "mil", query_by: "name", per_page: 3 }
  ],
  url_opts: { use_cache: true, cache_ttl: 30 }
)

You can also instantiate SearchEngine::Client directly when you need a specific instance:

client = SearchEngine::Client.new
client.search(collection: "books", params: { q: "milk", query_by: "name" },
              url_opts: { use_cache: true })

Top-level convenience returning raw:

SearchEngine.multi_search_raw(
  common: { query_by: SearchEngine.config.default_query_by }
) do |m|
  m.add :books, SearchEngine::Book.per(5)
  m.add :authors, SearchEngine::Author.per(3)
end

# Clear server-side cache (Typesense `/operations/cache/clear`)
SearchEngine::Cache.clear

Note: The default Typesense client connection timeout is 60 minutes, to avoid aborting long-running writes. You can override it, and you can introduce retry jitter by using a Range for retries[:backoff]. See Configuration.

Example override:

SearchEngine.configure do |c|
  c.timeout_ms = 3_600_000
  c.retries = { attempts: 3, backoff: 10.0..60.0 }
end

Cache management

• SearchEngine::Cache.clear issues a POST /operations/cache/clear via the client and returns the symbolized Typesense response. Call it after large imports or schema changes when you need fresh cached results immediately.
• Emits search_engine.cache.clear (see Observability) so subscribers/loggers capture cadence and duration; uses SearchEngine.client so injected clients and test mode are honored.
• Reference: Typesense cluster operations → Clear cache.

Operations helper (SearchEngine.operations)

Use the convenience wrapper when you need instrumented, redacted operational calls (no request body needed):

SearchEngine.operations.metrics   # GET /metrics.json
SearchEngine.operations.stats     # GET /stats.json
SearchEngine.operations.health    # GET /health

• Accepts optional client: for dependency injection; otherwise uses SearchEngine.client (respects injected clients, test mode, or builds a new instance).
• Emits search_engine.operations.* events; payloads are redacted and safe for dashboards/health checks.

Client helper (SearchEngine.client)

Use SearchEngine.client to access the configured client instance. It follows this precedence:

1. Returns SearchEngine.config.client if explicitly set (e.g., StubClient)
2. Returns SearchEngine::Test::OfflineClient if test_mode? is true
3. Otherwise creates and returns a new SearchEngine::Client instance

This helper ensures consistent client access across the codebase and respects test mode automatically.

Request flow

URL/common params vs body

Parameter	Location
use_cache	URL/Common
cache_ttl	URL/Common
q	Body/Params
query_by	Body/Params
filter_by	Body/Params
per_page	Body/Params

Errors

Public errors are exposed via SearchEngine::Errors:

• Timeout: request exceeded timeout budget
• Connection: DNS/socket/TLS/connect failures
• Api: non‑2xx Typesense responses (carries status and body)
• InvalidParams: wrapper pre‑call validation problems

See lib/search_engine/errors.rb for details.

Internals boundary

• SearchEngine::Client::RequestBuilder assembles concrete request shapes (HTTP method, path, body) from compiled params. It has no network concerns.
• SearchEngine::Client::HttpAdapter executes an assembled request using the injected Typesense::Client. It has no knowledge of Typesense domain semantics.
• These roles clarify responsibilities; there is no change to public behavior.

Troubleshooting

• Timeout / Connection: Check host/port/protocol and network reachability.
• API errors: Inspect status and server body. 4xx are not retried; 5xx/429 may be transient.

API Reference

Collection Management

• create_collection(schema): Create a physical collection.
• update_collection(name, schema): PATCH an existing collection (add/drop fields) without reindexing when Typesense deems the change compatible.
• delete_collection(name, timeout_ms: nil): Delete a collection.
• retrieve_collection_schema(name): Fetch schema for a physical collection.
• list_collections: List all collections.
• upsert_alias(alias, physical): Point an alias to a physical collection.
• resolve_alias(alias): Get the physical name for an alias.

Document Operations

• create_document(collection:, document:): Create a single document.
• retrieve_document(collection:, id:): Fetch a document by ID.
• update_document(collection:, id:, fields:): Partially update a document.
• delete_document(collection:, id:): Delete a document by ID.
• import_documents(collection:, jsonl:, action: :upsert): Bulk import.
• delete_documents_by_filter(collection:, filter_by:): Delete by query.
• update_documents_by_filter(collection:, filter_by:, fields:): Update by query.

Server Operations

• health: Check server health.
• metrics: Retrieve metrics (JSON).
• stats: Retrieve stats (JSON).
• list_api_keys: List configured API keys.
• clear_cache: Clear server-side cache.

Synonyms & Stopwords

• synonyms_upsert(collection:, id:, terms:)
• synonyms_list(collection:)
• synonyms_get(collection:, id:)
• synonyms_delete(collection:, id:)
• stopwords_upsert(collection:, id:, terms:)
• stopwords_list(collection:)
• stopwords_get(collection:, id:)
• stopwords_delete(collection:, id:)

Backlinks: Home

See Observability for emitted events and compact logging.