Skip to main content
  • 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