Ruby on Rails

Getting started with Ruby on Rails and Bonsai Elasticsearch is fast and easy. Sign up and create your first cluster to get started.

The following guide is for a simple integration. We will go through what gems to use, how to set up your client and your app, and how to index data. Finally, we’ll walk through a basic way to set up a search page and display results.


These instructions are for users who want to use the official Elasticsearch Rails client. If you’re using something like SearchKick, refer to the SearchKick documentation.

Set up the Elasticsearch client

Add your cluster URL to your environment

We recommend adding your Bonsai Elasticsearch cluster URL to your environment (.env files) as a variable so you don’t introduce security concerns by hard-coding it into your app. Add your cluster url to your .env file:


Next, add the bonsai-elasticsearch-rails gem to your Gemfile:

gem 'bonsai-elasticsearch-rails'


The bonsai-elasticsearch-rails gem is a wrapper to include and and initialize the elasticsearch-rails and elasticsearch-model gems in your app. You can always use those gems directly:

  gem 'elasticsearch-model'
  gem 'elasticsearch-rails'

and initialize a client:

      Elasticsearch::Model.client = url: ENV['BONSAI_URL']

Apps should use the bonsai-elasticsearch-rails gem OR the model and rails gem plus an initializer, but not both. Setting up both will cause bugs later on.

Prepare models and rake tasks

Prepare your models to be indexed and searched by your cluster by including Elasticsearch::Model:

class User < ActiveRecord::Base
  include Elasticsearch::Model
  include Elasticsearch::Model::Callbacks



Do this for any model you want to be searchable. Recall that Elasticsearch::Model is available to your app because the gem bonsai-elasticsearch-rails installs elasticsearch-model for you. See the full project for documentation here:

Explicitly limit what you index

We advise that you explicitly state what fields for your models you want to send to Elasticsearch. For example:

class User < ApplicationRecord
  include Elasticsearch::Model
  include Elasticsearch::Model::Callbacks

  # only send to Elasticsearch what we care about searching and running stats on
  def as_indexed_json(*_)
      only: [:name, :email]

Create a rake task

Define a rake task to import your models. Create a file lib/tasks/elasticsearch.rake:

require 'elasticsearch/rails/tasks/import'


The elasticsearch-rails gem will create a new index for every searchable model.

Index data

Bonsai does not support “lazy” index creation. In other words, you will need to explicitly create your index before you can put documents there. There are a few ways to do this. The best way is to use the rake task you (should have) set up in the last step. The first time you index your content, you’ll want to set the FORCE parameter.

Run the rake task to import your data

rake environment elasticsearch:import:all FORCE=Y

The FORCE parameter will explicitly delete and recreate indices, so you probably don’t want to use it frequently. Subsequent indexing tasks can drop this parameter.

If rake tasks aren’t possible for some reason, you could also create your indices with with curl. So if you have a User model, then you could use the following command to create the index:

curl -XPUT

You would need to repeat this for every model you plan to index.

Quick import commands

  • To import the records from a specific model, run: rake environment elasticsearch:import:model CLASS='User'

  • To limit the scope of the records imported, run: rake environment elasticsearch:import:model CLASS='User' SCOPE='active'

  • Force rebuilding the index (delete and create): `rake environment elasticsearch:import:model CLASS=‘Article’ FORCE=Y

  • Customize the batch size: rake environment elasticsearch:import:model CLASS='Article' BATCH=100

  • Set target index name: rake environment elasticsearch:import:model CLASS='Article' INDEX='articles-new'

Further reading

Elasticsearch Rails gem:

Elasticsearch-model gem: