:rocket: Intelligent search made easy

:tangerine: Battle-tested at Instacart

Searchkick learns what your users are looking for. As more people search, it gets smarter and the results get better. It’s friendly for developers - and magical for your users.

Searchkick handles:

  • stemming - tomatoes matches tomato
  • special characters - jalapeno matches jalapeño
  • extra whitespace - dishwasher matches dish washer
  • misspellings - zuchini matches zucchini
  • custom synonyms - qtip matches cotton swab


  • query like SQL - no need to learn a new query language
  • reindex without downtime
  • easily personalize results for each user
  • autocomplete
  • “Did you mean” suggestions
  • works with ActiveRecord and Mongoid

:speech_balloon: Get handcrafted updates for new features

Build Status

We highly recommend tracking queries and conversions

:zap:Searchjoy makes it easy

Get Started

Install Elasticsearch. For Homebrew, use:

brew install elasticsearch

Add this line to your application’s Gemfile:

gem 'searchkick'

For Elasticsearch 0.90, use version 0.6.3 and this readme.

Add searchkick to models you want to search.

class Product < ActiveRecord::Base

Add data to the search index.


And to query, use:

products = "2% Milk"
products.each do |product|

Searchkick supports the complete Elasticsearch Search API. As your search becomes more advanced, we recommend you use the Elasticsearch DSL for maximum flexibility.


Query like SQL "2% Milk", where: {in_stock: true}, limit: 10, offset: 50

Search specific fields

fields: [:name, :brand]


where: {
  expires_at: {gt:}, # lt, gte, lte also available
  orders_count: 1..10,        # equivalent to {gte: 1, lte: 10}
  aisle_id: [25, 30],         # in
  store_id: {not: 2},         # not
  aisle_id: {not: [25, 30]},  # not in
  user_ids: {all: [1, 3]},    # all elements in array
  or: [
    [{in_stock: true}, {backordered: true}]


order: {_score: :desc} # most relevant first - default

All of these sort options are supported

Limit / offset

limit: 20, offset: 40


Boost important fields

fields: ["title^10", "description"]

Boost by the value of a field (field must be numeric)

boost_by: [:orders_count] # give popular documents a little boost
boost_by: {orders_count: {factor: 10}} # default factor is 1

Boost matching documents

boost_where: {user_id: 1} # default factor is 1000
boost_where: {user_id: {value: 1, factor: 100}}

Conversions are also a great way to boost.

Get Everything

Use a * for the query. "*"


Plays nicely with kaminari and will_paginate.

# controller
@products = "milk", page: params[:page], per_page: 20

View with kaminari

<%= paginate @products %>

View with will_paginate

<%= will_paginate @products %>

Partial Matches

By default, results must match all words in the query. "fresh honey" # fresh AND honey

To change this, use: "fresh honey", operator: "or" # fresh OR honey

By default, results must match the entire word - back will not match backpack. You can change this behavior with:

class Product < ActiveRecord::Base
  searchkick word_start: [:name]

And to search (after you reindex): "back", fields: [{name: :word_start}]

Available options are:

:word # default

To boost fields, use:

fields: [{"name^2" => :word_start}] # better interface on the way

Exact Matches "", fields: [{email: :exact}, :name]


Searchkick defaults to English for stemming. To change this, use:

class Product < ActiveRecord::Base
  searchkick language: "German"

See the list of languages


class Product < ActiveRecord::Base
  searchkick synonyms: [["scallion", "green onion"], ["qtip", "cotton swab"]]

Call Product.reindex after changing synonyms.


Prepopulate English synonyms with the WordNet database.

Download WordNet 3.0 to each Elasticsearch server and move to the /var/lib directory.

cd /tmp
curl -o wordnet.tar.gz
tar -zxvf wordnet.tar.gz
mv prolog/ /var/lib

Tell each model to use it:

class Product < ActiveRecord::Base
  searchkick wordnet: true


By default, Searchkick handles misspelled queries by returning results with an edit distance of one. To turn off this feature, use: "zuchini", misspellings: false # no zucchini

You can also change the edit distance with: "zucini", misspellings: {edit_distance: 2} # zucchini


Control what data is indexed with the search_data method. Call Product.reindex after changing this method.

class Product < ActiveRecord::Base
  def search_data
    as_json only: [:name, :active]
    # or equivalently
      name: name,
      active: active

Searchkick uses find_in_batches to import documents. To eager load associations, use the search_import scope.

class Product < ActiveRecord::Base
  scope :search_import, -> { includes(:searches) }

By default, all records are indexed. To control which records are indexed, use the should_index? method.

class Product < ActiveRecord::Base
  def should_index?
    active # only index active records

To Reindex, or Not to Reindex


  • when you install or upgrade searchkick
  • change the search_data method
  • change the searchkick method

No need to reindex

  • App starts

Stay Synced

There are three strategies for keeping the index synced with your database.

  1. Immediate (default)

    Anytime a record is inserted, updated, or deleted

  2. Asynchronous

    Use background jobs for better performance

    class Product < ActiveRecord::Base
      searchkick callbacks: :async

    And install Active Job for Rails 4.1 and below

  3. Manual

    Turn off automatic syncing

    class Product < ActiveRecord::Base
      searchkick callbacks: false

Keep Getting Better

Searchkick uses conversion data to learn what users are looking for. If a user searches for “ice cream” and adds Ben & Jerry’s Chunky Monkey to the cart (our conversion metric at Instacart), that item gets a little more weight for similar searches.

The first step is to define your conversion metric and start tracking conversions. The database works well for low volume, but feel free to use Redis or another datastore.

class Search < ActiveRecord::Base
  belongs_to :product
  # fields: id, query, searched_at, converted_at, product_id

You do not need to clean up the search queries. Searchkick automatically treats apple and APPLES the same.

Next, add conversions to the index.

class Product < ActiveRecord::Base
  has_many :searches

  searchkick conversions: "conversions" # name of field

  def search_data
      name: name,
      # {"ice cream" => 234, "chocolate" => 67, "cream" => 2}

Reindex and set up a cron job to add new conversions daily.

rake searchkick:reindex CLASS=Product

Personalized Results

Order results differently for each user. For example, show a user’s previously purchased products before other results.

class Product < ActiveRecord::Base

  def search_data
      name: name,
      orderer_ids: orders.pluck(:user_id) # boost this product for these users


Reindex and search with: "milk", boost_where: {orderer_ids:}


Autocomplete predicts what a user will type, making the search experience faster and easier.


Note: If you only have a few thousand records, don’t use Searchkick for autocomplete. It’s much faster to load all records into JavaScript and autocomplete there (eliminates network requests).

First, specify which fields use this feature. This is necessary since autocomplete can increase the index size significantly, but don’t worry - this gives you blazing faster queries.

class City < ActiveRecord::Base
  searchkick text_start: [:name]

Reindex and search with: "san fr", fields: [{name: :text_start}]

Typically, you want to use a JavaScript library like typeahead.js or jQuery UI.

Here’s how to make it work with Rails

First, add a route and controller action.

# app/controllers/cities_controller.rb
class CitiesController < ApplicationController

  def autocomplete
    render json:[:query], fields: [{name: :text_start}], limit: 10).map(&:name)


Then add the search box and JavaScript code to a view.

<input type="text" id="query" name="query" />

<script src="jquery.js"></script>
<script src="typeahead.js"></script>
    name: "city",
    remote: "/cities/autocomplete?query=%QUERY"



class Product < ActiveRecord::Base
  searchkick suggest: ["name"] # fields to generate suggestions

Reindex and search with:

products = "peantu butta", suggest: true
products.suggestions # ["peanut butter"]


Facets provide aggregated search data.


products = "chuck taylor", facets: [:product_type, :gender, :brand]
p products.facets

By default, where conditions are not applied to facets (for backward compatibility). "wingtips", where: {color: "brandy"}, facets: [:size]
# facets *not* filtered by color :(

Change this with: "wingtips", where: {color: "brandy"}, facets: [:size], smart_facets: true

or set where conditions for each facet separately: "wingtips", facets: {size: {where: {color: "brandy"}}}

Limit "2% Milk", facets: {store_id: {limit: 10}}


price_ranges = [{to: 20}, {from: 20, to: 50}, {from: 50}] "*", facets: {price: {ranges: price_ranges}}

Use the stats option to get to max, min, mean, and total scores for each facet "*", facets: {store_id: {stats: true}}


Specify which fields to index with highlighting.

class Product < ActiveRecord::Base
  searchkick highlight: [:name]

Highlight the search query in the results.

bands = "cinema", fields: [:name], highlight: true

Note: The fields option is required, unless highlight options are given - see below.

View the highlighted fields with:

bands.with_details.each do |band, details|
  puts details[:highlight][:name] # "Two Door <em>Cinema</em> Club"

To change the tag, use: "cinema", fields: [:name], highlight: {tag: "<strong>"}

To highlight and search different fields, use: [master] "cinema", fields: [:name], highlight: {fields: [:description]}

Additional options, including fragment size, can be specified for each field: [master] "cinema", fields: [:name], highlight: {fields: {name: {fragment_size: 200}}}

You can find available highlight options in the Elasticsearch reference.

Similar Items

Find similar items.

product = Product.first
product.similar(fields: ["name"])

Geospatial Searches

class City < ActiveRecord::Base
  searchkick locations: ["location"]

  def search_data
    attributes.merge location: [latitude, longitude]

Reindex and search with: "san", where: {location: {near: [37, -114], within: "100mi"}} # or 160km

Bounded by a box "san", where: {location: {top_left: [38, -123], bottom_right: [37, -122]}}

Boost By Distance [master]

Boost results by distance - closer results are boosted more "san", boost_by_distance: {field: :location, origin: [37, -122]}

Also supports additional options "san", boost_by_distance: {field: :location, origin: [37, -122], function: :linear, scale: "30mi", decay: 0.5}


Searchkick supports single table inheritance.

class Dog < Animal

The parent and child model can both reindex.

Dog.reindex # equivalent

And to search, use: "*"                   # all animals "*"                      # just dogs "*", type: [Dog, Cat] # just cats and dogs

Note: The suggest option retrieves suggestions from the parent at the moment. "airbudd", suggest: true # suggestions for all animals

Debugging Queries

See how Elasticsearch tokenizes your queries with:

Product.searchkick_index.tokens("Dish Washer Soap", analyzer: "default_index")
# ["dish", "dishwash", "washer", "washersoap", "soap"]

Product.searchkick_index.tokens("dishwasher soap", analyzer: "searchkick_search")
# ["dishwashersoap"] - no match

Product.searchkick_index.tokens("dishwasher soap", analyzer: "searchkick_search2")
# ["dishwash", "soap"] - match!!

Partial matches

Product.searchkick_index.tokens("San Diego", analyzer: "searchkick_word_start_index")
# ["s", "sa", "san", "d", "di", "die", "dieg", "diego"]

Product.searchkick_index.tokens("dieg", analyzer: "searchkick_word_search")
# ["dieg"] - match!!

See the complete list of analyzers.


Searchkick uses ENV["ELASTICSEARCH_URL"] for the Elasticsearch server. This defaults to http://localhost:9200.


Choose an add-on: SearchBox, Bonsai, or Found.

# SearchBox
heroku addons:add searchbox:starter
heroku config:add ELASTICSEARCH_URL=`heroku config:get SEARCHBOX_URL`

# Bonsai
heroku addons:add bonsai
heroku config:add ELASTICSEARCH_URL=`heroku config:get BONSAI_URL`

# Found
heroku addons:add foundelasticsearch
heroku config:add ELASTICSEARCH_URL=`heroku config:get FOUNDELASTICSEARCH_URL`

Then deploy and reindex:

heroku run rake searchkick:reindex CLASS=Product


Create an initializer config/initializers/elasticsearch.rb with:


Then deploy and reindex:

rake searchkick:reindex CLASS=Product


For the best performance, add Typhoeus to your Gemfile.

gem 'typhoeus'

And create an initializer with:

require "typhoeus/adapters/faraday"
Ethon.logger ="/dev/null")

Note: Typhoeus is not available for Windows.

Automatic Failover

Create an initializer config/initializers/elasticsearch.rb with multiple hosts:

Searchkick.client = ["localhost:9200", "localhost:9201"], retry_on_failure: true)

See elasticsearch-transport for a complete list of options.


Add the following to config/environments/production.rb:

config.lograge.custom_options = lambda do |event|
  options = {}
  options[:search] = event.payload[:searchkick_runtime] if event.payload[:searchkick_runtime].to_f > 0

See Production Rails for other good practices.


Prefer to use the Elasticsearch DSL but still want awesome features like zero-downtime reindexing?

Create a custom mapping:

class Product < ActiveRecord::Base
  searchkick mappings: {
    product: {
      properties: {
        name: {type: "string", analyzer: "keyword"}

And use the query option to search:

products = query: {match: {name: "milk"}}

View the response with:


To keep the mappings and settings generated by Searchkick, use:

class Product < ActiveRecord::Base
  searchkick merge_mappings: true, mappings: {...}

To modify the query generated by Searchkick, use:

query = "2% Milk", execute: false
query.body[:query] = {match_all: {}}
products = query.execute


Reindex one record

product = Product.find 10

Remove old indices


Use a different index name

class Product < ActiveRecord::Base
  searchkick index_name: "products_v2"

Prefix the index name

class Product < ActiveRecord::Base
  searchkick index_prefix: "datakick"

Turn off callbacks temporarily

Product.disable_search_callbacks # or use Searchkick.disable_callbacks for all models
Product.enable_search_callbacks # or use Searchkick.enable_callbacks for all models

Change timeout

Searchkick.timeout = 5 # defaults to 10

Change the search method name in config/initializers/searchkick.rb

Searchkick.search_method_name = :lookup

Eager load associations "milk", include: [:brand, :stores]

Do not load models "milk", load: false

Turn off special characters

class Product < ActiveRecord::Base
  # A will not match Ä
  searchkick special_characters: false

Change import batch size

class Product < ActiveRecord::Base
  searchkick batch_size: 200 # defaults to 1000

Reindex asynchronously

class Product < ActiveRecord::Base
  searchkick callbacks: false

  def reindex_async
    # custom code to reindex

  after_commit :reindex_async
  # or for Mongoid
  # after_save :reindex_async
  # after_destroy :reindex_async

Reindex conditionally

Note: With ActiveRecord, use this feature with caution - transaction rollbacks can cause data inconstencies

class Product < ActiveRecord::Base
  searchkick callbacks: false

  # add the callbacks manually
  after_save :reindex, if: proc{|model| model.name_changed? } # use your own condition
  after_destroy :reindex

Reindex all models - Rails only

rake searchkick:reindex:all

Migrating from Tire

  1. Change search methods to and add index name in existing search calls "fruit"

    should be replaced with "fruit", index: "products"
  2. Replace tire mapping w/ searchkick method

    class Product < ActiveRecord::Base
  3. Deploy and reindex

    rake searchkick:reindex CLASS=Product # or Product.reindex in the console
  4. Once it finishes, replace search calls w/ searchkick calls


View the changelog.

Important notes are listed below.

0.6.0 and 0.7.0

If running Searchkick 0.6.0 or 0.7.0 and Elasticsearch 0.90, we recommend upgrading to Searchkick 0.6.1 or 0.7.1 to fix an issue that causes downtime when reindexing.


Before 0.3.0, locations were indexed incorrectly. When upgrading, be sure to reindex immediately.

Elasticsearch Gotchas

Inconsistent Scores

Due to the distributed nature of Elasticsearch, you can get incorrect results when the number of documents in the index is low. You can read more about it here. To fix this, do:

class Product < ActiveRecord::Base
  searchkick settings: {number_of_shards: 1}

For convenience, this is set by default in the test environment.


Thanks to Karel Minarik for Elasticsearch Ruby and Tire, Jaroslav Kalistsuk for zero downtime reindexing, and Alex Leschenko for Elasticsearch autocomplete.


  • Search multiple fields for different terms
  • Search across models
  • Search nested objects
  • Add section on testing
  • Much finer customization
  • More transparency into generated queries (for advanced use)


Everyone is encouraged to help improve this project. Here are a few ways you can help:

To get started with development and testing:

  1. Clone the repo
  2. bundle
  3. rake test