algoliasearch-rails 1.16.3 → 1.25.0

data/LICENSE

@@ -1,7 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2013 Algolia
-http://www.algolia.com/
+Copyright (c) 2013-Present Algolia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -10,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,44 +1,98 @@
-<!--NO_HTML-->
+<p align="center">
+  <a href="https://www.algolia.com">
+    <img alt="Algolia for Rails" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/rails.png" >
+  </a>
 
-Algolia Search for Rails
-==================
+  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your Rails project</h4>
 
-<!--/NO_HTML-->
+  <p align="center">
+    <a href="https://travis-ci.org/algolia/algoliasearch-rails"><img src="https://img.shields.io/travis/algolia/algoliasearch-rails/master.svg" alt="Build Status"></img></a>
+    <a href="http://badge.fury.io/rb/algoliasearch-rails"><img src="https://badge.fury.io/rb/algoliasearch-rails.svg" alt="Gem Version"></img></a>
+    <a href="https://codeclimate.com/github/algolia/algoliasearch-rails"><img src="https://codeclimate.com/github/algolia/algoliasearch-rails.svg" alt="Code Climate"></img></a>
+    <img src="https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square" alt="ActiveRecord"></img>
+    <img src="https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square" alt="Mongoid"></img>
+    <img src="https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square" alt="Sequel"></img>
+  </p>
+</p>
 
-This gem let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-ruby](https://github.com/algolia/algoliasearch-client-ruby) gem. Rails 3.x, 4.x and 5.x are all supported.
+<p align="center">
+  <a href="https://www.algolia.com/doc/framework-integration/rails/getting-started/setup/?language=ruby" target="_blank">Documentation</a>  •
+  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
+  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
+  <a href="https://github.com/algolia/algoliasearch-rails/issues" target="_blank">Report a bug</a>  •
+  <a href="https://www.algolia.com/doc/framework-integration/rails/troubleshooting/faq/" target="_blank">FAQ</a>  •
+  <a href="https://www.algolia.com/support" target="_blank">Support</a>
+</p>
 
-You might be interested in the sample Ruby on Rails application providing a `autocomplete.js`-based auto-completion and `instantsearch.js`-based instant search results page: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
 
-[![Build Status](https://travis-ci.org/algolia/algoliasearch-rails.svg?branch=master)](https://travis-ci.org/algolia/algoliasearch-rails) [![Gem Version](https://badge.fury.io/rb/algoliasearch-rails.svg)](http://badge.fury.io/rb/algoliasearch-rails) [![Code Climate](https://codeclimate.com/github/algolia/algoliasearch-rails.svg)](https://codeclimate.com/github/algolia/algoliasearch-rails) ![ActiveRecord](https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square) ![Mongoid](https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square) ![Sequel](https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square)
+This gem let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-ruby](https://github.com/algolia/algoliasearch-client-ruby) gem.
+Rails 3.x, 4.x and 5.x are all supported.
 
-<!--NO_HTML-->
+You might be interested in the sample Ruby on Rails application providing a `autocomplete.js`-based auto-completion and `InstantSearch.js`-based instant search results page: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
 
-Table of Content
-=============
 
-1. [Install](#install)
-1. [Setup](#setup)
-1. [Quick Start](#quick-start)
-1. [Options](#options)
-1. [Configuration example](#configuration-example)
-1. [Indexing](#indexing)
-1. [Master/Slave](#masterslave)
-1. [Share a single index](#share-a-single-index)
-1. [Target multiple indexes](#target-multiple-indexes)
-1. [Tags](#tags)
-1. [Search](#search)
-1. [Faceting](#faceting)
-1. [Facet search](#facet-search)
-1. [Group by](#group-by)
-1. [Geo-search](#geo-search)
-1. [Caveats](#caveats)
-1. [Note on testing](#note-on-testing)
 
-<!--/NO_HTML-->
+## API Documentation
 
-## Setup
+You can find the full reference on [Algolia's website](https://www.algolia.com/doc/framework-integration/rails/).
 
-### Install
+
+
+1. **[Setup](#setup)**
+    * [Install](#install)
+    * [Configuration](#configuration)
+    * [Timeouts](#timeouts)
+    * [Notes](#notes)
+
+1. **[Usage](#usage)**
+    * [Index Schema](#index-schema)
+    * [Relevancy](#relevancy)
+    * [Indexing](#indexing)
+    * [Frontend Search (realtime experience)](#frontend-search-realtime-experience)
+    * [Backend Search](#backend-search)
+    * [Backend Pagination](#backend-pagination)
+    * [Tags](#tags)
+    * [Faceting](#faceting)
+    * [Faceted search](#faceted-search)
+    * [Group by](#group-by)
+    * [Geo-Search](#geo-search)
+
+1. **[Options](#options)**
+    * [Auto-indexing &amp; asynchronism](#auto-indexing--asynchronism)
+    * [Custom index name](#custom-index-name)
+    * [Per-environment indices](#per-environment-indices)
+    * [Custom attribute definition](#custom-attribute-definition)
+    * [Nested objects/relations](#nested-objectsrelations)
+    * [Custom <code>objectID</code>](#custom-objectid)
+    * [Restrict indexing to a subset of your data](#restrict-indexing-to-a-subset-of-your-data)
+    * [Sanitizer](#sanitizer)
+    * [UTF-8 Encoding](#utf-8-encoding)
+    * [Exceptions](#exceptions)
+    * [Configuration example](#configuration-example)
+
+1. **[Indices](#indices)**
+    * [Manual indexing](#manual-indexing)
+    * [Manual removal](#manual-removal)
+    * [Reindexing](#reindexing)
+    * [Clearing an index](#clearing-an-index)
+    * [Using the underlying index](#using-the-underlying-index)
+    * [Primary/replica](#primaryreplica)
+    * [Share a single index](#share-a-single-index)
+    * [Target multiple indices](#target-multiple-indices)
+
+1. **[Testing](#testing)**
+    * [Notes](#notes)
+
+1. **[Troubleshooting](#troubleshooting)**
+    * [Frequently asked questions](#frequently-asked-questions)
+
+
+
+# Setup
+
+
+
+## Install
 
 ```sh
 gem install algoliasearch-rails
@@ -56,20 +110,51 @@ And run:
 bundle install
 ```
 
-### Configuration
+## Configuration
 
 Create a new file <code>config/initializers/algoliasearch.rb</code> to setup your <code>APPLICATION_ID</code> and <code>API_KEY</code>.
 
-
 ```ruby
 AlgoliaSearch.configuration = { application_id: 'YourApplicationID', api_key: 'YourAPIKey' }
 ```
 
 The gem is compatible with [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord), [Mongoid](https://github.com/mongoid/mongoid) and [Sequel](https://github.com/jeremyevans/sequel).
 
-## Quick Start
+## Timeouts
+
+You can configure a various timeout thresholds by setting the following options at initialization time:
+
+```ruby
+AlgoliaSearch.configuration = {
+  application_id: 'YourApplicationID',
+  api_key: 'YourAPIKey',
+  connect_timeout: 2,
+  receive_timeout: 30,
+  send_timeout: 30,
+  batch_timeout: 120,
+  search_timeout: 5
+}
+```
+
+## Notes
+
+This gem makes extensive use of Rails' callbacks to trigger the indexing tasks. If you're using methods bypassing `after_validation`, `before_save` or `after_commit` callbacks, it will not index your changes. For example: `update_attribute` doesn't perform validations checks, to perform validations when updating use `update_attributes`.
 
-### Schema
+All methods injected by the `AlgoliaSearch` module are prefixed by `algolia_` and aliased to the associated short names if they aren't already defined.
+
+```ruby
+Contact.algolia_reindex! # <=> Contact.reindex!
+
+Contact.algolia_search("jon doe") # <=> Contact.search("jon doe")
+```
+
+
+
+# Usage
+
+
+
+## Index Schema
 
 The following code will create a <code>Contact</code> index and add search capabilities to your <code>Contact</code> model:
 
@@ -78,7 +163,7 @@ class Contact < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch do
-    attribute :first_name, :last_name, :email
+    attributes :first_name, :last_name, :email
   end
 end
 ```
@@ -112,7 +197,7 @@ class Product < ActiveRecord::Base
 end
 ```
 
-### Relevancy
+## Relevancy
 
 We provide many ways to configure your index allowing you to tune your overall index relevancy. The most important ones are the **searchable attributes** and the attributes reflecting **record popularity**.
 
@@ -124,11 +209,11 @@ class Product < ActiveRecord::Base
     # list of attribute used to build an Algolia record
     attributes :title, :subtitle, :description, :likes_count, :seller_name
 
-    # the attributesToIndex` setting defines the attributes
+    # the `searchableAttributes` (formerly known as attributesToIndex) setting defines the attributes
     # you want to search in: here `title`, `subtitle` & `description`.
     # You need to list them by order of importance. `description` is tagged as
     # `unordered` to avoid taking the position of a match into account in that attribute.
-    attributesToIndex ['title', 'subtitle', 'unordered(description)']
+    searchableAttributes ['title', 'subtitle', 'unordered(description)']
 
     # the `customRanking` setting defines the ranking criteria use to compare two matching
     # records in case their text-relevance is equal. It should reflect your record popularity.
@@ -138,7 +223,7 @@ class Product < ActiveRecord::Base
 end
 ```
 
-### Indexing
+## Indexing
 
 To index a model, simple call `reindex` on the class:
 
@@ -156,11 +241,11 @@ algolia_models = ActiveRecord::Base.descendants.select{ |model| model.respond_to
 algolia_models.each(&:reindex)
 ```
 
-### Frontend Search (realtime experience)
+## Frontend Search (realtime experience)
 
 Traditional search implementations tend to have search logic and functionality on the backend. This made sense when the search experience consisted of a user entering a search query, executing that search, and then being redirected to a search result page.
 
-Implementing search on the backend is no longer necessary. In fact, in most cases it is harmful to performance because of added network and processing latency. We highly recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) issuing all search requests directly from the end user's browser, mobile device, or client. It will reduce the overall search latency while offloading your servers at the same time.
+Implementing search on the backend is no longer necessary. In fact, in most cases it is harmful to performance because of added network and processing latency. We highly recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-javascript) issuing all search requests directly from the end user's browser, mobile device, or client. It will reduce the overall search latency while offloading your servers at the same time.
 
 The JS API client is part of the gem, just require `algolia/v3/algoliasearch.min` somewhere in your JavaScript manifest, for example in `application.js` if you are using Rails 3.1+:
 
@@ -182,23 +267,58 @@ index.search('something', { hitsPerPage: 10, page: 0 })
   });
 ```
 
-**We recently (March 2015) released a new version (V3) of our JavaScript client, if you were using our previous version (V2), [read the migration guide](https://github.com/algolia/algoliasearch-client-js/wiki/Migration-guide-from-2.x.x-to-3.x.x)**
+**We recently (March 2015) released a new version (V3) of our JavaScript client, if you were using our previous version (V2), [read the migration guide](https://github.com/algolia/algoliasearch-client-javascript/wiki/Migration-guide-from-2.x.x-to-3.x.x)**
 
-### Backend Search
+## Backend Search
 
-If you want to search from your backend you can use the `raw_search` method. It retrieves the raw JSON answer from the API:
+***Notes:*** We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-javascript) to perform queries directly from the end-user browser without going through your server.
+
+A search returns ORM-compliant objects reloading them from your database. We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-javascript) to perform queries to decrease the overall latency and offload your servers.
 
 ```ruby
-p Contact.raw_search("jon doe")
+hits =  Contact.search("jon doe")
+p hits
+p hits.raw_answer # to get the original JSON raw answer
 ```
 
-You could also use `search` but it's not recommended. This method will fetch the matching `objectIDs` from the API and perform a database query to retrieve an array of matching models:
+A `highlight_result` attribute is added to each ORM object:
 
 ```ruby
-p Contact.search("jon doe") # we recommend to use `raw_search` to avoid the database lookup
+hits[0].highlight_result['first_name']['value']
 ```
 
-### Backend Pagination
+If you want to retrieve the raw JSON answer from the API, without re-loading the objects from the database, you can use:
+
+```ruby
+json_answer = Contact.raw_search("jon doe")
+p json_answer
+p json_answer['hits']
+p json_answer['facets']
+```
+
+Search parameters can be specified either through the index's [settings](https://github.com/algolia/algoliasearch-client-ruby#index-settings-parameters) statically in your model or dynamically at search time specifying [search parameters](https://github.com/algolia/algoliasearch-client-ruby#search) as second argument of the `search` method:
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  algoliasearch do
+    attribute :first_name, :last_name, :email
+
+    # default search parameters stored in the index settings
+    minWordSizefor1Typo 4
+    minWordSizefor2Typos 8
+    hitsPerPage 42
+  end
+end
+```
+
+```ruby
+# dynamical search parameters
+p Contact.raw_search('jon doe', { hitsPerPage: 5, page: 2 })
+```
+
+## Backend Pagination
 
 Even if we **highly recommend to perform all search (and therefore pagination) operations from your frontend using JavaScript**, we support both [will_paginate](https://github.com/mislav/will_paginate) and [kaminari](https://github.com/amatsuda/kaminari) as pagination backend.
 
@@ -222,21 +342,129 @@ Then, as soon as you use the `search` method, the returning results will be a pa
 <%= paginate @results %>
 ```
 
-### Notes
+## Tags
 
-All methods injected by the `AlgoliaSearch` include are prefixed by `algolia_` and aliased to the associated short names if they aren't already defined.
+Use the <code>tags</code> method to add tags to your record:
 
 ```ruby
-Contact.algolia_reindex! # <=> Contact.reindex!
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
 
-Contact.algolia_search("jon doe") # <=> Contact.search("jon doe")
+  algoliasearch do
+    tags ['trusted']
+  end
+end
 ```
 
-## Options
+or using dynamical values:
 
-### Auto-indexing & asynchronism
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
 
-Each time a record is saved; it will be - asynchronously - indexed. On the other hand, each time a record is destroyed, it will be - asynchronously - removed from the index. That means that a network call with the ADD/DELETE operation is sent **synchronously** to the Algolia API but then the engine will **asynchronously** process the operation (so if you do a search just after, the results may not reflect it yet).
+  algoliasearch do
+    tags do
+      [first_name.blank? || last_name.blank? ? 'partial' : 'full', has_valid_email? ? 'valid_email' : 'invalid_email']
+    end
+  end
+end
+```
+
+At query time, specify <code>{ tagFilters: 'tagvalue' }</code> or <code>{ tagFilters: ['tagvalue1', 'tagvalue2'] }</code> as search parameters to restrict the result set to specific tags.
+
+## Faceting
+
+Facets can be retrieved calling the extra `facets` method of the search answer.
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  algoliasearch do
+    # [...]
+
+    # specify the list of attributes available for faceting
+    attributesForFaceting [:company, :zip_code]
+  end
+end
+```
+
+```ruby
+hits = Contact.search('jon doe', { facets: '*' })
+p hits                    # ORM-compliant array of objects
+p hits.facets             # extra method added to retrieve facets
+p hits.facets['company']  # facet values+count of facet 'company'
+p hits.facets['zip_code'] # facet values+count of facet 'zip_code'
+```
+
+```ruby
+raw_json = Contact.raw_search('jon doe', { facets: '*' })
+p raw_json['facets']
+```
+
+## Faceted search
+
+You can also search for facet values.
+
+```ruby
+Product.search_for_facet_values('category', 'Headphones') # Array of {value, highlighted, count}
+```
+
+This method can also take any parameter a query can take.
+This will adjust the search to only hits which would have matched the query.
+
+```ruby
+# Only sends back the categories containing red Apple products (and only counts those)
+Product.search_for_facet_values('category', 'phone', {
+  query: 'red',
+  filters: 'brand:Apple'
+}) # Array of phone categories linked to red Apple products
+```
+
+## Group by
+
+More info on distinct for grouping can be found
+[here](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/).
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  algoliasearch do
+    # [...]
+
+    # specify the attribute to be used for distinguishing the records
+    # in this case the records will be grouped by company
+    attributeForDistinct "company"
+  end
+end
+```
+
+## Geo-Search
+
+Use the <code>geoloc</code> method to localize your record:
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  algoliasearch do
+    geoloc :lat_attr, :lng_attr
+  end
+end
+```
+
+At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
+
+
+
+# Options
+
+
+
+## Auto-indexing & asynchronism
+
+Each time a record is saved, it will be *asynchronously* indexed. On the other hand, each time a record is destroyed, it will be - asynchronously - removed from the index. That means that a network call with the ADD/DELETE operation is sent **synchronously** to the Algolia API but then the engine will **asynchronously** process the operation (so if you do a search just after, the results may not reflect it yet).
 
 You can disable auto-indexing and auto-removing setting the following options:
 
@@ -250,7 +478,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Temporary disable auto-indexing
+### Temporary disable auto-indexing
 
 You can temporary disable auto-indexing using the <code>without_auto_index</code> scope. This is often used for performance reason.
 
@@ -262,7 +490,7 @@ end
 Contact.reindex! # will use batch operations
 ```
 
-#### Queues & background jobs
+### Queues & background jobs
 
 You can configure the auto-indexing & auto-removal process to use a queue to perform those operations in background. ActiveJob (Rails >=4.2) queues are used by default but you can define your own queuing mechanism:
 
@@ -276,7 +504,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Things to Consider
+### Things to Consider
 
 If you are performing updates & deletions in the background then a record deletion can be committed to your database prior
 to the job actually executing. Thus if you were to load the record to remove it from the database than your ActiveRecord#find will fail with a RecordNotFound.
@@ -300,7 +528,7 @@ class MySidekiqWorker
 end
 ```
 
-#### With Sidekiq
+### With Sidekiq
 
 If you're using [Sidekiq](https://github.com/mperham/sidekiq):
 
@@ -319,13 +547,21 @@ end
 
 class MySidekiqWorker
   def perform(id, remove)
-    c = Contact.find(id)
-    remove ? c.remove_from_index! : c.index!
+    if remove
+      # the record has likely already been removed from your database so we cannot
+      # use ActiveRecord#find to load it
+      index = Algolia::Index.new("index_name")
+      index.delete_object(id)
+    else
+      # the record should be present
+      c = Contact.find(id)
+      c.index!
+    end
   end
 end
 ```
 
-#### With DelayedJob
+### With DelayedJob
 
 If you're using [delayed_job](https://github.com/collectiveidea/delayed_job):
 
@@ -348,7 +584,7 @@ end
 
 ```
 
-#### Synchronism & testing
+### Synchronism & testing
 
 You can force indexing and removing to be synchronous (in that case the gem will call the `wait_task` method to ensure the operation has been taken into account once the method returns) by setting the following option: (this is **NOT** recommended, except for testing purpose)
 
@@ -362,22 +598,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-### Exceptions
-
-You can disable exceptions that could be raised while trying to reach Algolia's API by using the `raise_on_failure` option:
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  # only raise exceptions in development env
-  algoliasearch raise_on_failure: Rails.env.development? do
-    attribute :first_name, :last_name, :email
-  end
-end
-```
-
-### Custom index name
+## Custom index name
 
 By default, the index name will be the class name, e.g. "Contact". You can customize the index name by using the `index_name` option:
 
@@ -391,7 +612,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-### Per-environment indexes
+## Per-environment indices
 
 You can suffix the index name with the current Rails environment using the following option:
 
@@ -405,7 +626,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-### Custom attribute definition
+## Custom attribute definition
 
 You can use a block to specify a complex attribute value
 
@@ -446,7 +667,9 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-### Nested objects/relations
+## Nested objects/relations
+
+### Defining the relationship
 
 You can easily embed nested objects defining an extra attribute returning any JSON-compliant object (an array or a hash or a combination of both).
 
@@ -473,7 +696,83 @@ class Profile < ActiveRecord::Base
 end
 ```
 
-### Custom `objectID`
+### Propagating the change from a nested child
+
+#### With ActiveRecord
+
+With ActiveRecord, we'll be using `touch` and `after_touch` to achieve this.
+
+```ruby
+# app/models/app.rb
+class App < ApplicationRecord
+  include AlgoliaSearch
+
+  belongs_to :author, class_name: :User
+  after_touch :index!
+
+  algoliasearch do
+    attribute :title
+    attribute :author do
+      author.as_json
+    end
+  end
+end
+
+# app/models/user.rb
+class User < ApplicationRecord
+  # If your association uses belongs_to
+  # - use `touch: true`
+  # - do not define an `after_save` hook
+  has_many :apps, foreign_key: :author_id
+
+  after_save { apps.each(&:touch) }
+end
+```
+
+#### With Sequel
+
+With Sequel, you can use the `touch` plugin to propagate the changes:
+
+```ruby
+# app/models/app.rb
+class App < Sequel::Model
+  include AlgoliaSearch
+
+  many_to_one :author, class: :User
+
+  plugin :timestamps
+  plugin :touch
+
+  algoliasearch do
+    attribute :title
+    attribute :author do
+      author.to_hash
+    end
+  end
+end
+
+# app/models/user.rb
+class User < Sequel::Model
+  one_to_many :apps, key: :author_id
+
+  plugin :timestamps
+  # Can't use the associations since it won't trigger the after_save
+  plugin :touch
+
+  # Define the associations that need to be touched here
+  # Less performant, but allows for the after_save hook to trigger
+  def touch_associations
+    apps.map(&:touch)
+  end
+
+  def touch
+    super
+    touch_associations
+  end
+end
+```
+
+## Custom `objectID`
 
 By default, the `objectID` is based on your record's `id`. You can change this behavior specifying the `:id` option (be sure to use a uniq field).
 
@@ -486,7 +785,7 @@ class UniqUser < ActiveRecord::Base
 end
 ```
 
-### Restrict indexing to a subset of your data
+## Restrict indexing to a subset of your data
 
 You can add constraints controlling if a record must be indexed by using options the `:if` or `:unless` options.
 
@@ -528,7 +827,6 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-
 You can index a subset of your records using either:
 
 ```ruby
@@ -542,7 +840,7 @@ or
 MyModel.index_objects MyModel.limit(5)
 ```
 
-### Sanitizer
+## Sanitizer
 
 You can sanitize all your attributes using the `sanitize` option. It will strip all HTML tags from your attributes.
 
@@ -563,8 +861,7 @@ If you're using Rails 4.2+, you also need to depend on `rails-html-sanitizer`:
 gem 'rails-html-sanitizer'
 ```
 
-
-### UTF-8 Encoding
+## UTF-8 Encoding
 
 You can force the UTF-8 encoding of all your attributes using the `force_utf8_encoding` option:
 
@@ -581,8 +878,22 @@ end
 
 ***Notes:*** This option is not compatible with Ruby 1.8
 
+## Exceptions
 
-### Configuration example
+You can disable exceptions that could be raised while trying to reach Algolia's API by using the `raise_on_failure` option:
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  # only raise exceptions in development env
+  algoliasearch raise_on_failure: Rails.env.development? do
+    attribute :first_name, :last_name, :email
+  end
+end
+```
+
+## Configuration example
 
 Here is a real-word configuration example (from [HN Search](https://github.com/algolia/hn-search)):
 
@@ -601,7 +912,7 @@ class Item < ActiveRecord::Base
 
     # `title` is more important than `{story,comment}_text`, `{story,comment}_text` more than `url`, `url` more than `author`
     # btw, do not take into account position in most fields to avoid first word match boost
-    attributesToIndex ['unordered(title)', 'unordered(story_text)', 'unordered(comment_text)', 'unordered(url)', 'author']
+    searchableAttributes ['unordered(title)', 'unordered(story_text)', 'unordered(comment_text)', 'unordered(url)', 'author']
 
     # tags used for filtering
     tags do
@@ -639,9 +950,13 @@ class Item < ActiveRecord::Base
 end
 ```
 
-## Indexing
 
-### Manual indexing
+
+# Indices
+
+
+
+## Manual indexing
 
 You can trigger indexing using the <code>index!</code> instance method.
 
@@ -650,7 +965,7 @@ c = Contact.create!(params[:contact])
 c.index!
 ```
 
-### Manual removal
+## Manual removal
 
 And trigger index removing using the <code>remove_from_index!</code> instance method.
 
@@ -659,13 +974,13 @@ c.remove_from_index!
 c.destroy
 ```
 
-### Reindexing
+## Reindexing
 
 The gem provides 2 ways to reindex all your objects:
 
-#### Atomical reindexing
+### Atomical reindexing
 
-To reindex all your records (taking into account the deleted objects), the `reindex` class method indexes all your objects to a temporary index called `<INDEX_NAME>.tmp` and moves the temporary index to the final one once everything is indexed (atomically). This is the safest way to reindex all your content.
+To reindex all your records (taking into account the deleted objects), the `reindex` class method indices all your objects to a temporary index called `<INDEX_NAME>.tmp` and moves the temporary index to the final one once everything is indexed (atomically). This is the safest way to reindex all your content.
 
 ```ruby
 Contact.reindex
@@ -673,7 +988,9 @@ Contact.reindex
 
 **Notes**: if you're using an index-specific API key, ensure you're allowing both `<INDEX_NAME>` and `<INDEX_NAME>.tmp`.
 
-#### Regular reindexing
+**Warning:** You should not use such an atomic reindexing operation while scoping/filtering the model because this operation **replaces the entire index**, keeping the filtered objects only. ie: Don't do `MyModel.where(...).reindex` but do `MyModel.where(...).reindex!` (with the trailing `!`)!!!
+
+### Regular reindexing
 
 To reindex all your objects in place (without temporary index and therefore without deleting removed objects), use the `reindex!` class method:
 
@@ -681,7 +998,7 @@ To reindex all your objects in place (without temporary index and therefore with
 Contact.reindex!
 ```
 
-### Clearing an index
+## Clearing an index
 
 To clear an index, use the <code>clear_index!</code> class method:
 
@@ -689,7 +1006,7 @@ To clear an index, use the <code>clear_index!</code> class method:
 Contact.clear_index!
 ```
 
-### Using the underlying index
+## Using the underlying index
 
 You can access the underlying `index` object by calling the `index` class method:
 
@@ -698,11 +1015,10 @@ index = Contact.index
 # index.get_settings, index.partial_update_object, ...
 ```
 
-## Indexes
-
-### Master/slave
+## Primary/replica
 
-You can define slave indexes using the <code>add_slave</code> method:
+You can define replica indices using the <code>add_replica</code> method.
+Use `inherit: true` on the replica block if you want it  to inherit from the primary settings.
 
 ```ruby
 class Book < ActiveRecord::Base
@@ -711,31 +1027,31 @@ class Book < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch per_environment: true do
-    attributesToIndex [:name, :author, :editor]
+    searchableAttributes [:name, :author, :editor]
 
-    # define a slave index to search by `author` only
-    add_slave 'Book_by_author', per_environment: true do
-      attributesToIndex [:author]
+    # define a replica index to search by `author` only
+    add_replica 'Book_by_author', per_environment: true do
+      searchableAttributes [:author]
     end
 
-    # define a slave index to search by `editor` only
-    add_slave 'Book_by_editor', per_environment: true do
-      attributesToIndex [:editor]
+    # define a replica index with custom ordering but same settings than the main block
+    add_replica 'Book_custom_order', inherit: true, per_environment: true do
+      customRanking ['asc(rank)']
     end
   end
 
 end
 ```
 
-To search using a slave, use the following code:
+To search using a replica, use the following code:
 
 ```ruby
-Book.raw_search 'foo bar', slave: 'Book_by_editor'
+Book.raw_search 'foo bar', replica: 'Book_by_editor'
 # or
-Book.search 'foo bar', slave: 'Book_by_editor'
+Book.search 'foo bar', replica: 'Book_by_editor'
 ```
 
-### Share a single index
+## Share a single index
 
 It can make sense to share an index between several models. In order to implement that, you'll need to ensure you don't have any conflict with the `objectID` of the underlying models.
 
@@ -773,9 +1089,9 @@ end
 
 ***Notes:*** If you target a single index from several models, you must never use `MyModel.reindex` and only use `MyModel.reindex!`. The `reindex` method uses a temporary index to perform an atomic reindexing: if you use it, the resulting index will only contain records for the current model because it will not reindex the others.
 
-### Target multiple indexes
+## Target multiple indices
 
-You can index a record in several indexes using the <code>add_index</code> method:
+You can index a record in several indices using the <code>add_index</code> method:
 
 ```ruby
 class Book < ActiveRecord::Base
@@ -788,7 +1104,7 @@ class Book < ActiveRecord::Base
 
   # store all books in index 'SECURED_INDEX_NAME'
   algoliasearch index_name: SECURED_INDEX_NAME do
-    attributesToIndex [:name, :author]
+    searchableAttributes [:name, :author]
     # convert security to tags
     tags do
       [released ? 'public' : 'private', premium ? 'premium' : 'standard']
@@ -796,7 +1112,7 @@ class Book < ActiveRecord::Base
 
     # store all 'public' (released and not premium) books in index 'PUBLIC_INDEX_NAME'
     add_index PUBLIC_INDEX_NAME, if: :public? do
-      attributesToIndex [:name, :author]
+      searchableAttributes [:name, :author]
     end
   end
 
@@ -816,198 +1132,15 @@ Book.raw_search 'foo bar', index: 'Book_by_editor'
 Book.search 'foo bar', index: 'Book_by_editor'
 ```
 
-## Features
 
-### Tags
 
-Use the <code>tags</code> method to add tags to your record:
+# Testing
 
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
 
-  algoliasearch do
-    tags ['trusted']
-  end
-end
-```
-
-or using dynamical values:
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  algoliasearch do
-    tags do
-      [first_name.blank? || last_name.blank? ? 'partial' : 'full', has_valid_email? ? 'valid_email' : 'invalid_email']
-    end
-  end
-end
-```
-
-At query time, specify <code>{ tagFilters: 'tagvalue' }</code> or <code>{ tagFilters: ['tagvalue1', 'tagvalue2'] }</code> as search parameters to restrict the result set to specific tags.
-
-### Search
-
-***Notes:*** We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) to perform queries directly from the end-user browser without going through your server.
-
-A search returns ORM-compliant objects reloading them from your database. We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) to perform queries to decrease the overall latency and offload your servers.
-
-
-```ruby
-hits =  Contact.search("jon doe")
-p hits
-p hits.raw_answer # to get the original JSON raw answer
-```
-
-A `highlight_result` attribute is added to each ORM object:
-
-```ruby
-hits[0].highlight_result['first_name']['value']
-```
 
-If you want to retrieve the raw JSON answer from the API, without re-loading the objects from the database, you can use:
+## Notes
 
-```ruby
-json_answer = Contact.raw_search("jon doe")
-p json_answer
-p json_answer['hits']
-p json_answer['facets']
-```
-
-Search parameters can be specified either through the index's [settings](https://github.com/algolia/algoliasearch-client-ruby#index-settings-parameters) statically in your model or dynamically at search time specifying [search parameters](https://github.com/algolia/algoliasearch-client-ruby#search) as second argument of the `search` method:
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  algoliasearch do
-    attribute :first_name, :last_name, :email
-
-    # default search parameters stored in the index settings
-    minWordSizeForApprox1 4
-    minWordSizeForApprox2 8
-    hitsPerPage 42
-  end
-end
-```
-
-
-```ruby
-# dynamical search parameters
-p Contact.raw_search("jon doe", { :hitsPerPage => 5, :page => 2 })
-```
-
-### Faceting
-
-Facets can be retrieved calling the extra `facets` method of the search answer.
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  algoliasearch do
-    # [...]
-
-    # specify the list of attributes available for faceting
-    attributesForFaceting [:company, :zip_code]
-  end
-end
-```
-
-
-```ruby
-hits = Contact.search("jon doe", { :facets => '*' })
-p hits                    # ORM-compliant array of objects
-p hits.facets             # extra method added to retrieve facets
-p hits.facets['company']  # facet values+count of facet 'company'
-p hits.facets['zip_code'] # facet values+count of facet 'zip_code'
-```
-
-
-```ruby
-raw_json = Contact.raw_search("jon doe", { :facets => '*' })
-p raw_json['facets']
-```
-
-### Facet search
-
-You can also search for facet values.
-
-```ruby
-Product.search_for_facet_values('category', 'Headphones') # Array of {value, highlighted, count}
-```
-
-This method can also take any parameter a query can take.
-This will adjust the search to only hits which would have matched the query.
-
-```ruby
-# Only sends back the categories containing red Apple products (and only counts those)
-Product.search_for_facet_values('category', 'phone', {
-  query: 'red',
-  filters: 'brand:Apple'
-}) # Array of phone categories linked to red Apple products
-```
-
-### Group by
-
-More info on distinct for grouping can be found
-[here](https://www.algolia.com/doc/guides/search/distinct#distinct-for-grouping).
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  algoliasearch do
-    # [...]
-
-    # specify the attribute to be used for distinguishing the records
-    # in this case the records will be grouped by company
-    attributeForDistinct "company"
-  end
-end
-```
-
-### Geo-Search
-
-Use the <code>geoloc</code> method to localize your record:
-
-```ruby
-class Contact < ActiveRecord::Base
-  include AlgoliaSearch
-
-  algoliasearch do
-    geoloc :lat_attr, :lng_attr
-  end
-end
-```
-
-At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
-
-### Caveats
-
-This gem makes intensive use of Rails' callbacks to trigger the indexing tasks. If you're using methods bypassing `after_validation`, `before_save` or `after_commit` callbacks, it will not index your changes. For example: `update_attribute` doesn't perform validations checks, to perform validations when updating use `update_attributes`.
-
-### Timeouts
-
-You can configure a bunch of timeout threshold by setting the following options at initialization time:
-
-```ruby
-AlgoliaSearch.configuration = {
-  application_id: 'YourApplicationID',
-  api_key: 'YourAPIKey'
-  connect_timeout: 2,
-  receive_timeout: 30,
-  send_timeout: 30,
-  batch_timeout: 120,
-  search_timeout: 5
-}
-```
-
-### Note on testing
-
-To run the specs, please set the <code>ALGOLIA_APPLICATION_ID</code> and <code>ALGOLIA_API_KEY</code> environment variables. Since the tests are creating and removing indexes, DO NOT use your production account.
+To run the specs, please set the <code>ALGOLIA_APPLICATION_ID</code> and <code>ALGOLIA_API_KEY</code> environment variables. Since the tests are creating and removing indices, DO NOT use your production account.
 
 You may want to disable all indexing (add, update & delete operations) API calls, you can set the `disable_indexing` option:
 
@@ -1015,14 +1148,14 @@ You may want to disable all indexing (add, update & delete operations) API calls
 class User < ActiveRecord::Base
   include AlgoliaSearch
 
-  algoliasearch :per_environment => true, :disable_indexing => Rails.env.test? do
+  algoliasearch per_environment: true, disable_indexing: Rails.env.test? do
   end
 end
 
 class User < ActiveRecord::Base
   include AlgoliaSearch
 
-  algoliasearch :per_environment => true, :disable_indexing => Proc.new { Rails.env.test? || more_complex_condition } do
+  algoliasearch per_environment: true, disable_indexing: Proc.new { Rails.env.test? || more_complex_condition } do
   end
 end
 ```
@@ -1050,3 +1183,12 @@ describe 'With a mocked client' do
 end
 ```
 
+
+## ❓ Troubleshooting
+
+Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/ruby/) where you will find answers for the most common issues and gotchas with the client.
+
+## Use the Dockerfile
+
+If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.MD) to learn more.
+