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.
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
Next, add the
bonsai-elasticsearch-rails gem to your Gemfile:
bonsai-elasticsearch-rails gem is a wrapper to include and and initialize the
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 = Elasticsearch::Client.new 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
class User < ActiveRecord::Base include Elasticsearch::Model include Elasticsearch::Model::Callbacks ... end
Do this for any model you want to be searchable. Recall that Elasticsearch::Model is available to your app because the gem
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(*_) as_json( only: [:name, :email] ) end end
Create a rake task
Define a rake task to import your models. Create a file
elasticsearch-rails gem will create a new index for every searchable model.
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
Run the rake task to import your data
rake environment elasticsearch:import:all FORCE=Y
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 http://username:firstname.lastname@example.org/users
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'
Elasticsearch Rails gem: