chewy 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de7c5c4e672dfb909540467bf37a13aaa21933c1
-  data.tar.gz: 1e6a424a74805c9e19495f9c2d33a1e16cd0a843
+  metadata.gz: d7aa20726080ec98870f97d0c0ef730a3eb7bc4f
+  data.tar.gz: 66b15afd916e7ed479bf7e9bacc3286a9ce9dc25
 SHA512:
-  metadata.gz: 9a7b5152aa2def448318b81b1fbac395ad652620c079c8013332e5e44ffebcfb27932688d81b7116f95447e37ebe715630307bf45e010f6964ff12a618a97d97
-  data.tar.gz: 370c365d9d690e29e5ab7de4ba06f0dff07aa360edbb7f18c982bf2c6f288b1bdd7554bb8bc569993d82553c696e44c3c726ab5c11db278b1d6fcc4c472b4998
+  metadata.gz: 5800f28ff7480f5c7052c5860a5b3f3e6547ebee02e88f82d59e4aa2df6764d3330ee5c00ee3b36cff26c74ebec5d3713641868618d465718c6c615bae12ef85
+  data.tar.gz: eb17d5fa79ec63472fdb0adac109d8612af6a9693bcda2afe05efe20f32b9d221933403049ba27731a9410752e6c955e522fceab4e7d6c372b38b64f21d87708

data/.gitignore

@@ -19,3 +19,4 @@ tmp
 .rvmrc
 _site
 .sass-cache
+file::memory:?cache=shared

data/.rubocop.yml

@@ -1,7 +1,10 @@
 inherit_from: .rubocop_todo.yml
 
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
 Lint/EndAlignment:
-  AlignWith: variable
+  EnforcedStyleAlignWith: variable
 
 Style/AccessModifierIndentation:
   EnforcedStyle: outdent
@@ -19,7 +22,7 @@ Style/AndOr:
   EnforcedStyle: conditionals
 
 Style/CaseIndentation:
-  IndentWhenRelativeTo: end
+  EnforcedStyle: end
 
 Style/DoubleNegation:
   Enabled: false
@@ -27,8 +30,27 @@ Style/DoubleNegation:
 Style/IndentArray:
   EnforcedStyle: consistent
 
+Style/IndentHash:
+  EnforcedStyle: consistent
+
+Style/IndentHeredoc:
+  Enabled: false
+
 Style/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
 Style/MultilineOperationIndentation:
   EnforcedStyle: indented
+
+Style/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Metrics/BlockLength:
+  Exclude:
+    - '**/*_spec.rb'
+    - '**/*_examples.rb'
+    - '**/*.rake'
+
+Metrics/ModuleLength:
+  Exclude:
+    - '**/*_spec.rb'

data/.rubocop_todo.yml

@@ -13,7 +13,7 @@ Metrics/AbcSize:
 # Offense count: 4
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 280
+  Max: 300
 
 # Offense count: 14
 Metrics/CyclomaticComplexity:
@@ -33,7 +33,7 @@ Metrics/MethodLength:
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ModuleLength:
-  Max: 172
+  Max: 180
 
 # Offense count: 14
 Metrics/PerceivedComplexity:

data/.travis.yml

@@ -2,35 +2,52 @@ language: ruby
 sudo: false
 services:
   - mongodb
+jdk:
+  - oraclejdk8
 rvm:
-  - 2.2.5
-  - 2.3.1
+  - 2.2.7
+  - 2.3.4
+  - 2.4.1
+env:
+  global:
+    - TEST_CLUSTER_NODES=1
+  matrix:
+    - ES_VERSION=2.4.4
+    - ES_VERSION=5.4.0
 gemfile:
+  - gemfiles/rails.4.0.activerecord.gemfile
+  - gemfiles/rails.4.1.activerecord.gemfile
   - gemfiles/rails.4.2.activerecord.gemfile
-  - gemfiles/rails.4.2.activerecord.kaminari.gemfile
-  - gemfiles/rails.4.2.activerecord.will_paginate.gemfile
   - gemfiles/rails.5.0.activerecord.gemfile
-  - gemfiles/rails.5.0.activerecord.kaminari.gemfile
-  - gemfiles/rails.5.0.activerecord.will_paginate.gemfile
-  - gemfiles/rails.4.2.mongoid.4.0.gemfile
-  - gemfiles/rails.4.2.mongoid.4.0.kaminari.gemfile
-  - gemfiles/rails.4.2.mongoid.4.0.will_paginate.gemfile
+  - gemfiles/rails.5.1.activerecord.gemfile
   - gemfiles/rails.4.2.mongoid.5.1.gemfile
-  - gemfiles/rails.4.2.mongoid.5.1.kaminari.gemfile
-  - gemfiles/rails.4.2.mongoid.5.1.will_paginate.gemfile
-  - gemfiles/sequel.4.38.gemfile
+  - gemfiles/rails.5.0.mongoid.6.0.gemfile
+  - gemfiles/rails.5.1.mongoid.6.1.gemfile
+  - gemfiles/sequel.4.45.gemfile
 matrix:
-  include:
-    - rvm: 2.1
-      gemfile: gemfiles/rails.3.2.activerecord.gemfile
-    - rvm: 2.1
-      gemfile: gemfiles/rails.3.2.activerecord.kaminari.gemfile
-    - rvm: 2.1
-      gemfile: gemfiles/rails.3.2.activerecord.will_paginate.gemfile
+  exclude:
+  - rvm: 2.2.7
+    env: ES_VERSION=5.4.0
+  - rvm: 2.3.4
+    env: ES_VERSION=2.4.4
+  - gemfile: gemfiles/rails.4.0.activerecord.gemfile
+    env: ES_VERSION=5.4.0
+  - gemfile: gemfiles/rails.4.1.activerecord.gemfile
+    env: ES_VERSION=5.4.0
+  - gemfile: gemfiles/rails.4.2.mongoid.5.1.gemfile
+    env: ES_VERSION=5.4.0
+  - gemfile: gemfiles/rails.5.1.mongoid.6.0.gemfile
+    env: ES_VERSION=5.4.0
+  - rvm: 2.4.1
+    gemfile: gemfiles/rails.4.0.activerecord.gemfile
+  - rvm: 2.4.1
+    gemfile: gemfiles/rails.4.1.activerecord.gemfile
 before_install:
-  - curl -s https://download.elastic.co/elasticsearch/elasticsearch/elasticsearch-1.7.5.tar.gz | tar xz -C /tmp
+  - curl -s https://download.elasticsearch.org/elasticsearch/release/org/elasticsearch/distribution/tar/elasticsearch/2.4.4/elasticsearch-2.4.4.tar.gz | tar xz -C /tmp
+  - curl -s https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-5.4.0.tar.gz | tar xz -C /tmp
 before_script:
-  - TEST_CLUSTER_COMMAND="/tmp/elasticsearch-1.7.5/bin/elasticsearch" rake es:start
+  - /tmp/elasticsearch-2.4.4/bin/plugin install delete-by-query
+  - TEST_CLUSTER_COMMAND=/tmp/elasticsearch-$ES_VERSION/bin/elasticsearch TEST_CLUSTER_LOGS=/tmp/log rake es:start
 script:
   - bundle exec rspec
   - bundle exec rubocop

data/.yardopts

@@ -0,0 +1,5 @@
+--markup-provider=redcarpet
+--markup=markdown
+-
+README.md
+CHANGELOG.md

data/Appraisals

@@ -1,51 +1,79 @@
-%w(3.2 4.2 5.0).each do |version|
-  appraise "rails.#{version}.activerecord" do
-    gem 'activerecord', "~> #{version}.0"
-    gem 'activesupport', "~> #{version}.0"
-    gem 'activejob', "~> #{version}.0" if version >= '4.2'
+# rubocop:disable Style/FileName
+
+%w[4.0 4.1 4.2].each do |activesupport|
+  appraise "rails.#{activesupport}.activerecord" do
+    gem 'activerecord', "~> #{activesupport}.0"
+    gem 'activesupport', "~> #{activesupport}.0"
+
+    gem 'activejob', "~> #{activesupport}.0" if activesupport >= '4.2'
     gem 'resque', require: false
+    gem 'shoryuken', require: false
     gem 'sidekiq', require: false
-  end
 
-  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 'kaminari', '~> 0.17.0', require: false
     gem 'will_paginate', require: false
+
+    gem 'parallel', require: false
   end
 end
 
-{ '4.0' => '4.2', '5.1' => '4.2' }.each do |(mongoid, activesupport)|
-  appraise "rails.#{activesupport}.mongoid.#{mongoid}" do
-    gem 'mongoid', "~> #{mongoid}.0"
+%w[5.0 5.1].each do |activesupport|
+  appraise "rails.#{activesupport}.activerecord" do
+    gem 'activerecord', "~> #{activesupport}.0"
     gem 'activesupport', "~> #{activesupport}.0"
+
+    gem 'activejob', "~> #{activesupport}.0"
     gem 'resque', require: false
+    gem 'shoryuken', require: false
     gem 'sidekiq', require: false
-  end
 
-  appraise "rails.#{activesupport}.mongoid.#{mongoid}.kaminari" do
-    gem 'mongoid', "~> #{mongoid}.0"
-    gem 'activesupport', "~> #{activesupport}.0"
-    gem 'kaminari', '0.16.3', require: false
+    gem 'kaminari-core', '~> 1.0.0', require: false
+    gem 'will_paginate', require: false
+
+    gem 'parallel', require: false
   end
+end
+
+appraise 'rails.4.2.mongoid.5.1' do
+  gem 'mongoid', '~> 5.1.0'
+  gem 'activesupport', '~> 4.2.0'
+
+  gem 'activejob', '~> 4.2.0'
+  gem 'resque', require: false
+  gem 'shoryuken', require: false
+  gem 'sidekiq', require: false
+
+  gem 'kaminari', '~> 0.17.0', require: false
+  gem 'will_paginate', require: false
 
-  appraise "rails.#{activesupport}.mongoid.#{mongoid}.will_paginate" do
+  gem 'parallel', require: false
+end
+
+{'5.0' => '6.0', '5.1' => '6.1'}.each do |activesupport, mongoid|
+  appraise "rails.#{activesupport}.mongoid.#{mongoid}" do
     gem 'mongoid', "~> #{mongoid}.0"
     gem 'activesupport', "~> #{activesupport}.0"
+
+    gem 'activejob', "~> #{activesupport}.0"
+    gem 'resque', require: false
+    gem 'shoryuken', require: false
+    gem 'sidekiq', require: false
+
+    gem 'kaminari-core', '~> 1.0.0', require: false
     gem 'will_paginate', require: false
+
+    gem 'parallel', require: false
   end
 end
 
-%w(4.38).each do |sequel|
+%w[4.45].each do |sequel|
   appraise "sequel.#{sequel}" do
     gem 'sequel', "~> #{sequel}.0"
     gem 'activesupport', '~> 5.0.0'
+
+    gem 'kaminari-core', '~> 1.0.0', require: false
+    gem 'will_paginate', require: false
+
+    gem 'parallel', require: false
   end
 end

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # master
 
+## Breaking changes
+
+  * Changed behavior of `Chewy::Index.index_name`, it doesn't cache the values anymore.
+
+  * Journal interfaces, related code and rake tasks were completely refactored and are not compatible with the previous version.
+
+## Changes
+
+  * Parallel import and rake tasks.
+
+  * `:shoryuken` async strategy (@josephchoe, #532)
+
+  * Deprecate `Chewy::Index.build_index_name`.
+
+  * Rename `Chewy::Index.default_prefix` to `Chewy::Index.prefix`. The old one is deprecated.
+
+  * Add `Chewy::Type.derivable_name` for consistency.
+
+  * Rename `Chewy::Index.derivable_index_name` to `Chewy::Index.derivable_name`.
+    `Chewy::Index.derivable_index_name` and `Chewy::Type.derivable_index_name` are deprecated.
+
+  * Use normal YAML loading, for the config, we don't need the safe one.
+
+  * `default_root_options` option (@barthez, #526)
+
+  * Partial indexing ability: it is possible to update only specified fields.
+
+  * New cool `rake chewy:deploy` task.
+
+  * Selective reset (resets only if necessary): `rake chewy:upgrade`.
+
+  * Consistency checks and synchronization: `rake chewy:sync`.
+
+  * Brand new request DSL. Supports ElasticSearch 2 and 5, better usability, architecture and docs.
+
+  * Add Kaminari 1.0 support.
+
+  * `skip_index_creation_on_import` option (@sergey-kintsel, #483)
+
+  * Ability to use procs for settings (@parallel588, #481)
+
+  * Bulk indexing optimizations with new additional options (@eproulx-petalmd, #467)
+
+  * Configurable sidekiq options (@averell23, #438)
+
 # Version 0.9.0
 
 ## Changes
@@ -14,7 +59,7 @@
 
   * Minitest helpers (@robacarp, #396)
 
-  * `Chewy::Query#unlimited` to fetch all the records (@sergey-kintsel, #393)
+  * `Chewy::Query#unlimited` to fetch all the documents (@sergey-kintsel, #393)
 
   * `Chewy::Query#exists?` (@sergey-kintsel, #386)
 
@@ -84,6 +129,12 @@
 
 # Version 0.8.3
 
+## Breaking changes:
+
+  * `Chewy.atomic` and `Chewy.urgent_update=` methods was removed from the codebase, use `Chewy.strategy` block instead.
+
+  * `delete_from_index?` hook is removed from the codebase.
+
 ## Changes
 
   * Sequel support completely reworked to use common ORM implementations + better sequel specs covarage.
@@ -100,12 +151,6 @@
 
   * Correct custom assets path silencer (@davekaro)
 
-## Incompatible changes:
-
-  * `Chewy.atomic` and `Chewy.urgent_update=` methods was removed from the codebase, use `Chewy.strategy` block instead.
-
-  * `delete_from_index?` hook is removed from the codebase.
-
 # Version 0.8.2
 
 ## Changes
@@ -141,7 +186,7 @@
 
 # Version 0.8.0
 
-## Incompatible changes:
+## Breaking changes:
 
   * `:atomic` and `:urgent` strategies are using `import!` method raising exceptions
 
@@ -167,7 +212,7 @@
 
 # Version 0.7.0
 
-## Incompatible changes:
+## Breaking changes:
 
   * `Chewy.use_after_commit_callbacks = false` returns previous RDBMS behavior
   in tests
@@ -296,7 +341,7 @@
 
   * `min_score` query option support (@jshirley)
 
-  * `Chewy::Query#find` method for finding records by id
+  * `Chewy::Query#find` method for finding documents by id
 
 # Version 0.6.0
 
@@ -316,7 +361,7 @@
 
 # Version 0.5.2
 
-## Incompatible changes:
+## Breaking changes:
 
   * `Chewy::Type::Base` removed in favour of using `Chewy::Type` as a base class for all types
 
@@ -356,7 +401,7 @@
 
 # Version 0.5.0
 
-## Incompatible changes:
+## Breaking changes:
 
   * 404 exception (IndexMissingException) while query is swallowed and treated like an empty result set.
 

data/Gemfile

@@ -6,15 +6,19 @@ gem 'activerecord'
 # gem 'mongoid'
 # gem 'sequel'
 
-# gem 'kaminari', require: false
-# gem 'will_paginate', require: false
+gem 'activejob', require: false
+gem 'resque', require: false
+gem 'shoryuken', require: false
+gem 'sidekiq', require: false
 
-# gem 'resque', require: false
-# gem 'sidekiq', require: false
-# gem 'activejob', require: false
+gem 'kaminari-core', require: false
+gem 'will_paginate', require: false
 
-group :test do
-  gem 'guard'
-  gem 'guard-rspec'
-  gem 'listen', '~> 3.0.0'
-end
+gem 'parallel', require: false
+gem 'ruby-progressbar', require: false
+
+gem 'guard'
+gem 'guard-rspec'
+
+gem 'redcarpet'
+gem 'yard'

data/LEGACY_DSL.md

@@ -0,0 +1,497 @@
+# Previous DSL readme.
+
+See `Chewy::Query` for details.
+
+* [Index querying](#index-querying)
+* [Additional query action.](#additional-query-action)
+* [Filters query DSL](#filters-query-dsl)
+* [Faceting](#faceting)
+* [Aggregations](#aggregations)
+* [Script fields](#script-fields)
+* [Script scoring](#script-scoring)
+* [Boost Factor](#boost-factor)
+* [Objects loading](#objects-loading)
+
+## Index querying
+
+```ruby
+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::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
+`filter_mode` and `query_mode` respectively.
+
+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 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 details.
+
+## Additional query action.
+
+You may also perform additional actions on the query scope, such as deleting of all the scope documents:
+
+```ruby
+UsersIndex.delete_all
+UsersIndex::User.delete_all
+UsersIndex.filter{ age < 42 }.delete_all
+UsersIndex::User.filter{ age < 42 }.delete_all
+```
+
+## Filters query 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 the 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-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
+  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 the help of combination operators.
+
+```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
+```
+
+There is also a special syntax for cache enabling:
+
+```ruby
+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
+# 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) }
+  ```
+
+* Match all filter
+
+  ```json
+  {"match_all": {}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ match_all }
+  ```
+
+* Has child filter
+
+  ```json
+  {"has_child": {"type": "blog_tag", "query": {"term": {"tag": "something"}}}
+  {"has_child": {"type": "comment", "filter": {"term": {"user": "john"}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ has_child(:blog_tag).query(term: {tag: 'something'}) }
+  UsersIndex.filter{ has_child(:comment).filter{ user == 'john' } }
+  ```
+
+* Has parent filter
+
+  ```json
+  {"has_parent": {"type": "blog", "query": {"term": {"tag": "something"}}}}
+  {"has_parent": {"type": "blog", "filter": {"term": {"text": "bonsai three"}}}}
+  ```
+
+  ```ruby
+  UsersIndex.filter{ has_parent(:blog).query(term: {tag: 'something'}) }
+  UsersIndex.filter{ has_parent(:blog).filter{ text == 'bonsai three' } }
+  ```
+
+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 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:
+
+```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 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.
+
+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 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(
+  distance: {
+    params: {
+      lat: 37.569976,
+      lon: -122.351591
+    },
+    script: "doc['coordinates'].distanceInMiles(lat, lon)"
+  }
+)
+```
+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
+
+Script scoring is used to score the search results. All scores are added to the search request and combined according to boost mode and score mode. This can be useful if, for example, a score function is computationally expensive and it is sufficient to compute the score on a filtered set of documents. For example, you might want to multiply the score by another numeric field in the doc:
+
+```ruby
+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 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'}})
+```
+
+## Objects loading
+
+It is possible to load source objects from the database for every search result:
+
+```ruby
+scope = UsersIndex.filter(range: {rating: {gte: 100}})
+
+scope.load # => scope is marked to return User instances array
+scope.load.query(...) # => since objects are loaded lazily you can complete scope
+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.load(scope: ->{ includes(:country) }) # and more common scope applied to every loaded object type.
+
+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 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)
+```
+
+See [loading.rb](lib/chewy/query/loading.rb) for more details.