This repository contains Ruby integrations for Elasticsearch:
- a client for connecting to an Elasticsearch cluster,
- a Ruby API for the Elasticsearch's REST API,
- a Ruby API for the X-Pack APIs,
- various extensions and utilities.
For integration with Ruby models and Rails applications, see the elasticsearch-rails project.
The Elasticsearch client is compatible with Ruby 1.9 and higher. Other libraries in this repository might require a more recent Ruby version.
The client's API is compatible with Elasticsearch's API versions from 0.90 till current, just use a release matching major version of Elasticsearch.
elasticsearch 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
elasticsearch library is a wrapper for two separate libraries:
elasticsearch-transport, which provides a low-level Ruby client for connecting to an Elasticsearch cluster
elasticsearch-api, which provides a Ruby API for the Elasticsearch RESTful API
require 'elasticsearch' client = Elasticsearch::Client.new log: true # if you specify Elasticsearch host # client = Elasticsearch::Client.new url: 'http://localhost:9200', log: true client.transport.reload_connections! client.cluster.health client.search q: 'test' # etc.
Keep in mind, that for optimal performance, you should use a HTTP library which supports persistent ("keep-alive") connections, e.g. Patron or Typhoeus. These libraries are not dependencies of the elasticsearch gems, so be sure to define a dependency in your own application.
This repository contains these additional Ruby libraries:
elasticsearch-extensions, which provides a set of extensions to the base library,
elasticsearch-dsl, which provides a Ruby API for the Elasticsearch Query DSL,
elasticsearch-xpack, which provides Ruby API for the X-Pack APIs.
Please see their respective READMEs for information and documentation.
To work on the code, clone and bootstrap the project first:
git clone https://github.com/elasticsearch/elasticsearch-ruby.git cd elasticsearch-ruby/ rake setup rake bundle
This will clone the Elasticsearch repository into the project, and run
bundle install in all subprojects.
To run tests, you need to start a testing cluster on port 9250, or provide a different one in the
TEST_CLUSTER_PORT environment variable.
There's a Rake task to start the testing cluster:
You can configure the port, path to the startup script, number of nodes, and other settings with environment variables:
TEST_CLUSTER_COMMAND=./tmp/builds/elasticsearch-2.0.0-SNAPSHOT/bin/elasticsearch \ TEST_CLUSTER_PORT=9250 \ TEST_CLUSTER_NODES=2 \ TEST_CLUSTER_NAME=my_cluster \ TEST_CLUSTER_PARAMS='-Xms500m -Xmx500m -D es.index.store.type=niofs' \ TEST_CLUSTER_TIMEOUT=120 \ rake test:cluster:start
To run tests against unreleased Elasticsearch versions, you can use the
rake elasticsearch:build Rake task to build Elasticsearch from the cloned source (use
rake elasticsearch:update to update the repository):
Note: If you have gems from the
elasticsearch family installed system-wide, and want to use development ones, prepend the command with
You can pass a branch name (tag, commit, ...) as the Rake task variable:
To run all the tests in all the subprojects, use the Rake task:
time rake test:all
This software is licensed under the Apache 2 license.