Repository files navigation

This repository contains various Ruby and Rails integrations forElasticsearch:

• ActiveModel integration with adapters for ActiveRecord and Mongoid
• Repository pattern based persistence layer for Ruby objects
• Enumerable-based wrapper for search results
• ActiveRecord::Relation-based wrapper for returning search results as records
• Convenience model methods such assearch,mapping,import, etc
• Rake tasks for importing the data
• Support for Kaminari and WillPaginate pagination
• Integration with Rails' instrumentation framework
• Templates for generating example Rails application

Elasticsearch client and Ruby API is provided by theelasticsearch-ruby project.

The libraries are compatible with Ruby 2.4 and higher.

The version numbers follow the Elasticsearch major versions. Themaster branch is compatible withthe Elasticsearchmaster branch, therefore, with the next major version.

Use a release that matches the major version of Elasticsearch in your stack. Each client version isbackwards compatible with all minor versions of the same major version.

Check outElastic product end of life datesto learn which releases are still actively supported and tested.

Install each library fromRubygems:

gem install elasticsearch-modelgem install elasticsearch-rails

To use an unreleased version, add it to yourGemfile forBundler:

gem'elasticsearch-model',github:'elastic/elasticsearch-rails',branch:'5.x'gem'elasticsearch-rails',github:'elastic/elasticsearch-rails',branch:'5.x'

This project is split into three separate gems:

• elasticsearch-model,which contains search integration for Ruby/Rails models such as ActiveRecord::Base and Mongoid,

• elasticsearch-persistence,which provides a standalone persistence layer for Ruby/Rails objects and models

• elasticsearch-rails,which contains various features for Ruby on Rails applications

Example of a basic integration into an ActiveRecord-based model:

require'elasticsearch/model'classArticle <ActiveRecord::BaseincludeElasticsearch::ModelincludeElasticsearch::Model::Callbacksend# Index creation right at import time is not encouraged.# Typically, you would call create_index! asynchronously (e.g. in a cron job)# However, we are adding it here so that this usage example can run correctly.Article.__elasticsearch__.create_index!Article.import@articles=Article.search('foobar').records

You can generate a simple Ruby on Rails application with a single command(see theother available templates):

rails new searchapp --skip --skip-bundle --template https://raw.github.com/elasticsearch/elasticsearch-rails/master/elasticsearch-rails/lib/rails/templates/01-basic.rb

Example of using Elasticsearch as a repository for a Ruby domain object:

require'virtus'classArticleincludeVirtus.modelattribute:title,Stringendrequire'elasticsearch/persistence'repository=Elasticsearch::Persistence::Repository.newrepository.saveArticle.new(title:'Test')# POST http://localhost:9200/repository/article# => {"_index"=>"repository", "_type"=>"article", "_id"=>"Ak75E0U9Q96T5Y999_39NA", ...}

Please refer to each library documentation for detailed information and examples.

• [README]
• [Documentation]
• [Test Suite]

• [README]
• [Documentation]
• [Test Suite]

• [README]
• [Documentation]
• [Test Suite]

To work on the code, clone the repository and install all dependencies first:

git clone https://github.com/elastic/elasticsearch-rails.gitcd elasticsearch-rails/bundle installrake bundle:install

You can run unit and integration tests for each sub-project by running the respective Rake tasks in their folders.

You can also unit, integration, or both tests for all sub-projects from the top-level directory:

rake test:all

The test suite expects an Elasticsearch cluster running on port 9250, andwill delete all the data. You can launch an isolated, in-memory Elasticsearch cluster with the following Rake task:

TEST_CLUSTER_COMMAND=/tmp/builds/elasticsearch-2.0.0-SNAPSHOT/bin/elasticsearch TEST_CLUSTER_NODES=1 bundle exec rake test:cluster:start

See more information in the documentation for theelasticsearch-extensions gem.

This software is licensed under the Apache 2 license, quoted below.

Licensed to Elasticsearch B.V. under one or more contributorlicense agreements. See the NOTICE file distributed withthis work for additional information regarding copyrightownership. Elasticsearch B.V. licenses this file to you underthe Apache License, Version 2.0 (the "License"); you maynot use this file except in compliance with the License.You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing,software distributed under the License is distributed on an"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANYKIND, either express or implied.  See the License for thespecific language governing permissions and limitationsunder the License.