Elasticsearch

The elasticsearch library provides a Ruby client and API for Elasticsearch.

Usage

This gem is a wrapper for two separate libraries:

Install the elasticsearch package and use the API directly:

require 'elasticsearch'

client = Elasticsearch::Client.new(log: true)

client.cluster.health

client.transport.reload_connections!

client.search(q: 'test')

# etc.

Features overview:

(For integration with Ruby models and Rails applications, see the github.com/elasticsearch/elasticsearch-rails project.)

Compatibility

We follow Ruby’s own maintenance policy and officially support all currently maintained versions per Ruby Maintenance Branches.

Language clients are forward compatible; meaning that clients support communicating with greater minor versions of Elasticsearch. Elastic language clients are also backwards compatible with lesser supported minor Elasticsearch versions.

Installation

Install the package from Rubygems:

gem install elasticsearch

To use an unreleased version, either add it to your Gemfile for Bundler:

gem 'elasticsearch', git: 'git://github.com/elasticsearch/elasticsearch-ruby.git'

or install it from a source code checkout:

git clone https://github.com/elasticsearch/elasticsearch-ruby.git
cd elasticsearch-ruby/elasticsearch
bundle install
rake install

Configuration

Identifying running tasks with X-Opaque-Id

The X-Opaque-Id header allows to track certain calls, or associate certain tasks with the client that started them (more on the Elasticsearch docs). To use this feature, you need to set an id for opaque_id on the client on each request. Example:

client = Elasticsearch::Client.new
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')

The search request will include the following HTTP Header:

X-Opaque-Id: 123456

You can also set a prefix for X-Opaque-Id when initializing the client. This will be prepended to the id you set before each request if you’re using X-Opaque-Id. Example:

client = Elastic::Transport::Client.new(opaque_id_prefix: 'eu-west1_')
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')

The request will include the following HTTP Header:

X-Opaque-Id: eu-west1_123456

Api Key Authentication

You can use {API Key authentication}:

Elasticsearch::Client.new(
  host: host,
  transport_options: transport_options,
  api_key: credentials
)

Where credentials is either the base64 encoding of id and api_key joined by a colon or a hash with the id and api_key:

Elasticsearch::Client.new(
  host: host,
  transport_options: transport_options,
  api_key: {id: 'my_id', api_key: 'my_api_key'}
)

API and Transport

Please refer to the specific library documentation for details:

License

This software is licensed under the Apache 2 license.