Skip to content
An Elasticsearch querying ORM
Ruby HTML Other
Branch: master
Clone or download
Latest commit 3c0f895 Sep 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Ensure that partially updated objects are always fully indexed but ne… Sep 17, 2019
test Ensure that partially updated objects are always fully indexed but ne… Sep 17, 2019
.gitignore Use dotenv-rails to configure the DB Dec 11, 2015
Gemfile fix dependencies Mar 15, 2019
LICENSE Remove version (#108) Aug 21, 2019
Rakefile fix dependencies Mar 15, 2019
elastic_record.gemspec Release 5.6.1 Aug 8, 2019


Build Status Code Climate

ElasticRecord is an Elasticsearch 7.x ORM.


Include ElasticRecord into your model:

class Product < ActiveRecord::Base
  include ElasticRecord::Model


There are two ways to set up which server to connect to:

# config/initializers/elastic_search.rb
ElasticRecord.configure do |config|
  config.servers = ""
# config/elasticsearch.yml:
  timeout: 10
  retries: 2

Search API

ElasticRecord adds the method 'elastic_search' to your models. It works similar to active_record scoping:

search = Product.elastic_search


If a simple hash is passed into filter, a term or terms query is created:

search.filter(color: 'red')         # Creates a 'term' filter
search.filter(color: %w(red blue))  # Creates a 'terms' filter
search.filter(color: nil)           # Creates a 'must not exist' filter

If a hash containing hashes is passed into filter, it is used directly as a filter DSL expression:

search.filter(prefix: { name: "Sca" }) # Creates a prefix filter

An Arelastic object can also be passed in, working similarily to Arel:

# Name starts with 'Sca'

# Name does not start with 'Sca'

# Size is greater than 5

Helpful Arel builders can be found at


To create a query string, pass a string to search.query:

search.query("red AND fun*") # Creates {query_string: {"red AND fun*"}}

Complex queries are done using either a hash or an arelastic object:

search.query(match: {description: "amazing"})


search.order(:price)          # sort by price
search.order(:color, :price)  # sort by color, then price
search.order(price: :desc)    # sort by price in descending order

Offsets and Limits

To change the 'size' and 'from' values of a query, use offset and limit:

search.limit(40).offset(80)   # Creates a query with {size: 40, from: 80}


Aggregations are added with the aggregate method:

search.aggregate('popular_colors' => {'terms' => {'field' => 'color'}})

Results are retrieved at query time within aggregations:

search = search.aggregate('popular_colors' => {'terms' => {'field' => 'color'}})

Getting Results

A search object behaves similar to an active_record scope, implementing a few methods of its own and delegating the rest to Array, and your class.

search.count        # Return the number of search results
search.first        # Limit results to 1 and return the first result or nil
search.find(id)     # Add an ids filter to the existing query
search.as_elastic   # Return the json hash that will be sent to elastic search.

The search object behaves like an array when necessary:

search.each do |product|

Class methods can be executed within scopes:

class Product
  def self.increase_prices
    all.each do { |product| product.increment(:price, 10) }

# Increase the price of all red products by $10.
Product.filter(color: 'red').increase_prices


ElasticRecord supports representing query documents as a model. Queries are registered and unregistered as query models are created and destroyed.

First, include ElasticRecord::PercolatorModel into your model. Specify the target model to percolate and how the model should be indexed as an ElasticSearch query.

class ProductQuery
  include ElasticRecord::PercolatorModel

  self.percolates_model = Product

  def as_search_document
    Product.filter(status: status).as_elastic

Use the percolate method to find records with queries that match.

  product = 5.99)
  matching_product_queries = ProductQuery.percolate(product)

Index Configuration

To avoid elasticsearch dynamically mapping fields, you can directly configure elastic_index.mapping and elastic_index.settings:

class Product
  include ElasticRecord::Model

  elastic_index.mapping = {
    properties: {
      name: {type: "text"},
      status: {type: "keyword"}


When one model inherits from another, ElasticRecord makes some assumptions about how the child index should be configured. By default:

  • alias_name - Same as parent
  • mapping - Same as parent
  • settings - Same as parent

These can all be overridden. For instance, it might be desirable for the child documents to be in a separate index.

Load Documents from Source

To fetch documents without an additional request to a backing ActiveRecord database you can load the documents from _source.

Product.elastic_index.loading_from_source do
  Product.elastic_search.filter(name: "Pizza")

Call load_from_source! to configure an index without ActiveRecord. Finder methods will be delegated to the ElasticRecord module.

class Product
  include ActiveModel::Model
  include ElasticRecord::Record

Index Management

If you need to manage multiple indexes via the rake tasks, you will need to declare them explicitly:

ElasticRecord.configure do |config|
  config.model_names = %w(Product Order Location)

Create the index:

rake index:create CLASS=Product

Index Admin Functions

Core and Index APIs can be accessed with Product.elastic_index. Some examples include:

Product.elastic_index.create_and_deploy  # Create a new index
Product.elastic_index.reset              # Delete related indexes and deploy a new one
Product.elastic_index.refresh            # Call the refresh API
Product.elastic_index.get_mapping        # Get the index mapping defined by elastic search
You can’t perform that action at this time.