Quickstart

Fastest path to a working search: install, configure, define a model, and run your first query.

• Ruby 3.1+ and Rails 6.1+ in your host app
• A reachable Typesense node (host/port/protocol); default port is 8108
• TYPESENSE_API_KEY set in your environment (never commit secrets)
• An existing Typesense collection and schema; see Schema

1. Add gem to Gemfile

   # Gemfile
   gem "search-engine-for-typesense"
   

   Then run Bundler to install dependencies in your host app.

2. Run installer

   rails g search_engine:install
   

   This will create a new initializer in config/initializers/search_engine.rb.

   See Generators & Console helpers for more details.

3. Configure the initializer

   # config/initializers/search_engine.rb
   SearchEngine.configure do |c|
     c.host = ENV.fetch("TYPESENSE_HOST", "localhost")
     c.port = 8108
     c.protocol = "http"
     c.api_key = ENV.fetch("TYPESENSE_API_KEY")
     c.default_query_by = "name, description"
   end
   

   • host/port/protocol: where your Typesense node is reachable; defaults are safe for localhost.
   • api_key: read from ENV.fetch(“TYPESENSE_API_KEY”) so secrets never live in code.
   • default_query_by: default fields used when you do not pass query_by explicitly.

   See Configuration for all options and ENV mapping.

4. Define a minimal model

   class SearchEngine::Book < SearchEngine::Base
     collection "books"
     attribute :id, :integer
     attribute :title, :string
   end
   
   SearchEngine::Book.where(title: "ruby").select(:id, :title).limit(5).to_a
   

   Ensure your Typesense books collection exists with at least id (int64) and title (string).

   You can also use a Generator to create a new model:

   rails g search_engine:model Book --collection books --attrs id:integer title:string
   

   This will create a new model in app/models/search_engine/book.rb.

5. Index data (optional convenience)

   You can let the model orchestrate schema and indexing:

   # Create collection + apply schema if needed, reindex, retention cleanup
   SearchEngine::Book.index_collection
   
   # Index a specific partition (collection must exist and be in-sync)
   SearchEngine::Book.index_collection(partition: publisher_id)
   

   See Indexer for details.

6. Rebuild a partition directly (optional)

   For one-off reindexing by key, call the model-level helper:

   SearchEngine::Book.rebuild_partition!(partition: publisher_id)
   SearchEngine::Book.rebuild_partition!(partition: publisher_id, into: "optional_physical_collection")
   

   See Indexer → Partitioning for the partitioning DSL.

7. First query (curl-free)

   Open rails console and paste the trailing line from the snippet above. It runs against Typesense and returns up to 5 Book records with only id and title hydrated. This uses the Relation → Client stack under the hood.

Request flow

Next steps

• Multi‑search: run multiple searches in one network call.
• JOINs: join related collections and select nested fields.
• Grouping: group results and aggregate with counts.

Troubleshooting

• Missing TYPESENSE_API_KEY: set the ENV var before boot; see Configuration → ENV mapping. Tip: the CLI doctor checks this.
• Connection refused or timeout: verify host/port/protocol; see the CLI → Doctor.
• Unknown field errors: declare attributes on the model or adjust selection; see Field selection → Guardrails.

Related links

• Installation
• Configuration
• Client
• Observability — events, logging subscriber, OpenTelemetry
• DX — helpers: dry_run!, to_params_json, to_curl
• Relation — chaining DSL used above