How to install and setup the Ruby client for Elasticsearch


Ruby is a very popular programming language that has been enabled to function on the Elastic program suite. This makes it possible to use their client to make and modify changes when you install and set up Ruby for Elasticsearch. This one more way the service has been made friendly to users that already have experience with older tools. Follow along while we explain each step to get this tool up and running for regular use with Elastic products.

  • Here’s a short, albeit incomplete, list of some Ruby libraries, wrappers, frameworks, and gems for Elasticsearch:
  • Stretcher: Ruby client.
  • Elastics: A tiny client with integrated ActiveRecord and zero-downtime migrations.
  • Chewy: Chewy is a wrapper and ODM for the official client Elasticsearch
  • Searchkick: Easy intelligent search
  • Estella: Makes the Ruby models searchable
  • Elastic has an official Github repository for its Ruby low-level client library with explanations and examples to help get you started.
  • Elastic has two libraries. This outline will focus on the elasticsearch-API library:
  • The official Github repository for the Elasticsearch API:


  • Ensure that Elasticsearch is installed and properly working on your system.
  • Elastic has an official Github repository for their Ruby-client library. You can consult their compatibility version Matrix for more information.


Check Ruby Version

  • To check if ruby was properly installed and its corresponding version, use the below command:
ruby -v
  • This is the result you should see:
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]

Update The Repository for the Ruby Gems:

  • Update the gem repository before installing to get the latest version of the gem repositories:
  • To update Ruby gems run the below command as a super user by appending sudo as shown below:
sudo gem install rubygems-update

sudo update_rubygems

sudo gem update --system
  • You’ll get an error message if you haven’t installed ruby before trying to install the Elasticsearch gem :
sudo gem install elasticsearch
  • You will see a prompt with the following warning:
Command 'gem' not found, but can be installed with:

sudo snap install ruby # version 2.6.2, or

sudo apt install ruby

See 'snap info ruby' for additional versions.

Install the Ruby API for Elasticsearch:

The library can be acquired through gem or git. The package in gem is named elasticsearch-ruby and the in git you use this url: Git — elastic/elasticsearch-ruby

  • You can install the package using Rubygems:
gem install elasticsearch-api
  • If you want to use git:
gem 'elasticsearch-api', git: 'git://'
  • or install it using:
git clone

cd elasticsearch-ruby/elasticsearch-api

bundle install

rake install
  • The Install by Elasticsearch::API is extracted from [Git — lasticsearch-ruby](


Install the ‘elasticsearch-ruby’ Gem

  • You can install elasticsearch-ruby from Rubygems:
sudo gem install elasticsearch
  • Install with git:
gem 'elasticsearch-api', git: 'git://'
  • You may also install it using git:
git clone

cd elasticsearch-ruby/elasticsearch

bundle install

rake install

Install Ruby on Windows

  • If Ruby is not installed, then download an installation package from Follow the link and run the installer.

The exe file rubyinstaller-2.5.3.x.exe will install with one click.

This package is very small, and RubyGems come with it as well. Please check the Release Notes for more detail.

Create A Ruby Script

Create and edit a new Ruby script using nano editor:

sudo nano edit elastic-example.rb
  • You can also just create an empty script to edit later using touch:
sudo touch elastic-example.rb

Require the Elasticsearch Library

  • At the beginning of the script you can use the optional Ruby shebang line and "-w" flag to turn on warnings:
#!/usr/local/bin/ruby -w
  • Require the Elasticsearch library:
require 'elasticsearch'

Create Client Instance

  • In the below code you create a new client instance to use the library’s built-in methods to index, query, delete, etc.. Elasticsearch documents.
client = log: true

client.index index: 'myindex', type: 'mytype', id: 1, body: { title: 'Demo' }

Index a Document Using Ruby

  • You can index a document using the below code.
client.index index: 'myindex', type: 'mytype', id: 1, body: { title: 'Demo' }

Create a Document Using Ruby Library:

  • Create a new document.

Create a Document with an ID

client.create index: 'car',

type: 'volvo',

id: '1',

body: {

model: 'modelname'

  • Let’s dissect the above code:
  • index — The name of the index, this is required.
  • id — Document ID; This is optional and will be auto-generated if missing.
  • body — The “body” of the document that contains all the fields and data.

Create a Document with an auto-generated ID:

  • _automatic_id_generation:
client.create index: 'myindex',

type: 'doc',

body: {

title: 'Test 1'

  • By default when creating a document an ID will be automatically generated when it’s not passed as an argument.

Delete a Document Using Ruby Library:

  • You can delete a single document using the below code.
client.delete index: 'theindex', type: 'thetype', id: '2'

Delete a Document with Specific Routing

client.delete index: 'theindex', type: 'thetype', id: '2', routing: 'route67'

For further information, you can consult Elastic’s Website.

Delete a Document with a Simple Query

client.delete_by_query index: 'theindex', q: 'name:volvo'

Delete a Document Using the Query DSL

client.delete_by_query index: 'theindex', body: { query: { term: { published: false } } }


Using the Ruby client with the Elasticsearch service simplifies the array of capabilities available to the programmer. This also adds a whole new level of functionality to the Elastic Stack that should be quite appealing to experienced coders. Additionally, the Ruby compatibility is further enhanced by the host of available tools that can be used with it. By following the preceding instructions, you can have these new features at your fingertips in no time. To find out what else becomes possible with this setup, just click on the other How-To guides we have for you.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.