elasticsearch-persistence 5.0.2 → 6.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 16991935a6a92bf65079ff6dcfe91e1893846421
-  data.tar.gz: 6d831835f08f046e32f4255e0f2eb91ee25ce100
+SHA256:
+  metadata.gz: 1d37ced5f5d7a21a94d37e5186a242b5c89f7dffa4503b5a286790061dfdf412
+  data.tar.gz: 412720f0597d5bd725e57cccffc17be2cef3242e33bd5720166b60af246c83e5
 SHA512:
-  metadata.gz: fc4df80b6eda6510e42c7a4d5f9111328efd1ca6aede2053d342061b3b2bb5b675fd326168b9252528cc86bcf62fe6e369433467b8b98410d940fdeba335466e
-  data.tar.gz: dbce37f333f0b0becb3e62b0907305a325e4f36518e466891ff81e66832ed84a0fad6fb1a87e1c7caec9521634c06d2092818aa42a2ae994c15471a6b7109d17
+  metadata.gz: 941fc4d03706ebe777ae7b3d55490962a3880f9d840588b58f803b45fda482574b94639db8c7fe2e639909c68c0206da6bdf12f85a66cd1ef63c64ef3c197ae7
+  data.tar.gz: adcdc8229548e59497afb2c0af4c09d50a3a75ed42f1a3406655ad4e577bf7c15a1c4177b9e7dc6d06db1918f87f76eaa589d7ce2637317710840780bc879780

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,16 +36,13 @@ 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
 
 The `Elasticsearch::Persistence::Repository` module provides an implementation of the
 [repository pattern](http://martinfowler.com/eaaCatalog/repository.html) and allows
-to save, delete, find and search objects stored in Elasticsearch, as well as configure
+you to save, delete, find and search objects stored in Elasticsearch, as well as configure
 mappings and settings for the index. It's an unobtrusive and decoupled way of adding
 persistence to your Ruby objects.
 
@@ -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...
@@ -77,7 +76,7 @@ We can save a `Note` instance into the repository...
 note = Note.new id: 1, text: 'Test'
 
 repository.save(note)
-# PUT http://localhost:9200/repository/note/1 [status:201, request:0.210s, query:n/a]
+# PUT http://localhost:9200/repository/_doc/1 [status:201, request:0.210s, query:n/a]
 # > {"id":1,"text":"Test"}
 # < {"_index":"repository","_type":"note","_id":"1","_version":1,"created":true}
 ```
@@ -86,7 +85,7 @@ repository.save(note)
 
 ```ruby
 n = repository.find(1)
-# GET http://localhost:9200/repository/_all/1 [status:200, request:0.003s, query:n/a]
+# GET http://localhost:9200/repository/_doc/1 [status:200, request:0.003s, query:n/a]
 # < {"_index":"repository","_type":"note","_id":"1","_version":2,"found":true, "_source" : {"id":1,"text":"Test"}}
 => <Note:0x007fcbfc0c4980 @attributes={"id"=>1, "text"=>"Test"}>
 ```
@@ -105,7 +104,7 @@ repository.search(query: { match: { text: 'test' } }).first
 
 ```ruby
 repository.delete(note)
-# DELETE http://localhost:9200/repository/note/1 [status:200, request:0.014s, query:n/a]
+# DELETE http://localhost:9200/repository/_doc/1 [status:200, request:0.014s, query:n/a]
 # < {"found":true,"_index":"repository","_type":"note","_id":"1","_version":3}
 => {"found"=>true, "_index"=>"repository", "_type"=>"note", "_id"=>"1", "_version"=>2}
 ```
@@ -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: :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,
@@ -176,7 +168,7 @@ Save the document with extra properties added by the `serialize` method:
 
 ```ruby
 repository.save(note)
-# PUT http://localhost:9200/my_notes/my_note/1
+# PUT http://localhost:9200/my_notes/note/1
 # > {"id":1,"text":"Test","my_special_key":"my_special_stuff"}
 {"_index"=>"my_notes", "_type"=>"my_note", "_id"=>"1", "_version"=>4, ... }
 ```
@@ -185,32 +177,31 @@ And `deserialize` it:
 
 ```ruby
 repository.find(1)
-# ***** CUSTOM DESERIALIZE LOGIC KICKING IN... *****
+# ***** CUSTOM DESERIALIZE LOGIC... *****
 <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,74 +223,160 @@ 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.
+```
 
-```ruby
-repository = NoteRepository.new url: 'http://localhost:9200', log: true
+You can also override the default configuration with options passed to the initialize method:
 
-# Configure the repository instance
-repository.index = 'notes_development'
-repository.client.transport.logger.formatter = proc { |s, d, p, m| "\e[2m# #{m}\n\e[0m" }
+```ruby
+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')
 
-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
+# PUT http://localhost:9200/notes_development/_doc/1
 # > {"id":1,"text":"Document with image","image":"Li4uIEJJTkFSWSBEQVRBIC4uLg==\n"}
 puts repository.find(1).attributes['image']
-# GET http://localhost:9200/notes_development/note/1
+# GET http://localhost:9200/notes_development/_doc/1
 # < {... "_source" : { ... "image":"Li4uIEJJTkFSWSBEQVRBIC4uLg==\n"}}
 # => ... 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 value. You can still override the configuration for any instance by passing options to the
+`#initialize` method.
+Even if you don't use the DSL mixin, you can set 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)
+repository.client
+# => Elasticsearch::Client
+
+```
+
+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
+repository.client
+# => Elasticsearch::Client
+
 ```
 
 ##### 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')
+repository.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
+repository.index_name
+# => 'notes_development'
+
+```
+
+The `document_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')
+repository.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
+repository.document_type
+# => 'note'
+
 ```
 
 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 = NoteRepository.new(klass: Note)
+repository.klass
+# => Note
+
+```
+
+or with the DSL mixin:
 
 ```ruby
-repository.klass = MyNote
+class NoteRepository
+  include Elasticsearch::Persistence::Repository
+  include Elasticsearch::Persistence::Repository::DSL
+
+  klass Note
+end
+
+repository = NoteRepository.new
+repository.klass
+# => Note
+
 ```
 
 ##### 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,18 +388,57 @@ 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
+
+```
+
+##### Create a Repository and set its configuration with a block
+
+You can also use the `#create` method to instantiate 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
+```
+
+##### Index Management
+
 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
 
-The `serialize` and `deserialize` methods allow you to customize the serialization of the document when passing it
-to the storage, and the initialization procedure when loading it from the storage:
+The `serialize` and `deserialize` methods allow you to customize the serialization of the document when it
+is persisted to Elasticsearch, and define the initialization procedure when loading it from the storage:
 
 ```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
@@ -336,7 +452,7 @@ The `save` method allows you to store a domain object in the repository:
 ```ruby
 note = Note.new id: 1, title: 'Quick Brown Fox'
 repository.save(note)
-# => {"_index"=>"notes_development", "_type"=>"my_note", "_id"=>"1", "_version"=>1, "created"=>true}
+# => {"_index"=>"notes_development", "_type"=>"_doc", "_id"=>"1", "_version"=>1, "created"=>true}
 ```
 
 The `update` method allows you to perform a partial update of a document in the repository.
@@ -344,18 +460,18 @@ Use either a partial document:
 
 ```ruby
 repository.update id: 1, title: 'UPDATED',  tags: []
-# => {"_index"=>"notes_development", "_type"=>"note", "_id"=>"1", "_version"=>2}
+# => {"_index"=>"notes_development", "_type"=>"_doc", "_id"=>"1", "_version"=>2}
 ```
 
 Or a script (optionally with parameters):
 
 ```ruby
 repository.update 1, script: 'if (!ctx._source.tags.contains(t)) { ctx._source.tags += t }', params: { t: 'foo' }
-# => {"_index"=>"notes_development", "_type"=>"note", "_id"=>"1", "_version"=>3}
+# => {"_index"=>"notes_development", "_type"=>"_doc", "_id"=>"1", "_version"=>3}
 ```
 
 
-The `delete` method allows to remove objects from the repository (pass either the object itself or its ID):
+The `delete` method allows you to remove objects from the repository (pass either the object itself or its ID):
 
 ```ruby
 repository.delete(note)
@@ -364,7 +480,7 @@ repository.delete(1)
 
 ##### Finding
 
-The `find` method allows to find one or many documents in the storage and returns them as deserialized Ruby objects:
+The `find` method allows you to find one or many documents in the storage and returns them as deserialized Ruby objects:
 
 ```ruby
 repository.save Note.new(id: 2, title: 'Fast White Dog')
@@ -387,15 +503,15 @@ Handle the missing objects in the application code, or call `compact` on the res
 
 ##### Search
 
-The `search` method to retrieve objects from the repository by a query string or definition in the Elasticsearch DSL:
+The `search` method is used to retrieve objects from the repository by a query string or definition in the Elasticsearch DSL:
 
 ```ruby
 repository.search('fox or dog').to_a
-# GET http://localhost:9200/notes_development/my_note/_search?q=fox
+# GET http://localhost:9200/notes_development/_doc/_search?q=fox
 # => [<MyNote ... FOX ...>, <MyNote ... DOG ...>]
 
 repository.search(query: { match: { title: 'fox dog' } }).to_a
-# GET http://localhost:9200/notes_development/my_note/_search
+# GET http://localhost:9200/notes_development/_doc/_search
 # > {"query":{"match":{"title":"fox dog"}}}
 # => [<MyNote ... FOX ...>, <MyNote ... DOG ...>]
 ```
@@ -427,9 +543,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,262 +567,8 @@ and demonstrates a rich set of features:
 
 ### The ActiveRecord Pattern
 
-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