elasticsearch-persistence 5.1.0 → 6.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad7450ff0696099a095419ee12da5d4ea875646ad591545f95bae8fc2408ce2
-  data.tar.gz: 339a759ce92884321d4adbb7fa63f4ee3a155958d97e5ea3ee8c55b60cd21e8a
+  metadata.gz: dd3b68c6704df1a51940545080b631c127701074727d9879c5eaf9bf29513d63
+  data.tar.gz: 966be9deff09a99f149b8c7206b383737be278dd96f368fbda45d30b59fc0439
 SHA512:
-  metadata.gz: 8a1477b512b7cdbb812866c7b582e1417871713689c165d876b49df44e7d8095d08d7b5993110b23071d784f9c9c19db6d58a771bd0b1627d1f9c75bd75586ed
-  data.tar.gz: 7eb56ed82336e9648a0fe3a3288c854621811f13b07ee6402138086c4dfe28fd78b4f283b4a0ea1a140678d8f625794c6aad3c386cfa346eec017b92ee007a06
+  metadata.gz: 0ffc1d1c058660ee3060ffaac44449e4a19b0ee34b2f12f1818aa22753c4a670c7c3dfe9975f44bc41cff8913cb6604bcc6e8e61633e8263ef1888c4a024382b
+  data.tar.gz: 2e589e4a386389e4c41a95c92738d79def0ff49ec18ee2add9ba07e813ae4d2704156dbbe0a9dafeff3cc9767fda38fbfd570ad3c6a7d0be7973f92ab33e35b4

data/.rspec

@@ -0,0 +1,2 @@
+--tty
+--colour

data/Gemfile

@@ -2,3 +2,12 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in elasticsearch-persistence.gemspec
 gemspec
+
+gem 'elasticsearch-model', :path => File.expand_path("../../elasticsearch-model", __FILE__), :require => false
+
+gem 'virtus'
+
+group :development, :testing do
+  gem 'rspec'
+  gem 'pry-nav'
+end

data/README.md

@@ -1,6 +1,6 @@
 # Elasticsearch::Persistence
 
-Persistence layer for Ruby domain objects in Elasticsearch, using the Repository and ActiveRecord patterns.
+Persistence layer for Ruby domain objects in Elasticsearch, using the Repository pattern.
 
 ## Compatibility
 
@@ -14,6 +14,7 @@ is compatible with the Elasticsearch `master` branch, therefore, with the next m
 | 0.1           | → | 1.x           |
 | 2.x           | → | 2.x           |
 | 5.x           | → | 5.x           |
+| 6.x           | → | 6.x           |
 | master        | → | master        |
 
 ## Installation
@@ -24,7 +25,7 @@ Install the package from [Rubygems](https://rubygems.org):
 
 To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://bundler.io):
 
-    gem 'elasticsearch-persistence', git: 'git://github.com/elastic/elasticsearch-rails.git', branch: '5.x'
+    gem 'elasticsearch-persistence', git: 'git://github.com/elastic/elasticsearch-rails.git', branch: '6.x'
 
 or install it from a source code checkout:
 
@@ -35,10 +36,7 @@ or install it from a source code checkout:
 
 ## Usage
 
-The library provides two different patterns for adding persistence to your Ruby objects:
-
-* [Repository Pattern](#the-repository-pattern)
-* [ActiveRecord Pattern](#the-activerecord-pattern)
+The library provides the Repository pattern for adding persistence to your Ruby objects.
 
 ### The Repository Pattern
 
@@ -68,7 +66,8 @@ Let's create a default, "dumb" repository, as a first step:
 
 ```ruby
 require 'elasticsearch/persistence'
-repository = Elasticsearch::Persistence::Repository.new
+class MyRepository; include Elasticsearch::Persistence::Repository; end
+repository = MyRepository.new
 ```
 
 We can save a `Note` instance into the repository...
@@ -121,32 +120,17 @@ The repository module provides a number of features and facilities to configure
 * Providing access to the Elasticsearch response for search results (aggregations, total, ...)
 * Defining the methods for serialization and deserialization
 
-You can use the default repository class, or include the module in your own. Let's review it in detail.
+There are two mixins you can include in your Repository class. The first `Elasticsearch::Persistence::Repository`,
+provides the basic methods and settings you'll need. The second, `Elasticsearch::Persistence::Repository::DSL` adds
+some additional class methods that allow you to set options that instances of the class will share.
 
-#### The Default Class
+#### Basic Repository mixin
 
-For simple cases, you can use the default, bundled repository class, and configure/customize it:
+For simple cases, you can just include the Elasticsearch::Persistence::Repository mixin to your class:
 
 ```ruby
-repository = Elasticsearch::Persistence::Repository.new do
-  # Configure the Elasticsearch client
-  client Elasticsearch::Client.new url: ENV['ELASTICSEARCH_URL'], log: true
-
-  # Set a custom index name
-  index :my_notes
-
-  # Set a custom document type
-  type  :my_note
-
-  # Specify the class to initialize when deserializing documents
-  klass Note
-
-  # Configure the settings and mappings for the Elasticsearch index
-  settings number_of_shards: 1 do
-    mapping do
-      indexes :text, analyzer: 'snowball'
-    end
-  end
+class MyRepository
+  include Elasticsearch::Persistence::Repository
 
   # Customize the serialization logic
   def serialize(document)
@@ -155,10 +139,18 @@ repository = Elasticsearch::Persistence::Repository.new do
 
   # Customize the de-serialization logic
   def deserialize(document)
-    puts "# ***** CUSTOM DESERIALIZE LOGIC KICKING IN... *****"
+    puts "# ***** CUSTOM DESERIALIZE LOGIC... *****"
     super
   end
 end
+
+client = Elasticsearch::Client.new(url: ENV['ELASTICSEARCH_URL'], log: true)
+repository = MyRepository.new(client: client, index_name: :my_notes, type: :my_note, klass: Note)
+repository.settings number_of_shards: 1 do
+  mapping do
+    indexes :text, analyzer: 'snowball'
+  end
+end
 ```
 
 The custom Elasticsearch client will be used now, with a custom index and type names,
@@ -189,28 +181,27 @@ repository.find(1)
 <Note:0x007f9bd782b7a0 @attributes={... "my_special_key"=>"my_special_stuff"}>
 ```
 
-#### A Custom Class
+#### The DSL mixin
 
-In most cases, though, you'll want to use a custom class for the repository, so let's do that:
+In some cases, you'll want to set some of the repository configurations at the class level. This makes
+most sense when the instances of the repository will use that same configuration:
 
 ```ruby
 require 'base64'
 
 class NoteRepository
   include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
 
-  def initialize(options={})
-    index  options[:index] || 'notes'
-    client Elasticsearch::Client.new url: options[:url], log: options[:log]
-  end
-
+  index_name 'notes'
+  document_type 'note'
   klass Note
 
   settings number_of_shards: 1 do
     mapping do
       indexes :text,  analyzer: 'snowball'
       # Do not index images
-      indexes :image, index: 'no'
+      indexes :image, index: false
     end
   end
 
@@ -232,23 +223,26 @@ class NoteRepository
 end
 ```
 
-Include the `Elasticsearch::Persistence::Repository` module to add the repository methods into the class.
+You can create an instance of this custom class and get each of the configurations.
 
-You can customize the repository in the familiar way, by calling the DSL-like methods.
+```ruby
+client = Elasticsearch::Client.new(url: 'http://localhost:9200', log: true)
+repository = NoteRepository.new(client: client)
+repository.index_name
+# => 'notes'
 
-You can implement a custom initializer for your repository, add complex logic in its
-class and instance methods -- in general, have all the freedom of a standard Ruby class.
+```
+
+You can also override the default configuration with options passed to the initialize method:
 
 ```ruby
-repository = NoteRepository.new url: 'http://localhost:9200', log: true
+client = Elasticsearch::Client.new(url: 'http://localhost:9250', log: true)
+client.transport.logger.formatter = proc { |s, d, p, m| "\e[2m# #{m}\n\e[0m" }
+repository = NoteRepository.new(client: client, index_name: 'notes_development')
 
-# Configure the repository instance
-repository.index = 'notes_development'
-repository.client.transport.logger.formatter = proc { |s, d, p, m| "\e[2m# #{m}\n\e[0m" }
+repository.create_index!(force: true)
 
-repository.create_index! force: true
-
-note = Note.new 'id' => 1, 'text' => 'Document with image', 'image' => '... BINARY DATA ...'
+note = Note.new('id' => 1, 'text' => 'Document with image', 'image' => '... BINARY DATA ...')
 
 repository.save(note)
 # PUT http://localhost:9200/notes_development/note/1
@@ -259,47 +253,110 @@ puts repository.find(1).attributes['image']
 # => ... BINARY DATA ...
 ```
 
-#### Methods Provided by the Repository
+#### Functionality Provided by the Repository mixin
+
+Each of the following configurations can be set for a repository instance.
+If you have included the `Elasticsearch::Persistence::Repository::DSL` mixin, then you can use the class-level DSL
+methods to set each configuration. You can override the configuration for any instance by passing options to the
+`#initialize` method.
+If you don't use the DSL mixin, you can set also the instance configuration with options passed the `#initialize` method.
 
 ##### Client
 
-The repository uses the standard Elasticsearch [client](https://github.com/elastic/elasticsearch-ruby#usage),
-which is accessible with the `client` getter and setter methods:
+The repository uses the standard Elasticsearch [client](https://github.com/elastic/elasticsearch-ruby#usage).
 
 ```ruby
-repository.client = Elasticsearch::Client.new url: 'http://search.server.org'
+client = Elasticsearch::Client.new(url: 'http://search.server.org')
+repository = NoteRepository.new(client: client)
 repository.client.transport.logger = Logger.new(STDERR)
 ```
 
+or with the DSL mixin:
+
+```ruby
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  client Elasticsearch::Client.new url: 'http://search.server.org'
+end
+
+repository = NoteRepository.new
+
+```
+
 ##### Naming
 
-The `index` method specifies the Elasticsearch index to use for storage, lookup and search
-(when not set, the value is inferred from the repository class name):
+The `index_name` method specifies the Elasticsearch index to use for storage, lookup and search. The default index name
+is 'repository'.
+
+```ruby
+repository = NoteRepository.new(index_name: 'notes_development')
+```
+
+or with the DSL mixin:
+
+```ruby
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  index_name 'notes_development'
+end
+
+repository = NoteRepository.new
+
+```
+
+The `type` method specifies the Elasticsearch document type to use for storage, lookup and search. The default value is
+'_doc'. Keep in mind that future versions of Elasticsearch will not allow you to set this yourself and will use the type,
+'_doc'.
 
 ```ruby
-repository.index = 'notes_development'
+repository = NoteRepository.new(document_type: 'note')
 ```
 
-The `type` method specifies the Elasticsearch document type to use for storage, lookup and search
-(when not set, the value is inferred from the document class name, or `_all` is used):
+or with the DSL mixin:
 
 ```ruby
-repository.type = 'my_note'
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  document_type 'note'
+end
+
+repository = NoteRepository.new
+
 ```
 
 The `klass` method specifies the Ruby class name to use when initializing objects from
-documents retrieved from the repository (when not set, the value is inferred from the
-document `_type` as fetched from Elasticsearch):
+documents retrieved from the repository. If this value is not set, a Hash representation of the document will be 
+returned instead.
 
 ```ruby
-repository.klass = MyNote
+repository = NoteRepository.new(klass: Note)
+```
+
+or with the DSL mixin:
+
+```ruby
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  klass Note
+end
+
+repository = NoteRepository.new
+
 ```
 
 ##### Index Configuration
 
 The `settings` and `mappings` methods, provided by the
 [`elasticsearch-model`](http://rubydoc.info/gems/elasticsearch-model/Elasticsearch/Model/Indexing/ClassMethods)
-gem, allow to configure the index properties:
+gem, allow you to configure the index properties:
 
 ```ruby
 repository.settings number_of_shards: 1
@@ -311,7 +368,39 @@ repository.mappings.to_hash
 # => { :note => {:properties=> ... }}
 ```
 
+or with the DSL mixin:
+
+```ruby
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  mappings { indexes :title, analyzer: 'snowball' }
+  settings number_of_shards: 1
+end
+
+repository = NoteRepository.new
+
+```
+
+You can also use the `#create` method defined on the repository class to create and set the mappings and settings 
+on an instance with a block in one call:
+
+```ruby
+repository = NoteRepository.create(index_name: 'notes_development') do
+  settings number_of_shards: 1, number_of_replicas: 0 do
+    mapping dynamic: 'strict' do
+      indexes :foo do
+        indexes :bar
+      end
+      indexes :baz
+    end
+  end
+end
+```
+
 The convenience methods `create_index!`, `delete_index!` and `refresh_index!` allow you to manage the index lifecycle.
+These methods can only be called on repository instances and are not implemented at the class level.
 
 ##### Serialization
 
@@ -320,9 +409,12 @@ to the storage, and the initialization procedure when loading it from the storag
 
 ```ruby
 class NoteRepository
+  include Elasticsearch::Persistence::Repository
+
   def serialize(document)
     Hash[document.to_hash.map() { |k,v|  v.upcase! if k == :title; [k,v] }]
   end
+
   def deserialize(document)
     MyNote.new ActiveSupport::HashWithIndifferentAccess.new(document['_source']).deep_symbolize_keys
   end
@@ -427,9 +519,15 @@ end
 results.total
 # => 2
 
-# Access the raw response as a Hashie::Mash instance
+# Access the raw response as a Hashie::Mash instance.
+# Note that a Hashie::Mash will only be created if the 'response' method is called on the results. 
 results.response._shards.failed
 # => 0
+
+# Access the raw response
+results.raw_response
+# => {...}
+
 ```
 
 #### Example Application
@@ -445,265 +543,8 @@ and demonstrates a rich set of features:
 
 ### The ActiveRecord Pattern
 
-Please note that this pattern is deprecated and will be removed in version 6.0.
-The [Repository Pattern](#the-repository-pattern) is recommended instead.
-
-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: 'text'},
-                               raw:    { type: '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 "Successfully saved: #{self}" }
-end
-```
-
-Attribute validations work 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
-# Successfully saved: #<Article {...}>
-```
-
-The model also supports familiar `find_in_batches` and `find_each` methods to efficiently
-retrieve big collections of model instances, 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&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
-```
-
-#### The Elasticsearch Client
-
-The module will set up a [client](https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch),
-connected to `localhost:9200`, by default.
-
-To use a client with different configuration:
-
-```ruby
-Elasticsearch::Persistence.client = Elasticsearch::Client.new log: true
-```
-
-To set up a specific client for a specific model:
-
-```ruby
-Article.gateway.client = Elasticsearch::Client.new host: 'api.server.org'
-```
-
-You might want to do this during you application bootstrap process, e.g. in a Rails initializer.
-
-Please refer to the
-[`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport)
-library documentation for all the configuration options, and to the
-[`elasticsearch-api`](http://rubydoc.info/gems/elasticsearch-api) library documentation
-for information about the Ruby client API.
-
-#### Accessing the Repository Gateway and the Client
-
-The integration with Elasticsearch 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 to facilitate building the application scaffolding:
-
-```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/elastic/elasticsearch-rails/master/elasticsearch-persistence/examples/music/template.rb
-```
-
-The application demonstrates:
-
-* How to set up model attributes with custom mappings
-* How to define 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 models 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.
+The ActiveRecord pattern has been deprecated as of version 6.0.0 of this gem. Please use the
+[Repository Pattern](#the-repository-pattern) instead.
 
 ## License