chewy 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 1731bb408069ab82feb6979f9f70008a0977cb48
-  data.tar.gz: b676bfdc501aece147b1af8a915f99defd0f2eaa
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzNiZmUxMGUxNzE1ODdkYzQzYTAyMzAwN2VhNDhmZDkzYzUyMDZhNQ==
+  data.tar.gz: !binary |-
+    MWIwNDA3MzMyNzRlZGM2ODllODA4ZjAxMzI0NzM5OTc3MGU4NjViMA==
 SHA512:
-  metadata.gz: 7ce0646699822d696680438f2be44d12b4a9829470362e841e357e059759474c4a54fdbed4c4b5ec6946b2d50800fd7e8be3a3f31d33e7ac987705fb5622266c
-  data.tar.gz: 5ede42795877994577c4aac44c5898dd7abacc7d922db0a1563b0e5e1564d8c02fec987eb4f01014f7fc46c4c20811aab5cc4f17280d734be6f7f5ba73fa8c0f
+  metadata.gz: !binary |-
+    MDk1NWIzZmYzYmZhNjkzOTI0OTY0MWVkYjYzNDE2N2FiZGUzOGQ1YjI0NzQ4
+    OTgzMTgyNDI2M2RlMjJhMWQzMjk1MzZjOGFkODQ3NzFjZmEwOTQ2M2UzNDMy
+    MDJjY2Y0ZmFiZjU5NjY3MTE5MzQ3NDk0ZDg4MzdjZDJkOTZhNGI=
+  data.tar.gz: !binary |-
+    NWEyODY1M2JhZjEwMDI1MTUyNGQ1NzM4ZTU0NTgyYWRkOWM3NWI0ZmQ2ZmY1
+    ODkyMjc5OTQwNThlODA2YjY3MGM5MTQyZDA5NzMzZDBjOWYyYmI2NmMyNGQx
+    OTU3ZGM3OTEyOGJjMWIyMmEwYWY2MjkzOGJmM2Q3MzQ2MzgzMGE=

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.rvmrc

data/.travis.yml

@@ -2,6 +2,8 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
-  - rbx
-services:
-  - elasticsearch
+  # - rbx
+before_install:
+  - curl -# https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-0.90.9.tar.gz | tar xz -C /tmp
+before_script:
+  - TEST_CLUSTER_COMMAND="/tmp/elasticsearch-0.90.9/bin/elasticsearch" rake elasticsearch:start

data/CHANGELOG.md

@@ -0,0 +1,75 @@
+# master
+
+# Version 0.1.0
+
+  * Added filters simplified DSL. See [context.rb](lib/chewy/query/context.rb) for more info.
+
+  * Queries and filters join system reworked. See [query.rb](lib/chewy/query.rb) for more info.
+
+  * Added query `merge` method
+
+  * `update_index` matcher now wraps expected block in `Chewy.atomic` by default.
+    This behaviour can be prevented with `atomic: false` option passing
+
+    ```ruby
+      expect { user.save! }.to update_index('users#user', atomic: false)
+    ```
+
+  * Renamed `Chewy.observing_enabled` to `Chewy.urgent_update` with `false` as default
+
+  * `update_elasticsearch` renamed to `update_index`, added `update_index`
+    `:urgent` option
+
+  * Added import ActiveSupport::Notifications instrumentation
+    `ActiveSupport::Notifications.subscribe('import_objects.chewy') { |*args| }`
+
+  * Added `types!` and `only!` query chain methods, which purges previously
+    chained types and fields
+
+  * `types` chain method now uses types filter
+
+  * Added `types` query chain method
+
+  * Changed types access API:
+
+    ```ruby
+      UsersIndex::User # => UsersIndex::User
+      UsersIndex::types_hash['user'] # => UsersIndex::User
+      UsersIndex.user # => UsersIndex::User
+      UsersIndex.types # => [UsersIndex::User]
+      UsersIndex.type_names # => ['user']
+    ```
+
+  * `update_elasticsearch` method name as the second argument
+
+    ```ruby
+      update_elasticsearch('users#user', :self)
+      update_elasticsearch('users#user', :users)
+    ```
+
+  * Changed index handle methods, removed `index_` prefix. I.e. was
+    `UsersIndex.index_create`, became `UsersIndex.create`
+
+  * Ability to pass value proc for source object context if arity == 0
+    `field :full_name, value: ->{ first_name + last_name }` instead of
+    `field :full_name, value: ->(u){ u.first_name + u.last_name }`
+
+  * Added `.only` chain to `update_index` matcher
+
+  * Added ability to pass ActiveRecord::Relation as a scope for load
+    `CitiesIndex.all.load(scope: {city: City.include(:country)})`
+
+  * Added method `all` to index for query DSL consistency
+
+  * Implemented isolated adapters to simplify adding new ORMs
+
+  * Query DLS chainable methods delegated to index class
+    (no longer need to call MyIndex.search.query, just MyIndex.query)
+
+# Version 0.0.1
+
+  * Query dsl
+
+  * Basic index hadling
+
+  * Initial version

data/README.md

@@ -1,3 +1,6 @@
+[![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)
+
 # Chewy
 
 Chewy is ODM and wrapper for official elasticsearch client (https://github.com/elasticsearch/elasticsearch-ruby)
@@ -23,17 +26,17 @@ Or install it yourself as:
 1. Create `/app/chewy/users_index.rb`
 
   ```ruby
-    class UsersIndex < Chewy::Index
+  class UsersIndex < Chewy::Index
 
-    end
+  end
   ```
 
 2. Add one or more types mapping
 
   ```ruby
-    class UsersIndex < Chewy::Index
-      define_type User.active # or just model instead_of scope: define_type User
-    end
+  class UsersIndex < Chewy::Index
+    define_type User.active # or just model instead_of scope: define_type User
+  end
   ```
 
   Newly-defined index type class is accessible via `UsersIndex.user` or `UsersIndex::User`
@@ -41,20 +44,21 @@ Or install it yourself as:
 3. Add some type mappings
 
   ```ruby
-    class UsersIndex < Chewy::Index
-      define_type User.active.includes(:country, :bages, :projects) do
-        field :first_name, :last_name # multiple fields without additional options
-        field :email, analyzer: 'email' # elasticsearch-related options
-        field :country, value: ->(user) { user.country.name } # custom value proc
-        field :bages, value: ->(user) { user.bages.map(&:name) } # passing array values to index
-        field :projects, type: 'object' do # the same syntax for `multi_field`
-          field :title
-          field :description # default data type is `string`
-        end
-        field :rating, type: 'integer' # custom data type
-        field :created_at, type: 'date', include_in_all: false
+  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 :country, value: ->(user) { user.country.name } # custom value proc
+      field :badges, value: ->(user) { user.badges.map(&:name) } # passing array values to index
+      field :projects, type: 'object' do # the same syntax for `multi_field`
+        field :title
+        field :description # default data type is `string`
       end
+      field :rating, type: 'integer' # custom data type
+      field :created, type: 'date', include_in_all: false,
+        value: ->{ created_at } # value proc for source object context
     end
+  end
   ```
 
   Mapping definitions - http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping.html
@@ -62,32 +66,33 @@ Or install it yourself as:
 4. Add some index- and type-related settings
 
   ```ruby
-    class UsersIndex < Chewy::Index
-      settings analysis: {
-        analyzer: {
-          email: {
-            tokenizer: 'keyword',
-            filter: ['lowercase']
-          }
+  class UsersIndex < Chewy::Index
+    settings analysis: {
+      analyzer: {
+        email: {
+          tokenizer: 'keyword',
+          filter: ['lowercase']
         }
       }
-
-      define_type User.active.includes(:country, :bages, :projects) do
-        root _boost: { name: :_boost, null_value: 1.0 } do # optional `root` object settings
-          field :first_name, :last_name # multiple fields without additional options
-          field :email, analyzer: 'email' # elasticsearch-related options
-          field :country, value: ->(user) { user.country.name } # custom value proc
-          field :bages, value: ->(user) { user.bages.map(&:name) } # passing array values to index
-          field :projects, type: 'object' do # the same syntax for `multi_field`
-            field :title
-            field :description # default data type is `string`
-          end
-          field :about_translations, type: 'object'
-          field :rating, type: 'integer' # custom data type
-          field :created_at, type: 'date', include_in_all: false
+    }
+
+    define_type User.active.includes(:country, :badges, :projects) do
+      root _boost: { name: :_boost, null_value: 1.0 } do
+        field :first_name, :last_name
+        field :email, analyzer: 'email'
+        field :country, value: ->(user) { user.country.name }
+        field :badges, value: ->(user) { user.badges.map(&:name) }
+        field :projects, type: 'object' do
+          field :title
+          field :description
         end
+        field :about_translations, type: 'object'
+        field :rating, type: 'integer'
+        field :created, type: 'date', include_in_all: false,
+          value: ->{ created_at }
       end
     end
+  end
   ```
 
   Index settings - http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-update-settings.html
@@ -96,95 +101,486 @@ Or install it yourself as:
 5. Add model observing code
 
   ```ruby
-    class User < ActiveRecord::Base
-      update_elasticsearch('users#user') { self } # specifying index, type and backreference
-                                                  # for updating after user save or destroy
-    end
+  class User < ActiveRecord::Base
+    update_index('users#user') { self } # specifying index, type and backreference
+                                        # for updating after user save or destroy
+  end
 
-    class Country < ActiveRecord::Base
-      has_many :users
+  class Country < ActiveRecord::Base
+    has_many :users
 
-      update_elasticsearch('users#user') { users } # return single object or collection
-    end
+    update_index('users#user') { users } # return single object or collection
+  end
 
-    class Project < ActiveRecord::Base
-      update_elasticsearch('users#user') { user if user.active? } # you can return even `nil` from the backreference
-    end
+  class Project < ActiveRecord::Base
+    update_index('users#user') { user if user.active? } # you can return even `nil` from the backreference
+  end
 
-    class Bage < ActiveRecord::Base
-      has_and_belongs_to_many :users
+  class Bage < ActiveRecord::Base
+    has_and_belongs_to_many :users
 
-      update_elasticsearch('users') { users } # if index has only one type
-                                              # there is no need to specify updated type
-    end
+    update_index('users') { users } # if index has only one type
+                                    # there is no need to specify updated type
+  end
   ```
 
+  Also, you can use second argument for method name passing:
+
+  ```ruby
+  update_index('users#user', :self)
+  update_index('users#user', :users)
+  ```
+
+### Types access
+
+You are able to access index-defined types with the following API:
+
+```ruby
+UsersIndex::User # => UsersIndex::User
+UsersIndex.types_hash['user'] # => UsersIndex::User
+UsersIndex.user # => UsersIndex::User
+UsersIndex.types # => [UsersIndex::User]
+UsersIndex.type_names # => ['user']
+```
+
 ### Index manipulation
 
 ```ruby
-  UsersIndex.index_delete # destroy index if exists
-  UsersIndex.index_create! # use bang or non-bang methods
-  UsersIndex.import # import with 0 arguments process all the data specified in type definition
-                    # literally, User.active.includes(:country, :bages, :projects).find_in_batches
+UsersIndex.delete # destroy index if exists
+UsersIndex.delete!
 
-  UsersIndex.import User.where('rating > 100') # or import specified users
-  UsersIndex.import [1, 2, 42] # pass even ids for import, it will be handled in the most effective way
+UsersIndex.create
+UsersIndex.create! # use bang or non-bang methods
+
+UsersIndex.purge
+UsersIndex.purge! # deletes then creates index
+
+UsersIndex::User.import # import with 0 arguments process all the data specified in type definition
+                        # literally, User.active.includes(:country, :badges, :projects).find_in_batches
+UsersIndex::User.import User.where('rating > 100') # or import specified users scope
+UsersIndex::User.import User.where('rating > 100').to_a # or import specified users array
+UsersIndex::User.import [1, 2, 42] # pass even ids for import, it will be handled in the most effective way
+
+UsersIndex.import # import every defined type
+UsersIndex.reset # purges index and imports default data for all types
 ```
 
 Also if passed user is #destroyed? or specified id is not existing in the database, import will perform `delete` index for this it
 
 ### Observing strategies
 
-There are 2 strategies for index updating: updating right after save and cummulative update. The first is by default. To perform the second one, use `Chewy.atomic`:
+There are 3 strategies for index updating: do not update index at all, update right after save and cummulative update. The first is by default.
+
+#### Updating index on-demand
+
+By default Chewy indexes are not updated when the observed model is saved or destroyed.
+This depends on the `Chewy.urgent_update` (false by default) or on the per-model update config.
+If you will perform `Chewy.urgent_update = true`, all the models will start to update elasticsearch
+index right after save. Also
 
 ```ruby
-  Chewy.atomic do
-    user.each { |user| user.update_attributes(name: user.name.strip) }
-  end
+class User < ActiveRecord::Base
+  update_index 'users#user', 'self', urgent: true
+end
 ```
 
-Index update will be performed once per Chewy.atomic block. This strategy is highly usable for rails actions:
+will make the same effect for User model only.
+Note than urgent update options affects only outside-atomic-block behavour. Inside
+the `Chewy.atomic { }` block indexes updates as described below.
+
+#### Using atomic updates
+
+To perform atomic cummulative updates, use `Chewy.atomic`:
 
 ```ruby
-  class ApplicationController < ActionController::Base
-    around_action { |&block| Chewy.atomic(&block) }
-  end
+Chewy.atomic do
+  user.each { |user| user.update_attributes(name: user.name.strip) }
+end
+```
+
+Index update will be performed once per Chewy.atomic block for every affected type.
+This strategy is highly usable for rails actions:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action { |&block| Chewy.atomic(&block) }
+end
 ```
 
+Also atomic blocks might be nested and don't affect each other.
+
 ### Index querying
 
 ```ruby
-  scope = UsersIndex.search.query(term: {name: 'foo'})
-    .filter({numeric_range: {rating: {gte: 100}}})
-    .order(created_at: :desc)
-    .limit(20).offset(100)
-
-  scope.to_a # => will produce array of UserIndex::User or other types instances
-  scope.map { |user| user.email }
-  scope.total_count # => will return total objects count
-
-  scope.per(10).page(3) # supports kaminari pagination
-  scope.explain.map { |user| user._explanation }
-  scope.only(:id, :email) # returns ids and emails only
+scope = UsersIndex.query(term: {name: 'foo'})
+  .filter(range: {rating: {gte: 100}})
+  .order(created: :desc)
+  .limit(20).offset(100)
+
+scope.to_a # => will produce array of UserIndex::User or other types instances
+scope.map { |user| user.email }
+scope.total_count # => will return total objects count
+
+scope.per(10).page(3) # supports kaminari pagination
+scope.explain.map { |user| user._explanation }
+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
 
 ```ruby
-  UsersIndex.search.query(term: {name: 'foo'}).count # will return UserIndex::User array only
+UsersIndex::User.filter(term: {name: 'foo'}) # will return UserIndex::User collection only
+```
+
+If you are performing more then 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`.
+
+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.
+
+```ruby
+UsersIndex::User.filter{ name == 'Fred' }.filter{ age < 42 } # will be wrapped with `and` filter
+UsersIndex::User.filter{ name == 'Fred' }.filter{ age < 42 }.filter_mode(:should) # will be wrapped with bool `should` filter
+UsersIndex::User.filter{ name == 'Fred' }.filter{ age < 42 }.filter_mode('75%') # will be wrapped with bool `should` filter with `minimum_should_match: '75%'`
+```
+
+See [query.rb](lib/chewy/query.rb) for more info.
+
+### Filters query DSL.
+
+There is a test version of filters 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:
+
+* Simple function
+
+  ```ruby
+  UsersIndex.filter{ s('doc["num"] > 1') } # script expression
+  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.
+
+  ```ruby
+  UsersIndex.filter{ name == 'Name' } # simple field term filter
+  UsersIndex.filter{ name(:bool) == ['Name1', 'Name2'] } # terms query with `execution: :bool` option passed
+  UsersIndex.filter{ answers.title =~ /regexp/ } # regexp filter for `answers.title` field
+  ```
+
+You can combine expressions as you wish with combination operators help
+
+```ruby
+UsersIndex.filter{ (name == 'Name') & (email == 'Email') } # combination produces `and` filter
+UsersIndex.filter{
+  must(
+    should(name =~ 'Fr').should_not(name == 'Fred') & (age == 42), email =~ /gmail\.com/
+  ) | ((roles.admin == true) & name?)
+} # many of the combination possibilities
+```
+
+Also, there is a special syntax for cache enabling:
+
+```ruby
+UsersIndex.filter{ ~name == 'Name' } # you can apply tilda 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
+# the whole filter will be cached:
+UsersIndex.filter{ ~(age > 42) & (age <= 50) }
+
+# You can pass cache options as a field option also.
+UsersIndex.filter{ name(cache: true) == 'Name' }
+UsersIndex.filter{ name(cache: false) == 'Name' }
+
+# With regexp filter you can pass _cache_key
+UsersIndex.filter{ name(cache: 'name_regexp') =~ /Name/ }
+# Or not
+UsersIndex.filter{ name(cache: true) =~ /Name/ }
+```
+
+Compliance cheatsheet for filters and DSL expressions:
+
+* Term filter
+
+  ```json
+  {"term": {"name": "Fred"}}
+  {"not": {"term": {"name": "Johny"}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ name == 'Fred' }
+  UsersIndex.filter{ name != 'Johny' }
+  ```
+
+* Terms filter
+
+  ```json
+  {"terms": {"name": ["Fred", "Johny"]}}
+  {"not": {"terms": {"name": ["Fred", "Johny"]}}}
+
+  {"terms": {"name": ["Fred", "Johny"], "execution": "or"}}
+
+  {"terms": {"name": ["Fred", "Johny"], "execution": "and"}}
+
+  {"terms": {"name": ["Fred", "Johny"], "execution": "bool"}}
+
+  {"terms": {"name": ["Fred", "Johny"], "execution": "fielddata"}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ name == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name != ['Fred', 'Johny'] }
+
+  UsersIndex.filter{ name(:|) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(:or) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(execution: :or) == ['Fred', 'Johny'] }
+
+  UsersIndex.filter{ name(:&) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(:and) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(execution: :and) == ['Fred', 'Johny'] }
+
+  UsersIndex.filter{ name(:b) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(:bool) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(execution: :bool) == ['Fred', 'Johny'] }
+
+  UsersIndex.filter{ name(:f) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(:fielddata) == ['Fred', 'Johny'] }
+  UsersIndex.filter{ name(execution: :fielddata) == ['Fred', 'Johny'] }
+  ```
+
+* Regexp filter (== and =~ are equivalent)
+
+  ```json
+  {"regexp": {"name.first": "s.*y"}}
+
+  {"not": {"regexp": {"name.first": "s.*y"}}}
+
+  {"regexp": {"name.first": {"value": "s.*y", "flags": "ANYSTRING|INTERSECTION"}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ name.first == /s.*y/ }
+  UsersIndex.filter{ name.first =~ /s.*y/ }
+
+  UsersIndex.filter{ name.first != /s.*y/ }
+  UsersIndex.filter{ name.first !~ /s.*y/ }
+
+  UsersIndex.filter{ name.first(:anystring, :intersection) == /s.*y/ }
+  UsersIndex.filter{ name.first(flags: [:anystring, :intersection]) == /s.*y/ }
+  ```
+
+* Prefix filter
+
+  ```json
+  {"prefix": {"name": "Fre"}}
+  {"not": {"prefix": {"name": "Joh"}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ name =~ re' }
+  UsersIndex.filter{ name !~ 'Joh' }
+  ```
+
+* Exists filter
+
+  ```json
+  {"exists": {"field": "name"}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ name? }
+  UsersIndex.filter{ !!name }
+  UsersIndex.filter{ !!name? }
+  UsersIndex.filter{ name != nil }
+  UsersIndex.filter{ !(name == nil) }
+  ```
+
+* Missing filter
+
+  ```json
+  {"missing": {"field": "name", "existence": true, "null_value": false}}
+  {"missing": {"field": "name", "existence": true, "null_value": true}}
+  {"missing": {"field": "name", "existence": false, "null_value": true}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ !name }
+  UsersIndex.filter{ !name? }
+  UsersIndex.filter{ name == nil }
+  ```
+
+* Range
+
+  ```json
+  {"range": {"age": {"gt": 42}}}
+  {"range": {"age": {"gte": 42}}}
+  {"range": {"age": {"lt": 42}}}
+  {"range": {"age": {"lte": 42}}}
+
+  {"range": {"age": {"gt": 40, "lt": 50}}}
+  {"range": {"age": {"gte": 40, "lte": 50}}}
+
+  {"range": {"age": {"gt": 40, "lte": 50}}}
+  {"range": {"age": {"gte": 40, "lt": 50}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ age > 42 }
+  UsersIndex.filter{ age >= 42 }
+  UsersIndex.filter{ age < 42 }
+  UsersIndex.filter{ age <= 42 }
+
+  UsersIndex.filter{ age == (40..50) }
+  UsersIndex.filter{ (age > 40) & (age < 50) }
+  UsersIndex.filter{ age == [40..50] }
+  UsersIndex.filter{ (age >= 40) & (age <= 50) }
+
+  UsersIndex.filter{ (age > 40) & (age <= 50) }
+  UsersIndex.filter{ (age >= 40) & (age < 50) }
+  ```
+
+* Bool filter
+
+  ```json
+  {"bool": {
+    "must": [{"term": {"name": "Name"}}],
+    "should": [{"term": {"age": 42}}, {"term": {"age": 45}}]
+  }}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ must(name == 'Name').should(age == 42, age == 45) }
+  ```
+
+* And filter
+
+  ```json
+  {"and": [{"term": {"name": "Name"}}, {"range": {"age": {"lt": 42}}}]}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ (name == 'Name') & (age < 42) }
+  ```
+
+* Or filter
+
+  ```json
+  {"or": [{"term": {"name": "Name"}}, {"range": {"age": {"lt": 42}}}]}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ (name == 'Name') | (age < 42) }
+  ```
+
+  ```json
+  {"not": {"term": {"name": "Name"}}}
+  {"not": {"range": {"age": {"lt": 42}}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ !(name == 'Name') } # or UsersIndex.filter{ name != 'Name' }
+  UsersIndex.filter{ !(age < 42) }
+  ```
+
+See [context.rb](lib/chewy/query/context.rb) for more info.
+
 ### Objects loading
 
 It is possible to load source objects from database for every search result:
 
 ```ruby
-  scope = UsersIndex.search.filter({numeric_range: {rating: {gte: 100}}})
+scope = UsersIndex.filter(range: {rating: {gte: 100}})
+
+scope.load # => will return User instances array (not a scope because )
+scope.load(user: { scope: ->(_) { includes(:country) }}) # you can also pass loading scopes for each
+                                                         # possibly returned type
+scope.load(user: { scope: User.includes(:country) }) # the second scope passing way
+scope.only(:id).load # it is optimal to request ids only if you are not planning to use type objects
+```
+
+### Rake tasks
 
-  scope.load # => will return User instances array (not a scope because )
-  scope.load(scopes: { user: ->(_) { includes(:country) }}) # => you can also pass loading scopes for each
-                                                            # possibly returned type
-  scope.only(:id).load # it is optimal to request ids only if you are not planning to use type objects
+Inside Rails application some index mantaining rake tasks are defined.
+
+```bash
+rake chewy:reset:all # resets all the existing indexes, declared in app/chewy
+rake chewy:reset[users] # resets UsersIndex
+rake chewy:update[users] # updates UsersIndex
+```
+
+### Rspec integration
+
+Just add `require 'chewy/rspec'` to your spec_helper.rb and you will get additional features:
+
+#### `update_index` matcher
+
+```ruby
+# just update index expectation. Used type class as argument.
+specify { expect { user.save! }.to update_index(UsersIndex.user) }
+# expect do not update target index. Type for `update_index` might be specified via string also
+specify { expect { user.name = 'Duke' }.not_to update_index('users#user') }
+# expecting update specified objects
+specify { expect { user.save! }.to update_index(UsersIndex.user).and_reindex(user) }
+# you can specify even id
+specify { expect { user.save! }.to update_index(UsersIndex.user).and_reindex(42) }
+# expected multiple objects to be reindexed
+specify { expect { [user1, user2].map(&:save!) }
+  .to update_index(UsersIndex.user).and_reindex(user1, user2) }
+specify { expect { [user1, user2].map(&:save!) }
+  .to update_index(UsersIndex.user).and_reindex(user1).and_reindex(user2) }
+# expect object to be reindexed exact twice
+specify { expect { 2.times { user.save! } }
+  .to update_index(UsersIndex.user).and_reindex(user, times: 2) }
+# expect object in index to be updated with specified fields
+specify { expect { user.update_attributes!(name: 'Duke') }
+  .to update_index(UsersIndex.user).and_reindex(user, with: {name: 'Duke'}) }
+# combination of previous two
+specify { expect { 2.times { user.update_attributes!(name: 'Duke') } }
+  .to update_index(UsersIndex.user).and_reindex(user, times: 2, with: {name: 'Duke'}) }
+# for every object
+specify { expect { 2.times { [user1, user2].map { |u| u.update_attributes!(name: 'Duke') } } }
+  .to update_index(UsersIndex.user).and_reindex(user1, user2, times: 2, with: {name: 'Duke'}) }
+# for every object splitted
+specify { expect { 2.times { [user1, user2].map { |u| u.update_attributes!(name: "Duke#{u.id}") } } }
+  .to update_index(UsersIndex.user)
+    .and_reindex(user1, with: {name: 'Duke42'}) }
+    .and_reindex(user2, times: 1, with: {name: 'Duke43'}) }
+# object deletion same abilities as `and_reindex`, except `:with` option
+specify { expect { user.destroy! }.to update_index(UsersIndex.user).and_delete(user) }
+# double deletion, whatever it means
+specify { expect { 2.times { user.destroy! } }.to update_index(UsersIndex.user).and_delete(user, times: 2) }
+# alltogether
+specify { expect { user1.destroy!; user2.save! } }
+  .to update_index(UsersIndex.user).and_reindex(user2).and_delete(user1)
+```
+
+```ruby
+# strictly specifing updated and deleted records
+specify { expect { [user1, user2].map(&:save!) }
+  .to update_index(UsersIndex.user).and_reindex(user1, user2).only }
+specify { expect { [user1, user2].map(&:destroy!) }
+  .to update_index(UsersIndex.user).and_delete(user1, user2).only }
+# this will fail
+specify { expect { [user1, user2].map(&:save!) }
+  .to update_index(UsersIndex.user).and_reindex(user1).only }
 ```
 
 ## TODO a.k.a coming soon:
@@ -192,8 +588,6 @@ It is possible to load source objects from database for every search result:
 * Dynamic templates additional DSL
 * Typecasting support
 * Advanced (simplyfied) query DSL: `UsersIndex.query { email == 'my@gmail.com' }` will produce term query
-* Remove Index.search method, all the query DSL methods should be delegated to the Index
-* Observing strategies reworking
 * update_all support
 * Other than ActiveRecord ORMs support (Mongoid)
 * Maybe, closer ORM/ODM integration, creating index classes implicitly
@@ -201,8 +595,9 @@ It is possible to load source objects from database for every search result:
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/chewy/fork )
+1. Fork it ( http://github.com/toptal/chewy/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+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