Here’s how to get started with Bonsai Elasticsearch and Ruby on Rails using Chewy.


Chewy is built on top of the official Elasticsearch Ruby client, which is not supported on Bonsai after version 7.13. This is due to a change introduced in the 7.14 release of the gem. This change prevents the Ruby client from communicating with open-sourced versions of Elasticsearch 7.x, as well as any version of OpenSearch. The table below indicates compatibility:

Engine Version Highest Compatible Gem Version
Elasticsearch 5.x 7.13
Elasticsearch 6.x 7.14+ ( sic)
Elasticsearch 7.x 7.13
OpenSearch 1.x 7.13

If you are receiving a Elasticsearch::UnsupportedProductError, then you'll need to ensure you're using a supported version of the Elasticsearch Ruby client.


As of January 2021, Chewy supports up to Elasticsearch 5.x. Users wanting to use Chewy will need to ensure they are not running anything later than 5.x. Support for later versions is planned.

Add Chewy to the Gemfile

In order to use the Chewy gem, add the gem to the Gemfile like so:
gem 'chewy'
Then run bundle install to install it.

Write an Initializer

A Chewy initializer will need to be written so that the Rails app can connect to your Bonsai cluster.
You can include your Bonsai cluster URL (located in Credentials of Bonsai dashboard) in the initializer, but hard-coding your credentials is not recommended. Instead, export them manually in the application environment to an environment variable called BONSAI_URL.
We recommend using something like dotenv for this, but you can also set it manually like so:
# Substitute with your own Bonsai cluster URL:
export BONSAI_URL=""
Heroku users will not need to do so, as their Bonsai cluster URL will already be in a Config Var of the same name.
Create a file called config/initializers/chewy.rb. With the environment variable in place, save the initializer with the following:
Chewy.settings = {
   host: ENV['BONSAI_URL']
The official Chewy documentation has more details on ways to modify and refine Chewy’s behavior.

Configure Your Models

Any Rails model that you will want to be searchable with Elasticsearch will need to be configured to do so by creating a Chewy index definition and adding model-observing code.
For example, here’s how we created an index definition for our demo app in app/chewy/users_index.rb:
class UsersIndex < Chewy::Index
   define_type User
Then, the User model is written like so:
class User < ApplicationRecord
   update_index('users#user') { self }
You can read more about configuring how a model will be ingested by Elasticsearch in the official Chewy documentation.

Indexing Your Documents

The Chewy gem comes with some Rake tasks for getting your documents into the cluster. Once you have set up your models as desired, run the following in your application environment:
bundle exec rake chewy:deploy
That will push your data into Elasticsearch and synchronize the data.

Next Steps

Chewy is a mature ODM with plenty of great features. Toptal (the maintainers of Chewy) have some great documentation exploring some of what Chewy can do: Elasticsearch for Ruby on Rails: A Tutorial to the Chewy Gem.