0.02
No release in over 3 years
Find your records with Elasticsearch
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

ElasticRecord

Build Status Code Climate

ElasticRecord is an Elasticsearch 7.x ORM.

Setup

Include ElasticRecord into your model:

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

Connection

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

# config/initializers/elastic_search.rb
ElasticRecord.configure do |config|
  config.servers = "es1.example.com:9200"
end
# config/elasticsearch.yml:
development:
  servers: es1.example.com:9200
  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

Filtering

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'
search.filter(Product.arelastic[:name].prefix("Sca"))

# Name does not start with 'Sca'
search.filter(Product.arelastic[:name].prefix("Sca").negate)

# Size is greater than 5
search.filter(Product.arelastic[:size].gt(5))

Helpful Arel builders can be found at https://github.com/matthuhiggins/arelastic/blob/master/lib/arelastic/builders/queries.rb.

Querying

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"})

Ordering

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

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'}})
search.aggregations['popular_colors'].buckets

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|
  ...
end

Class methods can be executed within scopes:

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

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

Percolators

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
  end
end

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

  product = Product.new(price: 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"}
    }
  }
end

Inheritance

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.

Join fields

ElasticSearch supports declaring a join field that specifies a parent-child relationship between documents of different types in the same index (docs). ElasticRecord provides a short-(but not-so-short)-cut for declaring the mapping:

class State
  include ElasticRecord::Model
end

class City
  include ElasticRecord::Model
end

class PostalCode
  include ElasticRecord::Model
end

class Country
  include ElasticRecord::Model

  has_es_children(
    join_field: 'pick_a_name_for_the_join_field',
    children:   [
      State,
      { zip: PostalCode },
      ElasticRecord::Model::Joining::JoinChild.new(klass: City, parent_id_accessor: :country_code)
    ]
  )
end

has_es_children accepts an optional name argument, with a sane default. In the above example, it would default to country. The name can later be used to construct has_parent queries. ElasticRecord will define a getter method with the same name as the value provided to join_field on both the parent and all children (and grandchildren).

The children argument can be:

  • a Class that includes ElasticRecord::Model
  • a Hash (with names as keys and classes as values)
  • an instance of ::ElasticRecord::Model::Joining::JoinChild.new (when you need to override any of the options below besides name)
  • or an Array containing any combination thereof.

::ElasticRecord::Model::Joining::JoinChild.new accepts additional, optional arguments:

  • name: defaults to the snake case version of the value provided to klass (e.g. state in the example above). Can be used to construct has_child queries.
  • children: Another instance of ::ElasticRecord::Model::Joining::JoinChild or an Array of instances. Defaults to an empty Array. Theoretically, an arbitrary number of layers of parent-child joins can be achieved this way.
  • parent_id_accessor: Determines how the ID of the parent is retrieved. Can be a proc, which will be executed in the context of the child object, or a symbol corresponding to the name of a method defined on the child object. In the above example, it would default to country_id.
  • parent_accessor: Determines how the parent is retrieved. Can be a proc, which will be executed in the context of the child object, or a symbol corresponding to the name of a method defined on the child object. In the above example, it would default to country. The is used to retrieve routing for multi-layered parent-child joins.

Note: Creating, deleting and updating mapping on the index must be handled via the Top-Level parent. In the above example, running rake index:create CLASS=State would have no effect.

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")
end

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
  elastic_index.load_from_source!
end

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)
end

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
Product.elastic_index.update_mapping     # Update the elastic search mapping of the current index

Development

# Setup the database
$ cp test/dummy/.env.example test/dummy/.env
$ bundle exec rake app:db:prepare app:index:reset
$ bundle exec rake app:db:prepare RAILS_ENV=test

# Run tests
$ bundle exec rake