The elasticsearch Rubygem provides a low-level client for communicating with an Elasticsearch cluster, fully compatible with other official clients.
Full documentation is hosted at Github and RubyDoc — this documentation provides only an overview of features.
The Ruby API is compatible with both Elasticsearch 0.90.x and 1.0.x versions, you have to install a matching gem version, though:
Elasticsearch version | Ruby gem version |
---|---|
0.90.x | 0.4.x |
1.x | 1.x |
Install the Ruby gem for Elasticsearch 1.x:
gem install elasticsearch
…or add it do your Gemfile:
gem 'elasticsearch'
Install the Ruby gem for Elasticsearch 0.90.x:
gem install elasticsearch -v 0.4.10
…or add it do your Gemfile:
gem 'elasticsearch', '~> 0.4'
require 'elasticsearch'
client = Elasticsearch::Client.new log: true
client.cluster.health
client.index index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' }
client.indices.refresh index: 'my-index'
client.search index: 'my-index', body: { query: { match: { title: 'test' } } }
The elasticsearch gem combines two separate Ruybygems:
Please see their respective documentation for configuration options and technical details.
Notably, the documentation and comprehensive examples for all the API methods is contained in the source, and available online at Rubydoc.
Keep in mind, that for optimal performance, you should use a HTTP library which supports persistent (“keep-alive”) HTTP connections.
The `elasticsearch-extensions <https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-extensions>`__ Rubygem provides a number of extensions to the core client, such as an API to programatically launch Elasticsearch clusters (eg. for testing purposes), and more.
Please see its documentation for more information.
The elasticsearch-model Rubygem provides integration with Ruby domain objects (“models”), commonly found e.g. in Ruby on Rails applications.
It uses the elasticsearch Rubygem as the client communicating with the Elasticsearch cluster.
Add the library to your Gemfile:
gem 'elasticsearch-rails'
Include the extension module in your model class:
class Article < ActiveRecord::Base
include Elasticsearch::Model
end
Import some data and perform a search:
Article.import
response = Article.search 'fox dog'
response.took
# => 3
It is possible to either return results as model instances, or decorated documents from Elasticsearch, with the records and results methods, respectively:
response.records.first
# Article Load (0.4ms) SELECT "articles".* FROM "articles" WHERE ...
=> #<Article id: 3, title: "Foo " ...>
response.results.first._score
# => 0.02250402
response.results.first._source.title
# => "Quick brown fox"
Please see the full documentation for more information.
The elasticsearch-rails Rubygem provides features suitable for Ruby on Rails applications.
You can generate a fully working example Ruby on Rails application with templates provides.
Please refer to the documentation for more information.
The elasticsearch-persistence Rubygem provides persistence layer for Ruby domain objects.
It supports two design patterns for integrating with your objects: repository and active record.
The Elasticsearch::Persistence::Repository module provides an implementation of the repository pattern and allows to save, delete, find and search objects stored in Elasticsearch, as well as configure mappings and settings for the index.
Let’s have a simple plain old Ruby object (PORO):
class Note
attr_reader :attributes
def initialize(attributes={})
@attributes = attributes
end
def to_hash
@attributes
end
end
Let’s create a default, “dumb” repository, as a first step:
require 'elasticsearch/persistence'
repository = Elasticsearch::Persistence::Repository.new
We can save a Note instance into the repository, find it, search it, delete it:
note = Note.new id: 1, text: 'Test'
repository.save(note)
# PUT http://localhost:9200/repository/note/1
# > {"id":1,"text":"Test"}
# < {"_index":"repository","_type":"note","_id":"1","_version":1,"created":true}
n = repository.find(1)
# GET http://localhost:9200/repository/_all/1
# < {"_index":"repository","_type":"note","_id":"1","_version":2,"found":true, "_source" : {"id":1,"text":"Test"}}
=> <Note:0x007fcbfc0c4980 @attributes={"id"=>1, "text"=>"Test"}>
repository.search(query: { match: { text: 'test' } }).first
# GET http://localhost:9200/repository/_search
# > {"query":{"match":{"text":"test"}}}
# < {"took":2, ... "hits":{"total":1, ... "hits":[{ ... "_source" : {"id":1,"text":"Test"}}]}}
=> <Note:0x007fcbfc1c7b70 @attributes={"id"=>1, "text"=>"Test"}>
repository.delete(note)
# DELETE http://localhost:9200/repository/note/1
# < {"found":true,"_index":"repository","_type":"note","_id":"1","_version":3}
=> {"found"=>true, "_index"=>"repository", "_type"=>"note", "_id"=>"1", "_version"=>2}
The repository module provides a number of features and facilities to configure and customize the behaviour, as well as support for extending your own, custom repository class.
Please refer to the documentation for more information.
Also, check out the example application which demonstrates the usage patterns of the repository approach to persistence.
The ‘Elasticsearch::Persistence::Model` module provides an implementation of the active record pattern, with a familiar interface for using Elasticsearch as a persistence layer in Ruby on Rails applications. The model is fully compatible with Rails’ conventions and helpers, such as url_for.
All the methods are documented with comprehensive examples in the source code, available also online.
To use the library in a Rails application, add it to your Gemfile with a require statement:
gem "elasticsearch-persistence", require: 'elasticsearch/persistence/model'
Include the module in a plain Ruby class, and set up the properties, mappings, etc:
class Article
include Elasticsearch::Persistence::Model
# Define a plain `title` attribute
#
attribute :title, String
# Define an `author` attribute, with multiple analyzers for this field
#
attribute :author, String, mapping: { fields: {
author: { type: 'string'},
raw: { type: 'string', analyzer: 'keyword' }
} }
# Define a `views` attribute, with default value
#
attribute :views, Integer, default: 0, mapping: { type: 'integer' }
# Validate the presence of the `title` attribute
#
validates :title, presence: true
# Execute code after saving the model.
#
after_save { puts "Successfuly saved: #{self}" }
end
The model attribute definition support is implemented with the *Virtus* Rubygem, and the naming, validation, etc. features with the *ActiveModel* Rubygem.
Attribute validations work like for any other ActiveModel-compatible implementation:
article = Article.new # => #<Article { ... }>
article.valid?
# => false
article.errors.to_a
# => ["Title can't be blank"]
We can create a new article in the database and find it:
Article.create id: 1, title: 'Test', author: 'John'
# PUT http://localhost:9200/articles/article/1 [status:201, request:0.015s, query:n/a]
article = Article.find(1)
# => #<Article { ... }>
article._index
# => "articles"
article.id
# => "1"
article.title
# => "Test"
To update the model, either update the attribute and save the model or use the update_attributes method:
article.title = 'Updated'
article.save
# => {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>2, "created"=>false}
article.update_attributes title: 'Test', author: 'Mary'
# => {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>3}
The implementation supports the familiar interface for updating model timestamps and numeric attributes:
article.touch
# => => { ... "_version"=>4}
article.views
# => 0
article.increment :views
article.views
# => 1
Any callbacks defined in the model will be triggered during the persistence operations:
article.save
# Successfuly saved: #<Article {...}>
Please see the extensive documentation in the library README for detailed information.
Also, check out the example application which demonstrates the usage patterns of the active record approach to persistence.
This software is Copyright (c) 2013 by Elasticsearch BV.
This is free software, licensed under The Apache License Version 2.0.