chewy 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a311bdd3957835909c81ba57886bba5fbebebbef
-  data.tar.gz: 0011b212e985166c040bb195ec3dc0214b797ab5
+  metadata.gz: 465b8f0c2bff702e61235bbd9b6782f3f57296e6
+  data.tar.gz: 60827a551d9b4338ee87a91c346b84cfbcca6aa2
 SHA512:
-  metadata.gz: 2727a488bbaefa2b0d9bd47da643a83e72882bfe3da41e4eda9e7e59df37fb72ad0343273594ae7dfbfbb8d4f84534d63867038b6fd8de667aca4eb0126c34a3
-  data.tar.gz: 6e54cfb1362cc06ff500ee01eb24c809c54c590b6390e20bfd45db4bb61c0c403ea3afd93b6dd3ef23bb53336efb157bd9c4cbca2aad9065db019a6693e84530
+  metadata.gz: e0efb611f827fa291ea9f3765d14e50450e6787f0541e9c04f034d79e20189cdb8dd718e2c8c8074e7736ac3575018e13fe9317f880d7b6d0429ac1ab060e6b2
+  data.tar.gz: 0270d359d7831c3f1c0217369f32d5017c7b90e7871780a5e79f7945414c7a3aaadf39f1505ab85c7a3c61a1f2fbb28ae49c183034f43c12d1ed065cf66e9acf

data/.travis.yml

@@ -1,10 +1,11 @@
 language: ruby
+sudo: false
 services:
   - mongodb
 rvm:
-  - 2.0.0
-  - 2.1.5
-  - 2.2.0
+  - 2.0
+  - 2.1
+  - 2.2
   # - rbx
 gemfile:
   - gemfiles/rails.3.2.activerecord.gemfile
@@ -28,15 +29,16 @@ gemfile:
   - gemfiles/rails.4.2.mongoid.gemfile
   - gemfiles/rails.4.2.mongoid.kaminari.gemfile
   - gemfiles/rails.4.2.mongoid.will_paginate.gemfile
+  - gemfiles/sequel.4.23.gemfile
 matrix:
   exclude:
-    - rvm: 2.2.0
+    - rvm: 2.2
       gemfile: gemfiles/rails.3.2.activerecord.gemfile
-    - rvm: 2.2.0
+    - rvm: 2.2
       gemfile: gemfiles/rails.3.2.activerecord.kaminari.gemfile
-    - rvm: 2.2.0
+    - rvm: 2.2
       gemfile: gemfiles/rails.3.2.activerecord.will_paginate.gemfile
 before_install:
-  - curl -# https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.5.2.tar.gz | tar xz -C /tmp
+  - curl -# https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.7.2.tar.gz | tar xz -C /tmp
 before_script:
-  - TEST_CLUSTER_COMMAND="/tmp/elasticsearch-1.5.2/bin/elasticsearch" rake elasticsearch:start
+  - TEST_CLUSTER_COMMAND="/tmp/elasticsearch-1.7.2/bin/elasticsearch" rake elasticsearch:start

data/Appraisals

@@ -2,6 +2,7 @@
   appraise "rails.#{version}.activerecord" do
     gem 'activerecord', "~> #{version}.0"
     gem 'activesupport', "~> #{version}.0"
+    gem 'activejob', "~> #{version}.0" if version >= '4.2'
     gem 'resque', require: false
     gem 'sidekiq', require: false
   end
@@ -9,12 +10,14 @@
   appraise "rails.#{version}.activerecord.kaminari" do
     gem 'activerecord', "~> #{version}.0"
     gem 'activesupport', "~> #{version}.0"
+    gem 'activejob', "~> #{version}.0" if version >= '4.2'
     gem 'kaminari', '0.16.3', require: false
   end
 
   appraise "rails.#{version}.activerecord.will_paginate" do
     gem 'activerecord', "~> #{version}.0"
     gem 'activesupport', "~> #{version}.0"
+    gem 'activejob', "~> #{version}.0" if version >= '4.2'
     gem 'will_paginate', require: false
   end
 end
@@ -39,3 +42,8 @@ end
     gem 'will_paginate', require: false
   end
 end
+
+appraise "sequel.4.23" do
+  gem 'sequel', "~> 4.23.0"
+  gem 'activesupport', '~> 4.2.0'
+end

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # master
 
+# Version 0.8.2
+
+## Changes
+
+  * ActiveJob strategy by @mkcode
+
+  * Async strategies tweak (@AndreySavelyev)
+
+  * GeoPoint readme (@joonty)
+
+  * Multiple grammar fixes and code improvements (@biow0lf)
+
+  * Named aggregations by @caldwecr
+
+  * Sequel adapter by @jirutka
+
+  * Rake helper methods extracted (@caldwecr, @jirutka)
+
+  * Multiple grammar fixes (@henrebotha)
+
+  * Ability to pass a proc to `update_index` to define updating index dynamically (@SeTeM)
+
+
+## Bugfixes
+
+  * Fixed transport logger and tracer configuration
+
 # Version 0.8.1
 
 ## Bugfixes
@@ -18,7 +45,7 @@
 
   * Added `.script_fields` chainable method to query (@ka8725)
 
-  * `update_index` mocha support (@lardawge)
+  * `update_index` matcher mocha support (@lardawge)
 
   * `:resque` async strategy
 
@@ -90,7 +117,7 @@
 
   * Multiple enhancements by @DNNX
 
-  * Added `script_fields` to search crteria (@ka8725)
+  * Added `script_fields` to search criteria (@ka8725)
 
   * ORM adapters now completely relies on the default scope. This means every scope or objects passed to import are merged with default scope so basically there is no need to define `delete_if` block. Default scope strongly restricts objects which may land in the current index.
 
@@ -269,13 +296,13 @@
 
 # Version 0.4.0
 
-  * Changed `update_index` matcher behavior. Now it compare array attributes position-independantly.
+  * Changed `update_index` matcher behavior. Now it compare array attributes position-independently.
 
   * Search aggregations API support (@arion).
 
   * Chewy::Query#facets called without params performs the request and returns facets.
 
-  * Added `Type.template` dsl method for root objects dynamic templates definition. See [mapping.rb](lib/chewy/type/mapping.rb) for more details.
+  * Added `Type.template` DSL method for root objects dynamic templates definition. See [mapping.rb](lib/chewy/type/mapping.rb) for more details.
 
   * ActiveRecord adapter custom `primary_key` support (@matthee).
 
@@ -414,8 +441,8 @@
 
 # Version 0.0.1
 
-  * Query dsl
+  * Query DSL
 
-  * Basic index hadling
+  * Basic index handling
 
   * Initial version

data/Gemfile

@@ -2,14 +2,16 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'activerecord'
+# gem 'activerecord'
 # gem 'mongoid'
+# gem 'sequel'
 
 # gem 'kaminari', require: false
-# gem 'will_pagnate', require: false
+# gem 'will_paginate', require: false
 
-gem 'resque', require: false
-gem 'sidekiq', require: false
+# gem 'resque', require: false
+# gem 'sidekiq', require: false
+# gem 'activejob', require: false
 
 group :test do
   gem 'guard'

data/README.md

@@ -1,6 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/chewy.svg)](http://badge.fury.io/rb/chewy)
-[![Build Status](https://travis-ci.org/toptal/chewy.png)](https://travis-ci.org/toptal/chewy)
-[![Code Climate](https://codeclimate.com/github/toptal/chewy.png)](https://codeclimate.com/github/toptal/chewy)
+[![Build Status](https://travis-ci.org/toptal/chewy.svg)](https://travis-ci.org/toptal/chewy)
+[![Code Climate](https://codeclimate.com/github/toptal/chewy.svg)](https://codeclimate.com/github/toptal/chewy)
 [![Inline docs](http://inch-ci.org/github/toptal/chewy.svg?branch=master)](http://inch-ci.org/github/toptal/chewy)
 
 <p align="right">Sponsored by</p>
@@ -8,25 +8,28 @@
 
 # Chewy
 
-Chewy is ODM and wrapper for official elasticsearch client (https://github.com/elasticsearch/elasticsearch-ruby)
+Chewy is an ODM and wrapper for [the official Elasticsearch client](https://github.com/elasticsearch/elasticsearch-ruby).
 
-## Why chewy?
+## Why Chewy?
 
-* Multi-model indexes.
+* Multi-model indices.
 
-  Index classes are independent from ORM/ODM models. Now implementing, e.g. cross-model autocomplete is much easier. You can just define index and work with it in object-oriented style. You can define several types for index - one per indexed model.
+  Index classes are independent from ORM/ODM models. Now, implementing e.g. cross-model autocomplete is much easier. You can just define the index and work with it in an object-oriented style. You can define several types for index - one per indexed model.
 
 * Every index is observable by all the related models.
 
-  Most of the indexed models are related to other and sometimes it is nessesary to denormalize this related data and put at the same object. For example, you need to index array of tags with article together. Chewy allows you to specify updatable index for every model separately. So, corresponding articles will be reindexed on any tag update.
+  Most of the indexed models are related to other and sometimes it is necessary to denormalize this related data and put at the same object. For example, you need to index an array of tags together with an article. Chewy allows you to specify an updateable index for every model separately - so corresponding articles will be reindexed on any tag update.
 
 * Bulk import everywhere.
 
-  Chewy utilizes bulk ES API for full reindexing or index updates. Also it uses atomic updates concept. All the changed objects are collected inside the atomic block and index is updated once at the end of it with all the collected object. See `Chewy.strategy(:atomic)` for more details.
+  Chewy utilizes the bulk ES API for full reindexing or index updates. It also uses atomic updates. All the changed objects are collected inside the atomic block and the index is updated once at the end with all the collected objects. See `Chewy.strategy(:atomic)` for more details.
 
 * Powerful querying DSL.
 
-  Chewy has AR-style query DSL. It is chainable, mergable and lazy. So you can produce queries in the most efficient way. Also it has object-oriented query and filter builders.
+  Chewy has an ActiveRecord-style query DSL. It is chainable, mergeable and lazy, so you can produce queries in the most efficient way. It also has object-oriented query and filter builders.
+
+* Support for ActiveRecord, [Mongoid](https://github.com/mongoid/mongoid) and [Sequel](https://github.com/jeremyevans/sequel).
+
 
 ## Installation
 
@@ -46,9 +49,9 @@ Or install it yourself as:
 
 ### Client settings
 
-There are 2 ways to configure Chewy client: `Chewy.settings` hash and `chewy.yml`
+There are two ways to configure the Chewy client: the `Chewy.settings` hash and `chewy.yml`
 
-You can create this file manually or run `rails g chewy:install` to do that with yaml way
+You can create this file manually or run `rails g chewy:install`.
 
 ```ruby
 # config/initializers/chewy.rb
@@ -65,17 +68,17 @@ development:
   host: 'localhost:9200'
 ```
 
-The result config merges both hashes. Client options are passed as is to Elasticsearch::Transport::Client except the `:prefix` - it is used internally by chewy to create prefixed index names:
+The resulting config merges both hashes. Client options are passed as is to `Elasticsearch::Transport::Client` except for the `:prefix`, which is used internally by Chewy to create prefixed index names:
 
 ```ruby
   Chewy.settings = {prefix: 'test'}
   UsersIndex.index_name # => 'test_users'
 ```
 
-Also logger might be set explicitly:
+The logger may be set explicitly:
 
 ```ruby
-Chewy.logger = Logger.new
+Chewy.logger = Logger.new(STDOUT)
 ```
 
 See [config.rb](lib/chewy/config.rb) for more details.
@@ -106,7 +109,7 @@ See [config.rb](lib/chewy/config.rb) for more details.
   class UsersIndex < Chewy::Index
     define_type User.active.includes(:country, :badges, :projects) do
       field :first_name, :last_name # multiple fields without additional options
-      field :email, analyzer: 'email' # elasticsearch-related options
+      field :email, analyzer: 'email' # Elasticsearch-related options
       field :country, value: ->(user) { user.country.name } # custom value proc
       field :badges, value: ->(user) { user.badges.map(&:name) } # passing array values to index
       field :projects do # the same block syntax for multi_field, if `:type` is specified
@@ -122,9 +125,9 @@ See [config.rb](lib/chewy/config.rb) for more details.
   end
   ```
 
-  Mapping definitions - http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping.html
+  [See here for mapping definitions](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping.html).
 
-4. Add some index- and type-related settings. Analyzers repositories might be used as well. See `Chewy::Index.settings` docs for details:
+4. Add some index- and type-related settings. Analyzer repositories might be used as well. See `Chewy::Index.settings` docs for details:
 
   ```ruby
   class UsersIndex < Chewy::Index
@@ -149,7 +152,7 @@ See [config.rb](lib/chewy/config.rb) for more details.
           field :title
           field :description
         end
-        field :about_translations, type: 'object' # pass object type explicitely if necessary
+        field :about_translations, type: 'object' # pass object type explicitly if necessary
         field :rating, type: 'integer'
         field :created, type: 'date', include_in_all: false,
           value: ->{ created_at }
@@ -158,16 +161,16 @@ See [config.rb](lib/chewy/config.rb) for more details.
   end
   ```
 
-  Index settings - http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-update-settings.html
-  Root object settings - http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-root-object-type.html
+  [See index settings here](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-update-settings.html).
+  [See root object settings here](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-root-object-type.html).
 
   See [mapping.rb](lib/chewy/type/mapping.rb) for more details.
 
-5. Add model observing code
+5. Add model-observing code
 
   ```ruby
   class User < ActiveRecord::Base
-    update_index('users#user') { self } # specifying index, type and backreference
+    update_index('users#user') { self } # specifying index, type and back-reference
                                         # for updating after user save or destroy
   end
 
@@ -178,7 +181,7 @@ See [config.rb](lib/chewy/config.rb) for more details.
   end
 
   class Project < ActiveRecord::Base
-    update_index('users#user') { user if user.active? } # you can return even `nil` from the backreference
+    update_index('users#user') { user if user.active? } # you can return even `nil` from the back-reference
   end
 
   class Badge < ActiveRecord::Base
@@ -187,16 +190,22 @@ See [config.rb](lib/chewy/config.rb) for more details.
     update_index('users') { users } # if index has only one type
                                     # there is no need to specify updated type
   end
+
+  class Book < ActiveRecord::Base
+    update_index(->(book) {"books#book_#{book.language}"}) { self } # dynamic index and type with proc.
+                                                                    # For book with language == "en"
+                                                                    # this code will generate `books#book_en`
+  end
   ```
 
-  Also, you can use second argument for method name passing:
+  Also, you can use the second argument for method name passing:
 
   ```ruby
   update_index('users#user', :self)
   update_index('users#user', :users)
   ```
 
-  In case of belongs_to association you may need to update both associated objects, previous and current:
+  In the case of a belongs_to association you may need to update both associated objects, previous and current:
 
   ```ruby
   class City < ActiveRecord::Base
@@ -212,9 +221,67 @@ See [config.rb](lib/chewy/config.rb) for more details.
   end
   ```
 
+  You can observe Sequel models in the same way as ActiveRecord:
+
+  ```ruby
+  class User < Sequel::Model
+    update_index('users#user') { self }
+  end
+  ```
+
+  However, to make it work, you must load the chewy plugin into Sequel model:
+
+  ```ruby
+  Sequel::Model.plugin :chewy_observe  # for all models, or...
+  User.plugin :chewy_observe           # just for User
+  ```
+
+### Multi (nested) and object field types
+
+To define an objects field you can simply nest fields in the DSL:
+
+```ruby
+field :projects do
+  field :title
+  field :description
+end
+```
+
+This will automatically set the type or root field to `object`. You may also specify `type: 'objects'` explicitly.
+
+To define a multi field you have to specify any type except for `object` or `nested` in the root field:
+
+```ruby
+field :full_name, type: 'string', value: ->{ full_name.strip } do
+  field :ordered, analyzer: `ordered`
+  field :untouched, index: 'not_analyzed'
+end
+```
+
+The `value:` option for internal fields would no longer be effective.
+
+### Geo Point fields
+
+You can use [Elasticsearch's geo mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-geo-point-type.html) with the `geo_point` field type, allowing you to query, filter and order by latitude and longitude. You can use the following hash format:
+
+```ruby
+field :coordinates, type: 'geo_point', value: ->{ {lat: latitude, lon: longitude} }
+```
+
+or by using nested fields:
+
+```ruby
+field :coordinates, type: 'geo_point' do
+  field :lat, value: ->{ latitude }
+  field :long, value: ->{ longitude }
+end
+```
+
+See the section on *Script fields* for details on calculating distance in a search.
+
 ### Crutches™ technology
 
-Assume you are defining index like this (product has_many categories through product_categories):
+Assume you are defining your index like this (product has_many categories through product_categories):
 
 ```ruby
 class ProductsIndex < Chewy::Index
@@ -225,7 +292,7 @@ class ProductsIndex < Chewy::Index
 end
 ```
 
-Then chewy reindexing flow would be look like following pseudo-code (even in mongoid):
+Then the Chewy reindexing flow would look like the following pseudo-code (even in Mongoid):
 
 ```ruby
 Product.includes(:categories).find_in_batches(1000) do |batch|
@@ -237,9 +304,9 @@ Product.includes(:categories).find_in_batches(1000) do |batch|
 end
 ```
 
-But in rails 4.1 and 4.2 you may face with slow associations problem (take a look on https://github.com/rails/rails/pull/19423) also, there might be really complicated cases when associations are not applicable.
+But in Rails 4.1 and 4.2 you may face a problem with slow associations (take a look at https://github.com/rails/rails/pull/19423). Also, there might be really complicated cases when associations are not applicable.
 
-Then you are able to replace rails associations with Chewy Crutches™ technology:
+Then you can replace Rails associations with Chewy Crutches™ technology:
 
 ```ruby
 class ProductsIndex < Chewy::Index
@@ -249,7 +316,7 @@ class ProductsIndex < Chewy::Index
       data = ProductCategory.joins(:category).where(product_id: collection.map(&:id)).pluck(:product_id, 'categories.name')
       # then we have to convert fetched data to appropriate format
       # this will return our data in structure like:
-      # {123 => ['seweets', 'juices'], 456 => ['meat']}
+      # {123 => ['sweets', 'juices'], 456 => ['meat']}
       data.each.with_object({}) { |(id, name), result| (result[id] ||= []).push(name) }
     end
 
@@ -260,7 +327,7 @@ class ProductsIndex < Chewy::Index
 end
 ```
 
-And example flow would be look like this:
+An example flow would look like this:
 
 ```ruby
 Product.includes(:categories).find_in_batches(1000) do |batch|
@@ -274,11 +341,11 @@ Product.includes(:categories).find_in_batches(1000) do |batch|
 end
 ```
 
-So Chewy Crutches™ technology is able to increase your indexing performance in some cases up to 100 times or even more depending on your associations complexity.
+So Chewy Crutches™ technology is able to increase your indexing performance in some cases up to a hundredfold or even more depending on your associations complexity.
 
 ### Types access
 
-You are able to access index-defined types with the following API:
+You can access index-defined types with the following API:
 
 ```ruby
 UsersIndex::User # => UsersIndex::User
@@ -291,7 +358,7 @@ UsersIndex.type_names # => ['user']
 ### Index manipulation
 
 ```ruby
-UsersIndex.delete # destroy index if exists
+UsersIndex.delete # destroy index if it exists
 UsersIndex.delete!
 
 UsersIndex.create
@@ -312,7 +379,7 @@ UsersIndex.import user: User.where('rating > 100') # import only active users to
 UsersIndex.reset! # purges index and imports default data for all types
 ```
 
-Also if passed user is `#destroyed?`, or satisfy `delete_if` type option, or specified id does not exists in the database, import will perform delete from index action for this object.
+If the passed user is `#destroyed?`, or satisfies a `delete_if` type option, or the specified id does not exist in the database, import will perform delete from index action for this object.
 
 ```ruby
 define_type User, delete_if: :deleted_at
@@ -338,18 +405,13 @@ class CitiesIndex < Chewy::Index
 end
 ```
 
-If you'll perform something like `City.first.save!` you'll get
-UndefinedUpdateStrategy exception instead of normal object saving
-and index update. This exception forces you to choose appropriate
-update strategy for current context.
+If you do something like `City.first.save!` you'll get an UndefinedUpdateStrategy exception instead of the object saving and index updating. This exception forces you to choose an appropriate update strategy for the current context.
 
-If you want to return behavior was before 0.7.0 - just set
-`Chewy.root_strategy = :bypass`.
+If you want to return to the pre-0.7.0 behavior - just set `Chewy.root_strategy = :bypass`.
 
 #### `:atomic`
 
-The main strategy here is `:atomic`. Assume you have to update a
-lot of records in db.
+The main strategy here is `:atomic`. Assume you have to update a lot of records in the db.
 
 ```ruby
 Chewy.strategy(:atomic) do
@@ -357,15 +419,11 @@ Chewy.strategy(:atomic) do
 end
 ```
 
-Using this strategy delays index update request until the end of
-block. Updated records are aggregated and index update happens with
-bulk API. So this strategy is highly optimized.
+Using this strategy delays the index update request until the end of the block. Updated records are aggregated and the index update happens with the bulk API. So this strategy is highly optimized.
 
 #### `:resque`
 
-Does the same thing as `:atomic`, but in async way using resque.
-Default queue name is `chewy`.
-Patch `Chewy::Strategy::Resque::Worker` for index updates improving.
+This does the same thing as `:atomic`, but asynchronously using resque. The default queue name is `chewy`. Patch `Chewy::Strategy::Resque::Worker` for index updates improving.
 
 ```ruby
 Chewy.strategy(:resque) do
@@ -375,8 +433,7 @@ end
 
 #### `:sidekiq`
 
-Does the same thing as `:atomic`, but in async way using sidekiq.
-Patch `Chewy::Strategy::Sidekiq::Worker` for index updates improving.
+This does the same thing as `:atomic`, but asynchronously using sidekiq. Patch `Chewy::Strategy::Sidekiq::Worker` for index updates improving.
 
 ```ruby
 Chewy.strategy(:sidekiq) do
@@ -384,10 +441,19 @@ Chewy.strategy(:sidekiq) do
 end
 ```
 
+#### `:active_job`
+
+This does the same thing as `:atomic`, but using ActiveJob. This will inherit the ActiveJob configuration settings including the `active_job.queue_adapter` setting for the environment. Patch `Chewy::Strategy::ActiveJob::Worker` for index updates improving.
+
+```ruby
+Chewy.strategy(:active_job) do
+  City.popular.map(&:do_some_update_action!)
+end
+```
+
 #### `:urgent`
 
-Next strategy is convenient if you are going to update documents in
-index one-by-one.
+The following strategy is convenient if you are going to update documents in your index one by one.
 
 ```ruby
 Chewy.strategy(:urgent) do
@@ -395,11 +461,9 @@ Chewy.strategy(:urgent) do
 end
 ```
 
-This code would perform `City.popular.count` requests for ES
-documents update.
+This code would perform `City.popular.count` requests for ES documents update.
 
-Seems to be convenient for usage in e.g. rails console with
-non-block notation:
+It is convenient for use in e.g. the Rails console with non-block notation:
 
 ```ruby
 > Chewy.strategy(:urgent)
@@ -408,12 +472,11 @@ non-block notation:
 
 #### `:bypass`
 
-Bypass strategy simply silences index updates.
+The bypass strategy simply silences index updates.
 
 #### Nesting
 
-Strategies are designed to allow nesting, so it is possible
-to redefine it for nested contexts.
+Strategies are designed to allow nesting, so it is possible to redefine it for nested contexts.
 
 ```ruby
 Chewy.strategy(:atomic) do
@@ -441,22 +504,19 @@ Chewy.strategy.pop
 city3.do_update! # index updated again
 ```
 
-#### Designing own strategies
+#### Designing your own strategies
 
-See [strategy/base.rb](lib/chewy/strategy/base.rb) for more details.
-See [strategy/atomic.rb](lib/chewy/strategy/atomic.rb) for example.
+See [strategy/base.rb](lib/chewy/strategy/base.rb) for more details. See [strategy/atomic.rb](lib/chewy/strategy/atomic.rb) for an example.
 
 ### Rails application strategies integration
 
-There is a couple of pre-defined strategies for your rails application. At first, rails console uses `:urgent` strategy by default, except the sandbox case. When you are running sandbox it switches to `bypass` strategy to avoid index polluting.
-
-Also migrations are wrapped with `:bypass` strategy. Because the main behavor implies that indexes are resetted after migration, so there is no need for extra index updates.
-Also indexing might be broken during migrations because of the outdated schema.
+There are a couple of predefined strategies for your Rails application. Initially, the Rails console uses the `:urgent` strategy by default, except in the sandbox case. When you are running sandbox it switches to the `:bypass` strategy to avoid polluting the index.
 
-Controller actions are wrapped with `:atomic` strategy with middleware just to reduce amount of index update requests inside actions.
+Migrations are wrapped with the `:bypass` strategy. Because the main behavior implies that indices are reset after migration, there is no need for extra index updates. Also indexing might be broken during migrations because of the outdated schema.
 
-It is also a good idea to set up `:bypass` strategy inside your test suite and import objects manually only when needed, plus use `Chewy.massacre` when needed to flush test ES indexes before every example. This will allow to minimize unnecessary ES requests and reduce overhead.
+Controller actions are wrapped with the `:atomic` strategy with middleware just to reduce the number of index update requests inside actions.
 
+It is also a good idea to set up the `:bypass` strategy inside your test suite and import objects manually only when needed, and use `Chewy.massacre` when needed to flush test ES indices before every example. This will allow you to minimize unnecessary ES requests and reduce overhead.
 
 ```ruby
 RSpec.configure do |config|
@@ -485,24 +545,20 @@ scope.only(:id, :email) # returns ids and emails only
 scope.merge(other_scope) # queries could be merged
 ```
 
-Also, queries can be performed on a type individually
+Also, queries can be performed on a type individually:
 
 ```ruby
 UsersIndex::User.filter(term: {name: 'foo'}) # will return UserIndex::User collection only
 ```
 
-If you are performing more than one `filter` or `query` in the chain,
-all the filters and queries will be concatenated in the way specified by
+If you are performing more than one `filter` or `query` in the chain, all the filters and queries will be concatenated in the way specified by
 `filter_mode` and `query_mode` respectively.
 
-Default `filter_mode` is `:and` and default `query_mode` is `bool`.
+The default `filter_mode` is `:and` and the default `query_mode` is `bool`.
 
-Available filter modes are: `:and`, `:or`, `:must`, `:should` and
-any minimum_should_match-acceptable value
+Available filter modes are: `:and`, `:or`, `:must`, `:should` and any minimum_should_match-acceptable value
 
-Available query modes are: `:must`, `:should`, `:dis_max`, any
-minimum_should_match-acceptable value or float value for dis_max
-query with tie_breaker specified.
+Available query modes are: `:must`, `:should`, `:dis_max`, any minimum_should_match-acceptable value or float value for dis_max query with tie_breaker specified.
 
 ```ruby
 UsersIndex::User.filter{ name == 'Fred' }.filter{ age < 42 } # will be wrapped with `and` filter
@@ -514,7 +570,7 @@ See [query.rb](lib/chewy/query.rb) for more details.
 
 ### Additional query action.
 
-You may also perform additional actions on query scope, such as deleting of all the scope documents:
+You may also perform additional actions on the query scope, such as deleting of all the scope documents:
 
 ```ruby
 UsersIndex.delete_all
@@ -523,17 +579,16 @@ UsersIndex.filter{ age < 42 }.delete_all
 UsersIndex::User.filter{ age < 42 }.delete_all
 ```
 
-### Filters query DSL.
+### Filters query DSL
 
-There is a test version of filters creating DSL:
+There is a test version of the filter-creating DSL:
 
 ```ruby
 UsersIndex.filter{ name == 'Fred' } # will produce `term` filter.
 UsersIndex.filter{ age <= 42 } # will produce `range` filter.
 ```
 
-The basis of the DSL is expression.
-There are 2 types of expressions:
+The basis of the DSL is the expression. There are 2 types of expressions:
 
 * Simple function
 
@@ -542,10 +597,8 @@ There are 2 types of expressions:
   UsersIndex.filter{ q(query_string: {query: 'lazy fox'}) } # query expression
   ```
 
-* Field-dependant composite expression.
-  Consists of the field name (with dot notation or not),
-  value and action operator between them. Field name might take
-  additional options for passing to the result expression.
+* Field-dependent composite expression
+  Consists of the field name (with or without dot notation), a value, and an action operator between them. The field name might take additional options for passing to the resulting expression.
 
   ```ruby
   UsersIndex.filter{ name == 'Name' } # simple field term filter
@@ -553,7 +606,7 @@ There are 2 types of expressions:
   UsersIndex.filter{ answers.title =~ /regexp/ } # regexp filter for `answers.title` field
   ```
 
-You can combine expressions as you wish with combination operators help
+You can combine expressions as you wish with the help of combination operators.
 
 ```ruby
 UsersIndex.filter{ (name == 'Name') & (email == 'Email') } # combination produces `and` filter
@@ -564,10 +617,10 @@ UsersIndex.filter{
 } # many of the combination possibilities
 ```
 
-Also, there is a special syntax for cache enabling:
+There is also a special syntax for cache enabling:
 
 ```ruby
-UsersIndex.filter{ ~name == 'Name' } # you can apply tilda to the field name
+UsersIndex.filter{ ~name == 'Name' } # you can apply tilde to the field name
 UsersIndex.filter{ ~(name == 'Name') } # or to the whole expression
 
 # if you are applying cache to the one part of range filter
@@ -806,25 +859,102 @@ See [filters.rb](lib/chewy/query/filters.rb) for more details.
 
 ### Faceting
 
-Facets are an optional sidechannel you can request from elasticsearch describing certain fields of the resulting collection. The most common use for facets is to allow the user continue filtering specifically within the subset, as opposed to the global index.
+Facets are an optional sidechannel you can request from Elasticsearch describing certain fields of the resulting collection. The most common use for facets is to allow the user to continue filtering specifically within the subset, as opposed to the global index.
 
-For instance, let's request the ```country``` field as a facet along with our users collection. We can do this with the #facets method like so:
+For instance, let's request the `country` field as a facet along with our users collection. We can do this with the #facets method like so:
 
 ```ruby
 UsersIndex.filter{ [...] }.facets({countries: {terms: {field: 'country'}}})
 ```
 
-Let's look at what we asked from elasticsearch. The facets setter method accepts a hash. You can choose custom/semantic key names for this hash for your own convinience (in this case I used the plural version of the actual field), in our case: ```countries```. The following nested hash tells ES to grab and aggregate values (terms) from the ```country``` field on our indexed records.
+Let's look at what we asked from Elasticsearch. The facets setter method accepts a hash. You can choose custom/semantic key names for this hash for your own convenience (in this case I used the plural version of the actual field), in our case `countries`. The following nested hash tells ES to grab and aggregate values (terms) from the `country` field on our indexed records.
 
-When the response comes back, it will have the ```:facets``` sidechannel included:
+The response will include the `:facets` sidechannel:
 
 ```
 < { ... ,"facets":{"countries":{"_type":"terms","missing":?,"total":?,"other":?,"terms":[{"term":"USA","count":?},{"term":"Brazil","count":?}, ...}}
 ```
 
+### Aggregations
+
+Aggregations are part of the optional sidechannel that can be requested with a query.
+
+You interact with aggregations using the composable #aggregations method (or its alias #aggs)
+
+Let's look at an example.
+
+```ruby
+class UsersIndex < Chewy::Index
+  define_type User do
+    field :name
+    field :rating
+  end
+end
+
+all_johns = UsersIndex::User.filter { name == 'john' }.aggs({ avg_rating: { avg: { field: 'rating' } } })
+
+avg_johns_rating = all_johns.aggs
+# => {"avg_rating"=>{"value"=>3.5}}
+```
+
+It is convenient to name aggregations that you intend to reuse regularly. This is achieve with the .aggregation method,
+which is also available under the .agg alias method.
+
+Here's the same example from before
+
+```ruby
+class UsersIndex < Chewy::Index
+  define_type User do
+    field :name
+    field :rating, type: "long"
+    agg :avg_rating do
+      { avg: { field: 'rating' } }
+    end
+  end
+end
+
+all_johns = UsersIndex::User.filter { name == 'john' }.aggs(:avg_rating)
+
+avg_johns_rating = all_johns.aggs
+# => {"avg_rating"=>{"value"=>3.5}}
+```
+
+It is possible to run into collisions between named aggregations. This occurs when there is more than one aggregation
+ with the same name. To explicitly reference an aggregation you provide a string to the #aggs method of the form: 
+ `index_name#document_type.aggregation_name`
+ 
+Consider this example where there are two separate aggregations named `avg_rating`
+
+```ruby
+class UsersIndex < Chewy::Index
+  define_type User do
+    field :name
+    field :rating, type: "long"
+    agg :avg_rating do
+      { avg: { field: 'rating' } }
+    end
+  end
+  define_type Post do
+    field :title
+    field :body
+    field :comments do
+      field :message
+      field :rating, type: "long"
+    end
+    agg :avg_rating do
+      { avg: { field: 'comments.rating' } }
+    end
+  end
+end
+
+all_docs = UsersIndex.filter {match_all}.aggs("users#user.avg_rating")
+all_docs.aggs
+# => {"users#user.avg_rating"=>{"value"=>3.5}} 
+```
+
 ### Script fields
 
-Script fields allow to execute elasticsearch's scripting language such as groovy, javascript and etc. More about supported languages and what is scripting [here](https://www.elastic.co/guide/en/elasticsearch/reference/0.90/modules-scripting.html). This feature allows to calculate distance between geo points, for example. This is how to use the DSL:
+Script fields allow you to execute Elasticsearch's scripting languages such as groovy and javascript. More about supported languages and what scripting is [here](https://www.elastic.co/guide/en/elasticsearch/reference/0.90/modules-scripting.html). This feature allows you to calculate the distance between geo points, for example. This is how to use the DSL:
 
 ```ruby
 UsersIndex.script_fields(
@@ -837,7 +967,7 @@ UsersIndex.script_fields(
   }
 )
 ```
-`coordinates` here is a field with `geo_point` type. There will be `distance` field for the index's model in the search result.
+Here, `coordinates` is a field with type `geo_point`. There will be a `distance` field for the index's model in the search result.
 
 ### Script scoring
 
@@ -849,7 +979,7 @@ UsersIndex.script_score("_score * doc['my_numeric_field'].value")
 
 ### Boost Factor
 
-Boost factors are a way to add a boost to a query where documents match the filter. If you have some users who are experts and some are regular users, you might want to give the experts a higher score and boost to the top of the search results. You can accomplish this by using the #boost_factor method and adding a boost score for an expert user of 5:
+Boost factors are a way to add a boost to a query where documents match the filter. If you have some users who are experts and some who are regular users, you might want to give the experts a higher score and boost to the top of the search results. You can accomplish this by using the #boost_factor method and adding a boost score of 5 for an expert user:
 
 ```ruby
 UsersIndex.boost_factor(5, filter: {term: {type: 'Expert'}})
@@ -857,7 +987,7 @@ UsersIndex.boost_factor(5, filter: {term: {type: 'Expert'}})
 
 ### Objects loading
 
-It is possible to load source objects from database for every search result:
+It is possible to load source objects from the database for every search result:
 
 ```ruby
 scope = UsersIndex.filter(range: {rating: {gte: 100}})
@@ -872,7 +1002,7 @@ scope.load(scope: ->{ includes(:country) }) # and more common scope applied to e
 scope.only(:id).load # it is optimal to request ids only if you are not planning to use type objects
 ```
 
-The `preload` method takes the same options as `load` and ORM/ODM objects will be loaded, but scope will still return array of Chewy wrappers. To access real objects use `_object` wrapper method:
+The `preload` method takes the same options as `load` and ORM/ODM objects will be loaded, but the scope will still return an array of Chewy wrappers. To access real objects use the `_object` wrapper method:
 
 ```ruby
 UsersIndex.filter(range: {rating: {gte: 100}}).preload(...).query(...).map(&:_object)
@@ -882,7 +1012,7 @@ See [loading.rb](lib/chewy/query/loading.rb) for more details.
 
 ### `ActiveSupport::Notifications` support
 
-Chewy has notifing the following events:
+Chewy has notifying the following events:
 
 #### `search_query.chewy` payload
 
@@ -892,7 +1022,7 @@ Chewy has notifing the following events:
 #### `import_objects.chewy` payload
 
   * `payload[:type]`: currently imported type
-  * `payload[:import]`: imports stast, total imported and deleted objects count:
+  * `payload[:import]`: imports stats, total imported and deleted objects count:
 
     ```ruby
     {index: 30, delete: 5}
@@ -941,25 +1071,24 @@ end
 
 ### Rake tasks
 
-Inside Rails application some index mantaining rake tasks are defined.
+Inside the Rails application, some index-maintaining rake tasks are defined.
 
 ```bash
-rake chewy:reset # resets all the existing indexes, declared in app/chewy
+rake chewy:reset # resets all the existing indices, declared in app/chewy
 rake chewy:reset[users] # resets UsersIndex only
 
-rake chewy:update # updates all the existing indexes, declared in app/chewy
+rake chewy:update # updates all the existing indices, declared in app/chewy
 rake chewy:update[users] # updates UsersIndex only
 ```
 
-Also `rake chewy:reset` performs zero-downtime reindexing as described here: https://www.elastic.co/blog/changing-mapping-with-zero-downtime. So basically rake task creates new index with uniq suffix and then simply aliases it to the common index name. Previous index is deleted afterwards (see `Chewy::Index.reset!` for more details).
+`rake chewy:reset` performs zero-downtime reindexing as described [here](https://www.elastic.co/blog/changing-mapping-with-zero-downtime). So basically rake task creates a new index with uniq suffix and then simply aliases it to the common index name. The previous index is deleted afterwards (see `Chewy::Index.reset!` for more details).
 
 
 ### Rspec integration
 
-Just add `require 'chewy/rspec'` to your spec_helper.rb and you will get additional features:
-See [update_index.rb](lib/chewy/rspec/update_index.rb) for more details.
+Just add `require 'chewy/rspec'` to your spec_helper.rb and you will get additional features: See [update_index.rb](lib/chewy/rspec/update_index.rb) for more details.
 
-If you use `DatabaseCleaner` in your tests with `transaction` (strategy)[https://github.com/DatabaseCleaner/database_cleaner#how-to-use] you may run into the problem that `ActiveRecord`'s models are not indexed automatically on save them despite of the fact that you set the callbacks to do this with the `update_index` method. The issue arises because `chewy` indexes data on `after_commit` run as default but all `after_commit` callbacks are not run with the `DatabaseCleaner`'s' `transaction` strategy. You can solve the issue by changing the `Chewy.use_after_commit_callbacks` option. Just add the following initializer in your Rails application:
+If you use `DatabaseCleaner` in your tests with [the `transaction` strategy](https://github.com/DatabaseCleaner/database_cleaner#how-to-use), you may run into the problem that `ActiveRecord`'s models are not indexed automatically on save despite the fact that you set the callbacks to do this with the `update_index` method. The issue arises because `chewy` indexes data on `after_commit` run as default, but all `after_commit` callbacks are not run with the `DatabaseCleaner`'s' `transaction` strategy. You can solve this issue by changing the `Chewy.use_after_commit_callbacks` option. Just add the following initializer in your Rails application:
 
 ```ruby
 #config/initializers/chewy.rb
@@ -969,20 +1098,20 @@ Chewy.use_after_commit_callbacks = !Rails.env.test?
 ## TODO a.k.a coming soon:
 
 * Typecasting support
-* Advanced (simplyfied) query DSL: `UsersIndex.query { email == 'my@gmail.com' }` will produce term query
+* Advanced (simplified) query DSL: `UsersIndex.query { email == 'my@gmail.com' }` will produce term query
 * update_all support
 * Maybe, closer ORM/ODM integration, creating index classes implicitly
 
 ## Contributing
 
-1. Fork it ( http://github.com/toptal/chewy/fork )
+1. Fork it (http://github.com/toptal/chewy/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Implement your changes, cover it with specs and make sure old specs are passing
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create new Pull Request
 
-Use the following Rake tasks to control ElasticSearch cluster while developing.
+Use the following Rake tasks to control the Elasticsearch cluster while developing.
 
 ```bash
 rake elasticsearch:start # start Elasticsearch cluster on 9250 port for tests