elasticsearch-persistence 0.1.3 → 0.1.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NGIxM2RkNWIyNmRkMGE4YzE1NzY0ZmNkNmI3ZDI4ODI5ZDY5NTM1Nw==
+    OTQ2NWJlZWJlNDE0ODRhODAzZDM2ZDFhYTFiNDkzNTdlMTZkZjQzYQ==
   data.tar.gz: !binary |-
-    YmFiZGFkYzZhZWU4NTY0NTNlNzVkZjNkZWM0MzJkNWFhMmQ3YmU4NQ==
+    MmUzOGJiN2I0MmY1ZDBmOTg3NjRiOWM0NDk2NjkzN2Q0N2I2Yjk3Mg==
 SHA512:
   metadata.gz: !binary |-
-    MzFhNzNjMDdjM2NlZTNmN2IzZDA4ZjM0ZjVjNGRkODlhYzMwNzNlZTk0MTMw
-    NGZkNWYyOThlMzA4NWZmZTRkNjc5MzI1N2ZjZTMwODJlYzAxZTVlODQ0ZWIy
-    MTQ0YWQ4M2QyMTAwNzc0OTI0ZDUwZGI2NmM3YjUxZGJmMmNhYjU=
+    YTViMmMzZTNlMGVhMTE4ZWIzYzJmYjU1ZGQwMWJlMzVmMWQ4ZmM2Y2YyNTcz
+    NWQ2NDE2NDlkYzI2YTFkMjMxOWVlMWZlZWE5MWQ4MmNlNjQxMzc1MWVkNzZk
+    MTcxYjM2OTk1MDNlNDQ5NjNiNzk1NTkxNGVlNjVjNTMyZTI4Mzk=
   data.tar.gz: !binary |-
-    ODdjOTY2NDE0ODkwMzA5YThlZjU1MmZlNTVhZDc2ODZmODA0NmY4YTBhNzY2
-    ODI0MDc1M2MxOTk5ZWVjMWU3ZGRmYWJhZTk3ZjYyYmM1NDcyM2RmZDQ4YzEz
-    NmNiMzQ1ODliYzNhYzEyNzE0OWVhNmQ4NjcxYzY2ZWM3MmZmMjU=
+    ZjFmNDc0MWYyOTZjNTcwZmNjMzBmYzY5ZTlmZmFmODM3MzEwNTg0OTAwYmY5
+    MzZkZTFmZjNmNzliZTFiNTY4YTZhMjVhYWY1MmNmZWRiNTJmZWYwNDNiYWFj
+    ZmRhMmZhNzg1ZTAyNDI3ODJhODRlMGI3MjI5NDczZTNhYmU4NzQ=

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.4
+
+* Added the Elasticsearch::Persistence::Model feature
+
 ## 0.1.3
 
 * Released the "elasticsearch-persistence" Rubygem

data/README.md

@@ -416,17 +416,248 @@ results.response._shards.failed
 
 #### Example Application
 
-An example Sinatra application is available in
-[`examples/sinatra/application.rb`](examples/sinatra/application.rb),
-and demonstrates a rich set of features of the repository.
+An example Sinatra application is available in [`examples/notes/application.rb`](examples/notes/application.rb),
+and demonstrates a rich set of features:
 
+* How to create and configure a custom repository class
+* How to work with a plain Ruby class as the domain object
+* How to integrate the repository with a Sinatra application
+* How to write complex search definitions, including pagination, highlighting and aggregations
+* How to use search results in the application view
 
 ### The ActiveRecord Pattern
 
-[_Work in progress_](https://github.com/elasticsearch/elasticsearch-rails/pull/91).
-The ActiveRecord [pattern](http://www.martinfowler.com/eaaCatalog/activeRecord.html) will work
-in a very similar way as `Tire::Model::Persistence`, allowing a drop-in replacement of
-an Elasticsearch-backed model in Ruby on Rails applications.
+The `Elasticsearch::Persistence::Model` module provides an implementation of the
+active record [pattern](http://www.martinfowler.com/eaaCatalog/activeRecord.html),
+with a familiar interface for using Elasticsearch as a persistence layer in
+Ruby on Rails applications.
+
+All the methods are documented with comprehensive examples in the source code,
+available also online at <http://rubydoc.info/gems/elasticsearch-persistence/Elasticsearch/Persistence/Model>.
+
+#### Installation/Usage
+
+To use the library in a Rails application, add it to your `Gemfile` with a `require` statement:
+
+```ruby
+gem "elasticsearch-persistence", require: 'elasticsearch/persistence/model'
+```
+
+To use the library without Bundler, install it, and require the file:
+
+```bash
+gem install elasticsearch-persistence
+```
+
+```ruby
+# In your code
+require 'elasticsearch/persistence/model'
+```
+
+#### Model Definition
+
+The integration is implemented by including the module in a Ruby class.
+The model attribute definition support is implemented with the
+[_Virtus_](https://github.com/solnic/virtus) Rubygem, and the
+naming, validation, etc. features with the
+[_ActiveModel_](https://github.com/rails/rails/tree/master/activemodel) Rubygem.
+
+```ruby
+class Article
+  include Elasticsearch::Persistence::Model
+
+  # Define a plain `title` attribute
+  #
+  attribute :title,  String
+
+  # Define an `author` attribute, with multiple analyzers for this field
+  #
+  attribute :author, String, mapping: { fields: {
+                               author: { type: 'string'},
+                               raw:    { type: 'string', analyzer: 'keyword' }
+                             } }
+
+
+  # Define a `views` attribute, with default value
+  #
+  attribute :views,  Integer, default: 0, mapping: { type: 'integer' }
+
+  # Validate the presence of the `title` attribute
+  #
+  validates :title, presence: true
+
+  # Execute code after saving the model.
+  #
+  after_save { puts "Successfuly saved: #{self}" }
+end
+```
+
+Attribute validations works like for any other _ActiveModel_-compatible implementation:
+
+```ruby
+article = Article.new                                                                                             # => #<Article { ... }>
+
+article.valid?
+# => false
+
+article.errors.to_a
+# => ["Title can't be blank"]
+```
+
+#### Persistence
+
+We can create a new article in the database...
+
+```ruby
+Article.create id: 1, title: 'Test', author: 'John'
+# PUT http://localhost:9200/articles/article/1 [status:201, request:0.015s, query:n/a]
+```
+
+... and find it:
+
+```ruby
+article = Article.find(1)
+# => #<Article { ... }>
+
+article._index
+# => "articles"
+
+article.id
+# => "1"
+
+article.title
+# => "Test"
+```
+
+To update the model, either update the attribute and save the model:
+
+```ruby
+article.title = 'Updated'
+
+article.save
+=> {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>2, "created"=>false}
+```
+
+... or use the `update_attributes` method:
+
+```ruby
+article.update_attributes title: 'Test', author: 'Mary'
+# => {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>3}
+```
+
+The implementation supports the familiar interface for updating model timestamps:
+
+```ruby
+article.touch
+# => => { ... "_version"=>4}
+```
+
+... and numeric attributes:
+
+```ruby
+article.views
+# => 0
+
+article.increment :views
+article.views
+# => 1
+```
+
+Any callbacks defined in the model will be triggered during the persistence operations:
+
+```ruby
+article.save
+# Successfuly saved: #<Article {...}>
+```
+
+The model also supports familiar `find_in_batches` and `find_each` methods to efficiently
+retrieve big collections of model instance, using the Elasticsearch's _Scan API_:
+
+```ruby
+Article.find_each(_source_include: 'title') { |a| puts "===> #{a.title.upcase}" }
+# GET http://localhost:9200/articles/article/_search?scroll=5m&search_type=scan&size=20
+# GET http://localhost:9200/_search/scroll?scroll=5m&scroll_id=c2Nhb...
+# ===> TEST
+# GET http://localhost:9200/_search/scroll?scroll=5m&scroll_id=c2Nhb...
+# => "c2Nhb..."
+```
+
+#### Search
+
+The model class provides a `search` method to retrieve model instances with a regular
+search definition, including highlighting, aggregations, etc:
+
+```ruby
+results = Article.search query: { match: { title: 'test' } },
+                         aggregations: {  authors: { terms: { field: 'author.raw' } } },
+                         highlight: { fields: { title: {} } }
+
+puts results.first.title
+# Test
+
+puts results.first.hit.highlight['title']
+# <em>Test</em>
+
+puts results.response.aggregations.authors.buckets.each { |b| puts "#{b['key']} : #{b['doc_count']}" }
+# John : 1
+```
+
+#### Accessing the Repository Gateway
+
+The Elasticsearch integration is implemented by embedding the repository object in the model.
+You can access it through the `gateway` method:
+
+```ruby
+Artist.gateway.client.info
+# GET http://localhost:9200/ [status:200, request:0.011s, query:n/a]
+# => {"status"=>200, "name"=>"Lightspeed", ...}
+```
+
+#### Rails Compatibility
+
+The model instances are fully compatible with Rails' conventions and helpers:
+
+```ruby
+url_for article
+# => "http://localhost:3000/articles/1"
+
+div_for article
+# => '<div class="article" id="article_1"></div>'
+```
+
+... as well as form values for dates and times:
+
+```ruby
+article = Article.new "title" => "Date", "published(1i)"=>"2014", "published(2i)"=>"1", "published(3i)"=>"1"
+
+article.published.iso8601
+# => "2014-01-01"
+```
+
+The library provides a Rails ORM generator:
+
+```bash
+rails generate scaffold Person name:String email:String birthday:Date --orm=elasticsearch
+```
+
+#### Example application
+
+A fully working Ruby on Rails application can be generated with the following command:
+
+```bash
+rails new music --force --skip --skip-bundle --skip-active-record --template https://raw.githubusercontent.com/elasticsearch/elasticsearch-rails/persistence-model/elasticsearch-persistence/examples/music/template.rb
+```
+
+The application demonstrates:
+
+* How to set up model attributes with custom mappings
+* How to configure model relationships with Elasticsearch's parent/child
+* How to configure models to use a common index, and create the index with proper mappings
+* How to use Elasticsearch's completion suggester to drive auto-complete functionality
+* How to use Elasticsearch-persisted model in Rails' views and forms
+* How to write controller tests
+
+The source files for the application are available in the [`examples/music`](examples/music) folder.
 
 ## License
 

data/elasticsearch-persistence.gemspec

@@ -26,13 +26,16 @@ Gem::Specification.new do |s|
   s.add_dependency "elasticsearch",       '> 0.4'
   s.add_dependency "elasticsearch-model", '>= 0.1'
   s.add_dependency "activesupport",       '> 3'
+  s.add_dependency "activemodel",         '> 3'
   s.add_dependency "hashie"
+  s.add_dependency "virtus"
 
   s.add_development_dependency "bundler", "~> 1.5"
   s.add_development_dependency "rake"
 
   s.add_development_dependency "oj"
-  s.add_development_dependency "virtus"
+
+  s.add_development_dependency "rails"
 
   s.add_development_dependency "elasticsearch-extensions"
 

data/examples/music/album.rb

@@ -0,0 +1,34 @@
+class Meta
+  include Virtus.model
+
+  attribute :rating
+  attribute :have
+  attribute :want
+  attribute :formats
+end
+
+class Album
+  include Elasticsearch::Persistence::Model
+
+  index_name [Rails.application.engine_name, Rails.env].join('-')
+
+  mapping _parent: { type: 'artist' } do
+    indexes :suggest_title, type: 'completion', payloads: true
+    indexes :suggest_track, type: 'completion', payloads: true
+  end
+
+  attribute :artist
+  attribute :artist_id, String, mapping: { index: 'not_analyzed' }
+  attribute :label, Hash, mapping: { type: 'object' }
+
+  attribute :title
+  attribute :suggest_title, String, default: {}, mapping: { type: 'completion', payloads: true }
+  attribute :released, Date
+  attribute :notes
+  attribute :uri
+
+  attribute :tracklist, Array, mapping: { type: 'object' }
+
+  attribute :styles
+  attribute :meta, Meta, mapping: { type: 'object' }
+end

data/examples/music/artist.rb

@@ -0,0 +1,50 @@
+class Artist
+  include Elasticsearch::Persistence::Model
+
+  index_name [Rails.application.engine_name, Rails.env].join('-')
+
+  analyzed_and_raw = { fields: {
+    name: { type: 'string', analyzer: 'snowball' },
+    raw:  { type: 'string', analyzer: 'keyword' }
+  } }
+
+  attribute :name, String, mapping: analyzed_and_raw
+  attribute :suggest_name, String, default: {}, mapping: { type: 'completion', payloads: true }
+
+  attribute :profile
+  attribute :date, Date
+
+  attribute :members, String, default: [], mapping: analyzed_and_raw
+  attribute :members_combined, String, default: [], mapping: { analyzer: 'snowball' }
+  attribute :suggest_member, String, default: {}, mapping: { type: 'completion', payloads: true }
+
+  attribute :urls, String, default: []
+  attribute :album_count, Integer, default: 0
+
+  validates :name, presence: true
+
+  def albums
+    Album.search(
+      { query: {
+          has_parent: {
+            type: 'artist',
+            query: {
+              filtered: {
+                filter: {
+                  ids: { values: [ self.id ] }
+                }
+              }
+            }
+          }
+        },
+        sort: 'released',
+        size: 100
+      },
+      { type: 'album' }
+  )
+  end
+
+  def to_param
+    [id, name.parameterize].join('-')
+  end
+end

data/examples/music/artists/_form.html.erb

@@ -0,0 +1,8 @@
+<%= simple_form_for @artist do |f| %>
+  <%= f.input :name %>
+  <%= f.input :profile, as: :text %>
+  <%= f.input :date, as: :date %>
+  <%= f.input :members, hint: 'Separate names by comma', input_html: { value: f.object.members.join(', ') } %>
+
+  <%= f.button :submit %>
+<% end %>

data/examples/music/artists/artists_controller.rb

@@ -0,0 +1,67 @@
+class ArtistsController < ApplicationController
+  before_action :set_artist, only: [:show, :edit, :update, :destroy]
+
+  rescue_from Elasticsearch::Persistence::Repository::DocumentNotFound do
+    render file: "public/404.html", status: 404, layout: false
+  end
+
+  def index
+    @artists = Artist.all sort: 'name.raw', _source: ['name', 'album_count']
+  end
+
+  def show
+    @albums = @artist.albums
+  end
+
+  def new
+    @artist = Artist.new
+  end
+
+  def edit
+  end
+
+  def create
+    @artist = Artist.new(artist_params)
+
+    respond_to do |format|
+      if @artist.save refresh: true
+        format.html { redirect_to @artist, notice: 'Artist was successfully created.' }
+        format.json { render :show, status: :created, location: @artist }
+      else
+        format.html { render :new }
+        format.json { render json: @artist.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  def update
+    respond_to do |format|
+      if @artist.update(artist_params, refresh: true)
+        format.html { redirect_to @artist, notice: 'Artist was successfully updated.' }
+        format.json { render :show, status: :ok, location: @artist }
+      else
+        format.html { render :edit }
+        format.json { render json: @artist.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  def destroy
+    @artist.destroy refresh: true
+    respond_to do |format|
+      format.html { redirect_to artists_url, notice: 'Artist was successfully destroyed.' }
+      format.json { head :no_content }
+    end
+  end
+
+  private
+    def set_artist
+      @artist = Artist.find(params[:id].split('-').first)
+    end
+
+    def artist_params
+      a = params.require(:artist)
+      a[:members] = a[:members].split(/,\s?/) unless a[:members].is_a?(Array) || a[:members].blank?
+      return a
+    end
+end