Elastico is a simple layer that enables you to use the full elasticsearch API. The elasticsearch team created this great API which enables you to do almost anything todays search engines allow you to do.

Simple. Elastico is built to keep your configuration and usage as simple and straightforward as possible.

Full. Elastico is built to be a transparent, non-blocking, non-opinionated layer between your code and the elasticsearch API. Meaning Elastico won't force anything regarding the way you index your active records models, nor how to search it.

There is one reason for building it Simple and Full: The elasticsearch community is large. Its supportive, and very helpful. Though most of it does not use ruby. Its most likely that you want to spend your time on figuring out how to use elasticsearch rather than how to use the gem that works with elasticsearch. If you use Elastico, its most likely that your time will go to the former, and will be able to take advantage of the elasticsearch community.

You should give Elastico a try if you want to use the elasticsearch full api.

In general, in order to be able to use elasticsearch search capabilities you should:

1. Define what and how you want to index (settings and mappings)
2. Define what and how you want to search (query the index)

Install elasticsearch:

cd ~
wget https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-0.90.5.tar.gz .
tar -zxvf elasticsearch-0.90.5.tar.gz /bin/
rm elasticsearch-0.90.5.tar.gz

Now run it:

/bin/elasticsearch-0.90.5/bin/elasticsearch -f

Add this line to your application's Gemfile:

gem 'elastico'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install elastico

In your model:

class Apple < ActiveRecord::Base

  attr_accessible :color, :name
  
  def self.prepare_elastico_settings_and_mappings_json
    json = { "settings" => 
              {
                "number_of_shards" => 3
              },
              "mappings" =>
              {
                  "apple" => 
                  {
                    "properties" => 
                    {
                      "name" => {"type" => "string"},
                      "color" => {"type" => "string"}
                    }
                  }
              }
            }.to_json
  end

  # include elastico only after you declared your settings and mappings json in the method prepare_elastico_settings_and_mappings_json
  include Elastico
  Apple.elastico_url = "http://vokdxbxi:dhkxpsqfg8fy2bnr@banyan-6062486.us-east-1.bonsai.io:9200/" if Rails.env == "production" # This is optional
  send_settings_mappings_to_elasticsearch_server
end

In your controller:

class ApplesController < ApplicationController  
    def index
      if params[:query]
        Apple.search_query = prepare_search_json_for params[:query]
        @apples = Apple.elastico_search
      else
        @apples = Apple.all
      end
    end

    private
      def prepare_search_json_for query
        json = { "query" => 
                  {
                    "term" => { "color" => query.to_s }
                  }
                }.to_json
      end
    # now do something with your apples 
end

Import your active record instances simply by:

Apple.elastico_import_all

1. Play with the example app online at http://elasticoexample.herokuapp.com/
2. Fork/Clone the example app that shows how to use Elastico here.

In order to get a model work with elasticsearch + Elastico you have to:

Mandatory

1. In your controller, Create a class method 'prepare_search_json_for' to be your standard search query for that model (defaults to nil). This is the same search query you would send if you were using the curl command.

2. In your model, Create a class method 'prepare_elastico_settings_and_mappings_json' to be your settings and mapping json (defaults to nil). This is the same search query you would send if you were using the curl command.

Optional

1. Set Apple.elastico_url= to be the ip of your elasticsearch server (defaults to "localhost:9200").

2. Set up Apple.elastico_index_name (optional - defaults to your class name followed by Rail.env; here it will be apples_development).

3. Set up Apple.elastico_type_name (optional - defaults to your class name; here it will be Apple).

4. Run Apple.elastico_import_all to import all your data.

5. Controll what fields are indexed by declaring a method called 'elastico_to_indexed_json'.

1. After every save Elastico will automatically save your instance in elasticsearch.

2. Import current database by Apple.elastico_import_all.

3. Search it: call Apple.elastico_search to get your results, or override it to better suit your needs.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Please send your feedback to gneyal+elastico@gmail.com