Usage Overview
Elastics can integrate your code with elasticsearch in 6 different ways that can be handy in different contexts. From a fully automatic integration, to a very low-level manual interaction:
1. ActiveRecord and Mongoid Integration
When the data you need to index is in your DB, just add the following lines to your ActiveRecord
and Mongoid
model to sync them:
class MyModel < ActiveRecord::Base
include Elastics::ModelIndexer
elastics.sync self
end
You can add a few other declarations to your models in order to setup parent and child relationship (eventually also polymorphic), and mapping any DB structure to any index structure you might want to design.
(see ActiveRecord And Mongoid Integration)
2. ActiveModel Integration
Manage the elasticsearch index as it were a DB, through ActiveModel
models. Get validations and callbacks, typecasting, attribute defaults, persistent storage, with optimistic lock update, finders, chainable scopes etc.
This is very useful when the data don’t come from a DB or when you want to use the elasticsearch index as a data storage, or simply when you want a familiar way to populate and search your index. For example:
class Product
include Elastics::ActiveModel
attribute :name
attribute :color, :analyzed => false
attribute :price, :properties => {'type' => 'float'}, :default => 0
attribute_timestamps
validate :name, :presence => true
scope :red, term(:color => 'red')
end
# indexes the data in elasticsearch
Product.create :name => 'my_name',
:color => 'blue',
:price => 9.99
red_products = Product.red.all
product = Product.find('a09rf')
total = Product.count
(see ActiveModel Integration)
3. Chainable Scopes and Finders
Almost no elasticsearch knowledge required: a ruby-rails way that covers most searching needs!
Scopes are a great way to define the criteria to search the index in pure ruby. You can mix and match many scopes to create a new search criteria, and finally get your result by calling the usual find
, count
, delete
, first
, last
, all
. You can also use scan_all
when you want to process a lot of documents in batches.
class MyClass
include Elastics::Scopes
scope :red, terms(:color => 'red')
scope :size do |size|
terms(:size => size)
end
scope :cheaper_than do |p|
range :price => {:to => p}
end
end
my_scope = MyClass.red.size('big')
all_big_red = my_scope.all
big_red_cheap = my_scope.cheaper_than(10).all
in_range_scope = MyClass.range :price =>{:from => 10, :to => 99.99}
first_in_range = in_range_scope.first
# uses the elasticsearch 'scan' search_type
MyClass.red.scan_all do |batch|
batch.each {|d| do_something_with(d)}
end
You can use the elastics-scopes
with every class that includes any Elastics module (see elastics-scopes)
4. Template Based Usage
Easily design complex search queries in simple YAML
that automatically define methods in your classes.
Elastics implements a very simple but powerful templating system that allows you to define very elaborate queries and automatically generate the methods to use (and reuse) them. This method is typically used for search queries, that may grow quite complex, but internally Elastics uses it everywhere.
Define the Elastics source my_source.yml
: it’s just a YAML
document containing a few elasticsearch queries and placeholder tags:
my_template:
query:
term:
my_attr: <<the_term>>
facets:
my_facet:
...
Create a class and load the source in the class:
class MySearch
include Elastics::Templates
elastics.load_search_source 'my_source.yml'
end
Use the automatically generated class methods by just passing a hash of variables/values to interpolate:
result = MySearch.my_template :the_string => params[:the_string]
# or simply
result = MySearch.my_template params
The results contains the untouched structure returned by elasticsearch, just extended (and easily custom-extendable) with the methods you may need to use:
result.collection.each do |document|
puts document.id, document.title, ...
end
my_facet = result.facets['my_facet']
(see Templating)
5. elasticsearch API Methods Usage
Elastics exposes all the elasticsearch API methods as ready to use class methods. A few examples:
Elastics.exist? :index => 'my_index'
Elastics.count :index => 'my_index',
:type => 'my_type'
Elastics.get :id => id,
:type => 'my_type',
:index => 'my_index'
Elastics.multi_get :ids => ids,
:type => 'my_type',
:index => 'my_index'
Elastics.delete_by_query :index => 'my_index',
:params => {:q =>'my_field:value'}
Elastics.more_like_this :id => id,
:index => 'my_index',
:type => 'my_type'
Elastics.stats :index => %w[my_index my_other_index],
:type => %w[my_type my_other_type]
:endpoint => 'indexing'
Notice: you don’t actually need to pass any explicit
:index
or:type
if you set them as a defaults (see Variables)
You will probably never need to use the API Methods directly, since Elastics does the heavy lifting for you, but they cover all the elasticsearch API, so they will be available when you will need to do anything special (see API Methods).
6. Curl-like Usage
This usage is very explicit and mostly useful for experimentation and debugging: you can use the methods HEAD
, GET
, PUT
, POST
, DELETE
exactly as you would do with curl (also enforced by the unconventional upcase naming):
# you can use a json string
Elastics.GET '/my_index/my_type/_search', '{"query":{"match_all":{}}}'
# a ruby hash
Elastics.GET '/my_index/my_type/_search', {:query => {:match_all => {}}}
# or a yaml string
Elastics.GET '/my_index/my_type/_search', <<-yaml
query:
match_all: {}
yaml
You don’t need to pass the base uri: just the path since the base_uri
is a configuration setting that defaults to the elasticsearch http:://localhost:9200
(see Configuration).
In all methods above you can also use tags in path and data, and get them interpolated with the default or explicit variables, as you do with a regular Elastics template (see Curl-like Methods))
Elastics.GET '/<<index>>/<<type>>/_search', <<-yaml, :index => 'my_index', :my_term => 'any'
query:
term:
my_field: <<my_term>>
yaml