{"id":13427925,"url":"https://github.com/ankane/searchkick","last_synced_at":"2025-11-17T03:08:46.907Z","repository":{"id":9515630,"uuid":"11412473","full_name":"ankane/searchkick","owner":"ankane","description":"Intelligent search made easy","archived":false,"fork":false,"pushed_at":"2025-05-06T23:07:11.000Z","size":3253,"stargazers_count":6621,"open_issues_count":26,"forks_count":756,"subscribers_count":101,"default_branch":"master","last_synced_at":"2025-05-13T11:03:42.735Z","etag":null,"topics":["elasticsearch","opensearch","rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-07-15T01:44:33.000Z","updated_at":"2025-05-12T02:34:13.000Z","dependencies_parsed_at":"2023-01-13T15:24:22.762Z","dependency_job_id":"fcef6e65-9d5a-4e05-93b2-d56edbfc126c","html_url":"https://github.com/ankane/searchkick","commit_stats":{"total_commits":2745,"total_committers":126,"mean_commits":"21.785714285714285","dds":"0.41420765027322404","last_synced_commit":"250f6457d1a34e3cdf85e70a75280723ade6febd"},"previous_names":[],"tags_count":136,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fsearchkick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fsearchkick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fsearchkick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fsearchkick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankane","download_url":"https://codeload.github.com/ankane/searchkick/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253929359,"owners_count":21985802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","opensearch","rails"],"created_at":"2024-07-31T01:00:42.656Z","updated_at":"2025-11-17T03:08:46.892Z","avatar_url":"https://github.com/ankane.png","language":"Ruby","readme":"# Searchkick\n\n:rocket: Intelligent search made easy\n\n**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.\n\nSearchkick handles:\n\n- stemming - `tomatoes` matches `tomato`\n- special characters - `jalapeno` matches `jalapeño`\n- extra whitespace - `dishwasher` matches `dish washer`\n- misspellings - `zuchini` matches `zucchini`\n- custom synonyms - `pop` matches `soda`\n\nPlus:\n\n- query like SQL - no need to learn a new query language\n- reindex without downtime\n- easily personalize results for each user\n- autocomplete\n- “Did you mean” suggestions\n- supports many languages\n- works with Active Record and Mongoid\n\nCheck out [Searchjoy](https://github.com/ankane/searchjoy) for analytics and [Autosuggest](https://github.com/ankane/autosuggest) for query suggestions\n\n:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)\n\n[![Build Status](https://github.com/ankane/searchkick/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/searchkick/actions)\n\n## Contents\n\n- [Getting Started](#getting-started)\n- [Querying](#querying)\n- [Indexing](#indexing)\n- [Intelligent Search](#intelligent-search)\n- [Instant Search / Autocomplete](#instant-search--autocomplete)\n- [Aggregations](#aggregations)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [Performance](#performance)\n- [Advanced Search](#advanced)\n- [Reference](#reference)\n- [Contributing](#contributing)\n\nSearchkick 6.0 was recently released! See [how to upgrade](#upgrading)\n\n## Getting Started\n\nInstall [Elasticsearch](https://www.elastic.co/downloads/elasticsearch) or [OpenSearch](https://opensearch.org/downloads.html). For Homebrew, use:\n\n```sh\nbrew install opensearch\nbrew services start opensearch\n```\n\nAdd these lines to your application’s Gemfile:\n\n```ruby\ngem \"searchkick\"\n\ngem \"elasticsearch\"   # select one\ngem \"opensearch-ruby\" # select one\n```\n\nThe latest version works with Elasticsearch 8 and 9 and OpenSearch 2 and 3. For Elasticsearch 7 and OpenSearch 1, use version 5.5.2 and [this readme](https://github.com/ankane/searchkick/blob/v5.5.2/README.md).\n\nAdd `searchkick` to models you want to search.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick\nend\n```\n\nAdd data to the search index.\n\n```ruby\nProduct.reindex\n```\n\nAnd to query, use:\n\n```ruby\nproducts = Product.search(\"apples\")\nproducts.each do |product|\n  puts product.name\nend\n```\n\nSearchkick supports the complete [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) and [OpenSearch Search API](https://opensearch.org/docs/latest/opensearch/rest-api/search/). As your search becomes more advanced, we recommend you use the [search server DSL](#advanced) for maximum flexibility.\n\n## Querying\n\nQuery like SQL\n\n```ruby\nProduct.search(\"apples\").where(in_stock: true).limit(10).offset(50)\n```\n\nSearch specific fields\n\n```ruby\nfields(:name, :brand)\n```\n\nWhere\n\n```ruby\nwhere(store_id: 1, expires_at: Time.now..)\n```\n\n[These types of filters are supported](#filtering)\n\nOrder\n\n```ruby\norder(_score: :desc) # most relevant first - default\n```\n\n[All of these sort options are supported](https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html)\n\nLimit / offset\n\n```ruby\nlimit(20).offset(40)\n```\n\nSelect\n\n```ruby\nselect(:name)\n```\n\n[These source filtering options are supported](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#source-filtering)\n\n### Results\n\nSearches return a `Searchkick::Relation` object. This responds like an array to most methods.\n\n```ruby\nresults = Product.search(\"milk\")\nresults.size\nresults.any?\nresults.each { |result| ... }\n```\n\nBy default, ids are fetched from the search server and records are fetched from your database. To fetch everything from the search server, use:\n\n```ruby\nProduct.search(\"apples\").load(false)\n```\n\nGet total results\n\n```ruby\nresults.total_count\n```\n\nGet the time the search took (in milliseconds)\n\n```ruby\nresults.took\n```\n\nGet the full response from the search server\n\n```ruby\nresults.response\n```\n\n**Note:** By default, Elasticsearch and OpenSearch [limit paging](#deep-paging) to the first 10,000 results for performance. This applies to the total count as well.\n\n### Filtering\n\nEqual\n\n```ruby\nwhere(store_id: 1)\n```\n\nNot equal\n\n```ruby\nwhere.not(store_id: 2)\n```\n\nGreater than (`gt`), less than (`lt`), greater than or equal (`gte`), less than or equal (`lte`)\n\n```ruby\nwhere(expires_at: {gt: Time.now})\n```\n\nRange\n\n```ruby\nwhere(orders_count: 1..10)\n```\n\nIn\n\n```ruby\nwhere(aisle_id: [25, 30])\n```\n\nNot in\n\n```ruby\nwhere.not(aisle_id: [25, 30])\n```\n\nContains all\n\n```ruby\nwhere(user_ids: {all: [1, 3]})\n```\n\nLike\n\n```ruby\nwhere(category: {like: \"%frozen%\"})\n```\n\nCase-insensitive like\n\n```ruby\nwhere(category: {ilike: \"%frozen%\"})\n```\n\nRegular expression\n\n```ruby\nwhere(category: /frozen .+/)\n```\n\nPrefix\n\n```ruby\nwhere(category: {prefix: \"frozen\"})\n```\n\nExists\n\n```ruby\nwhere(store_id: {exists: true})\n```\n\nCombine filters with OR\n\n```ruby\nwhere(_or: [{in_stock: true}, {backordered: true}])\n```\n\n### Boosting\n\nBoost important fields\n\n```ruby\nfields(\"title^10\", \"description\")\n```\n\nBoost by the value of a field (field must be numeric)\n\n```ruby\nboost_by(:orders_count) # give popular documents a little boost\nboost_by(orders_count: {factor: 10}) # default factor is 1\n```\n\nBoost matching documents\n\n```ruby\nboost_where(user_id: 1)\nboost_where(user_id: {value: 1, factor: 100}) # default factor is 1000\nboost_where(user_id: [{value: 1, factor: 100}, {value: 2, factor: 200}])\n```\n\nBoost by recency\n\n```ruby\nboost_by_recency(created_at: {scale: \"7d\", decay: 0.5})\n```\n\nYou can also boost by:\n\n- [Conversions](#intelligent-search)\n- [Distance](#boost-by-distance)\n\n### Get Everything\n\nUse a `*` for the query.\n\n```ruby\nProduct.search(\"*\")\n```\n\n### Pagination\n\nPlays nicely with kaminari and will_paginate.\n\n```ruby\n# controller\n@products = Product.search(\"milk\").page(params[:page]).per_page(20)\n```\n\nView with kaminari\n\n```erb\n\u003c%= paginate @products %\u003e\n```\n\nView with will_paginate\n\n```erb\n\u003c%= will_paginate @products %\u003e\n```\n\n### Partial Matches\n\nBy default, results must match all words in the query.\n\n```ruby\nProduct.search(\"fresh honey\") # fresh AND honey\n```\n\nTo change this, use:\n\n```ruby\nProduct.search(\"fresh honey\").operator(\"or\") # fresh OR honey\n```\n\nBy default, results must match the entire word - `back` will not match `backpack`. You can change this behavior with:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick word_start: [:name]\nend\n```\n\nAnd to search (after you reindex):\n\n```ruby\nProduct.search(\"back\").fields(:name).match(:word_start)\n```\n\nAvailable options are:\n\nOption | Matches | Example\n--- | --- | ---\n`:word` | entire word | `apple` matches `apple`\n`:word_start` | start of word | `app` matches `apple`\n`:word_middle` | any part of word | `ppl` matches `apple`\n`:word_end` | end of word | `ple` matches `apple`\n`:text_start` | start of text | `gre` matches `green apple`, `app` does not match\n`:text_middle` | any part of text | `een app` matches `green apple`\n`:text_end` | end of text | `ple` matches `green apple`, `een` does not match\n\nThe default is `:word`. The most matches will happen with `:word_middle`.\n\nTo specify different matching for different fields, use:\n\n```ruby\nProduct.search(query).fields({name: :word_start}, {brand: :word_middle})\n```\n\n### Exact Matches\n\nTo match a field exactly (case-sensitive), use:\n\n```ruby\nProduct.search(query).fields({name: :exact})\n```\n\n### Phrase Matches\n\nTo only match the exact order, use:\n\n```ruby\nProduct.search(\"fresh honey\").match(:phrase)\n```\n\n### Stemming and Language\n\nSearchkick stems words by default for better matching. `apple` and `apples` both stem to `appl`, so searches for either term will have the same matches.\n\nSearchkick defaults to English for stemming. To change this, use:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick language: \"german\"\nend\n```\n\nSee the [list of languages](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-stemmer-tokenfilter.html#analysis-stemmer-tokenfilter-configure-parms). A few languages require plugins:\n\n- `chinese` - [analysis-ik plugin](https://github.com/medcl/elasticsearch-analysis-ik)\n- `chinese2` - [analysis-smartcn plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html)\n- `japanese` - [analysis-kuromoji plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html)\n- `korean` - [analysis-openkoreantext plugin](https://github.com/open-korean-text/elasticsearch-analysis-openkoreantext)\n- `korean2` - [analysis-nori plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-nori.html)\n- `polish` - [analysis-stempel plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-stempel.html)\n- `ukrainian` - [analysis-ukrainian plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/7.4/analysis-ukrainian.html)\n- `vietnamese` - [analysis-vietnamese plugin](https://github.com/duydo/elasticsearch-analysis-vietnamese)\n\nYou can also use a Hunspell dictionary for stemming.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick stemmer: {type: \"hunspell\", locale: \"en_US\"}\nend\n```\n\nDisable stemming with:\n\n```ruby\nclass Image \u003c ApplicationRecord\n  searchkick stem: false\nend\n```\n\nExclude certain words from stemming with:\n\n```ruby\nclass Image \u003c ApplicationRecord\n  searchkick stem_exclusion: [\"apples\"]\nend\n```\n\nOr change how words are stemmed:\n\n```ruby\nclass Image \u003c ApplicationRecord\n  searchkick stemmer_override: [\"apples =\u003e other\"]\nend\n```\n\n### Synonyms\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick search_synonyms: [[\"pop\", \"soda\"], [\"burger\", \"hamburger\"]]\nend\n```\n\nCall `Product.reindex` after changing synonyms. Synonyms are applied at search time before stemming, and can be a single word or multiple words.\n\nFor directional synonyms, use:\n\n```ruby\nsearch_synonyms: [\"lightbulb =\u003e halogenlamp\"]\n```\n\n### Dynamic Synonyms\n\nThe above approach works well when your synonym list is static, but in practice, this is often not the case. When you analyze search conversions, you often want to add new synonyms without a full reindex. We recommend placing synonyms in a file on the search server (in the `config` directory). This allows you to reload synonyms without reindexing.\n\n```txt\npop, soda\nburger, hamburger\n```\n\nThen use:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick search_synonyms: \"synonyms.txt\"\nend\n```\n\nAnd reload with:\n\n```ruby\nProduct.search_index.reload_synonyms\n```\n\n### Misspellings\n\nBy default, Searchkick handles misspelled queries by returning results with an [edit distance](https://en.wikipedia.org/wiki/Levenshtein_distance) of one.\n\nYou can change this with:\n\n```ruby\nProduct.search(\"zucini\").misspellings(edit_distance: 2) # zucchini\n```\n\nTo prevent poor precision and improve performance for correctly spelled queries (which should be a majority for most applications), Searchkick can first perform a search without misspellings, and if there are too few results, perform another with them.\n\n```ruby\nProduct.search(\"zuchini\").misspellings(below: 5)\n```\n\nIf there are fewer than 5 results, a 2nd search is performed with misspellings enabled. The result of this query is returned.\n\nTurn off misspellings with:\n\n```ruby\nProduct.search(\"zuchini\").misspellings(false) # no zucchini\n```\n\nSpecify which fields can include misspellings with:\n\n```ruby\nProduct.search(\"zucini\").fields(:name, :color).misspellings(fields: [:name])\n```\n\n\u003e When doing this, you must also specify fields to search\n\n### Bad Matches\n\nIf a user searches `butter`, they may also get results for `peanut butter`. To prevent this, use:\n\n```ruby\nProduct.search(\"butter\").exclude(\"peanut butter\")\n```\n\nYou can map queries and terms to exclude with:\n\n```ruby\nexclude_queries = {\n  \"butter\" =\u003e [\"peanut butter\"],\n  \"cream\" =\u003e [\"ice cream\", \"whipped cream\"]\n}\n\nProduct.search(query).exclude(exclude_queries[query])\n```\n\nYou can demote results by boosting by a factor less than one:\n\n```ruby\nProduct.search(\"butter\").boost_where(category: {value: \"pantry\", factor: 0.5})\n```\n\n### Emoji\n\nSearch :ice_cream::cake: and get `ice cream cake`!\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"gemoji-parser\"\n```\n\nAnd use:\n\n```ruby\nProduct.search(\"🍨🍰\").emoji\n```\n\n## Indexing\n\nControl what data is indexed with the `search_data` method. Call `Product.reindex` after changing this method.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  belongs_to :department\n\n  def search_data\n    {\n      name: name,\n      department_name: department.name,\n      on_sale: sale_price.present?\n    }\n  end\nend\n```\n\nSearchkick uses `find_in_batches` to import documents. To eager load associations, use the `search_import` scope.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  scope :search_import, -\u003e { includes(:department) }\nend\n```\n\nBy default, all records are indexed. To control which records are indexed, use the `should_index?` method.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  def should_index?\n    active # only index active records\n  end\nend\n```\n\nIf a reindex is interrupted, you can resume it with:\n\n```ruby\nProduct.reindex(resume: true)\n```\n\nFor large data sets, try [parallel reindexing](#parallel-reindexing).\n\n### To Reindex, or Not to Reindex\n\n#### Reindex\n\n- when you install or upgrade searchkick\n- change the `search_data` method\n- change the `searchkick` method\n\n#### No need to reindex\n\n- app starts\n\n### Strategies\n\nThere are four strategies for keeping the index synced with your database.\n\n1. Inline (default)\n\n  Anytime a record is inserted, updated, or deleted\n\n2. Asynchronous\n\n  Use background jobs for better performance\n\n  ```ruby\n  class Product \u003c ApplicationRecord\n    searchkick callbacks: :async\n  end\n  ```\n\n  Jobs are added to a queue named `searchkick`.\n\n3. Queuing\n\n  Push ids of records that need updated to a queue and reindex in the background in batches. This is more performant than the asynchronous method, which updates records individually. See [how to set up](#queuing).\n\n4. Manual\n\n  Turn off automatic syncing\n\n  ```ruby\n  class Product \u003c ApplicationRecord\n    searchkick callbacks: false\n  end\n  ```\n\n  And reindex a record or relation manually.\n\n  ```ruby\n  product.reindex\n  # or\n  store.products.reindex(mode: :async)\n  ```\n\nYou can also do bulk updates.\n\n```ruby\nSearchkick.callbacks(:bulk) do\n  Product.find_each(\u0026:update_fields)\nend\n```\n\nOr temporarily skip updates.\n\n```ruby\nSearchkick.callbacks(false) do\n  Product.find_each(\u0026:update_fields)\nend\n```\n\nOr override the model’s strategy.\n\n```ruby\nproduct.reindex(mode: :async) # :inline or :queue\n```\n\n### Associations\n\nData is **not** automatically synced when an association is updated. If this is desired, add a callback to reindex:\n\n```ruby\nclass Image \u003c ApplicationRecord\n  belongs_to :product\n\n  after_commit :reindex_product\n\n  def reindex_product\n    product.reindex\n  end\nend\n```\n\n### Default Scopes\n\nIf you have a default scope that filters records, use the `should_index?` method to exclude them from indexing:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  default_scope { where(deleted_at: nil) }\n\n  def should_index?\n    deleted_at.nil?\n  end\nend\n```\n\nIf you want to index and search filtered records, set:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick unscope: true\nend\n```\n\n## Intelligent Search\n\nThe best starting point to improve your search **by far** is to track searches and conversions. [Searchjoy](https://github.com/ankane/searchjoy) makes it easy.\n\n```ruby\nProduct.search(\"apple\").track(user_id: current_user.id)\n```\n\n[See the docs](https://github.com/ankane/searchjoy) for how to install and use. Focus on top searches with a low conversion rate.\n\nSearchkick can then use the conversion data to learn what users are looking for. If a user searches for “ice cream” and adds Ben \u0026 Jerry’s Chunky Monkey to the cart (our conversion metric at Instacart), that item gets a little more weight for similar searches. This can make a huge difference on the quality of your search.\n\nAdd conversion data with:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  has_many :conversions, class_name: \"Searchjoy::Conversion\", as: :convertable\n  has_many :searches, class_name: \"Searchjoy::Search\", through: :conversions\n\n  searchkick conversions_v2: [:conversions] # name of field\n\n  def search_data\n    {\n      name: name,\n      conversions: searches.group(:query).distinct.count(:user_id)\n      # {\"ice cream\" =\u003e 234, \"chocolate\" =\u003e 67, \"cream\" =\u003e 2}\n    }\n  end\nend\n```\n\nReindex and set up a cron job to add new conversions daily. For zero downtime deployment, temporarily set `conversions_v2(false)` in your search calls until the data is reindexed.\n\n### Performant Conversions\n\nA performant way to do conversions is to cache them to prevent N+1 queries. For Postgres, create a migration with:\n\n```ruby\nadd_column :products, :search_conversions, :jsonb\n```\n\nFor MySQL, use `:json`, and for others, use `:text` with a [JSON serializer](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html).\n\nNext, update your model. Create a separate method for conversion data so you can use [partial reindexing](#partial-reindexing).\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick conversions_v2: [:conversions]\n\n  def search_data\n    {\n      name: name,\n      category: category\n    }.merge(conversions_data)\n  end\n\n  def conversions_data\n    {\n      conversions: search_conversions || {}\n    }\n  end\nend\n```\n\nDeploy and reindex your data. For zero downtime deployment, temporarily set `conversions_v2(false)` in your search calls until the data is reindexed.\n\n```ruby\nProduct.reindex\n```\n\nThen, create a job to update the conversions column and reindex records with new conversions. Here’s one you can use for Searchjoy:\n\n```ruby\nclass UpdateConversionsJob \u003c ApplicationJob\n  def perform(class_name, since: nil, update: true, reindex: true)\n    model = Searchkick.load_model(class_name)\n\n    # get records that have a recent conversion\n    recently_converted_ids =\n      Searchjoy::Conversion.where(convertable_type: class_name, created_at: since..)\n        .order(:convertable_id).distinct.pluck(:convertable_id)\n\n    # split into batches\n    recently_converted_ids.in_groups_of(1000, false) do |ids|\n      if update\n        # fetch conversions\n        conversions =\n          Searchjoy::Conversion.where(convertable_id: ids, convertable_type: class_name)\n            .joins(:search).where.not(searchjoy_searches: {user_id: nil})\n            .group(:convertable_id, :query).distinct.count(:user_id)\n\n        # group by record\n        conversions_by_record = {}\n        conversions.each do |(id, query), count|\n          (conversions_by_record[id] ||= {})[query] = count\n        end\n\n        # update conversions column\n        model.transaction do\n          conversions_by_record.each do |id, conversions|\n            model.where(id: id).update_all(search_conversions: conversions)\n          end\n        end\n      end\n\n      if reindex\n        # reindex conversions data\n        model.where(id: ids).reindex(:conversions_data, ignore_missing: true)\n      end\n    end\n  end\nend\n```\n\nRun the job:\n\n```ruby\nUpdateConversionsJob.perform_now(\"Product\")\n```\n\nAnd set it up to run daily.\n\n```ruby\nUpdateConversionsJob.perform_later(\"Product\", since: 1.day.ago)\n```\n\n## Personalized Results\n\nOrder results differently for each user. For example, show a user’s previously purchased products before other results.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  def search_data\n    {\n      name: name,\n      orderer_ids: orders.pluck(:user_id) # boost this product for these users\n    }\n  end\nend\n```\n\nReindex and search with:\n\n```ruby\nProduct.search(\"milk\").boost_where(orderer_ids: current_user.id)\n```\n\n## Instant Search / Autocomplete\n\nAutocomplete predicts what a user will type, making the search experience faster and easier.\n\n![Autocomplete](https://gist.githubusercontent.com/ankane/b6988db2802aca68a589b31e41b44195/raw/40febe948427e5bc53ec4e5dc248822855fef76f/autocomplete.png)\n\n**Note:** To autocomplete on search terms rather than results, check out [Autosuggest](https://github.com/ankane/autosuggest).\n\n**Note 2:** 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).\n\nFirst, 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 fast queries.\n\n```ruby\nclass Movie \u003c ApplicationRecord\n  searchkick word_start: [:title, :director]\nend\n```\n\nReindex and search with:\n\n```ruby\nMovie.search(\"jurassic pa\").fields(:title).match(:word_start)\n```\n\nUse a front-end library like [typeahead.js](https://twitter.github.io/typeahead.js/) to show the results.\n\n#### Here’s how to make it work with Rails\n\nFirst, add a route and controller action.\n\n```ruby\nclass MoviesController \u003c ApplicationController\n  def autocomplete\n    render json: Movie.search(params[:query]).fields(\"title^5\", \"director\")\n      .match(:word_start).limit(10).load(false).misspellings(below: 5).map(\u0026:title)\n  end\nend\n```\n\n**Note:** Use `load(false)` and `misspellings(below: n)` (or `misspellings(false)`) for best performance.\n\nThen add the search box and JavaScript code to a view.\n\n```html\n\u003cinput type=\"text\" id=\"query\" name=\"query\" /\u003e\n\n\u003cscript src=\"jquery.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"typeahead.bundle.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  var movies = new Bloodhound({\n    datumTokenizer: Bloodhound.tokenizers.whitespace,\n    queryTokenizer: Bloodhound.tokenizers.whitespace,\n    remote: {\n      url: '/movies/autocomplete?query=%QUERY',\n      wildcard: '%QUERY'\n    }\n  });\n  $('#query').typeahead(null, {\n    source: movies\n  });\n\u003c/script\u003e\n```\n\n## Suggestions\n\n![Suggest](https://gist.githubusercontent.com/ankane/b6988db2802aca68a589b31e41b44195/raw/40febe948427e5bc53ec4e5dc248822855fef76f/recursion.png)\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick suggest: [:name] # fields to generate suggestions\nend\n```\n\nReindex and search with:\n\n```ruby\nproducts = Product.search(\"peantu butta\").suggest\nproducts.suggestions # [\"peanut butter\"]\n```\n\n## Aggregations\n\n[Aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html) provide aggregated search data.\n\n![Aggregations](https://gist.githubusercontent.com/ankane/b6988db2802aca68a589b31e41b44195/raw/40febe948427e5bc53ec4e5dc248822855fef76f/facets.png)\n\n```ruby\nproducts = Product.search(\"chuck taylor\").aggs(:product_type, :gender, :brand)\nproducts.aggs\n```\n\nBy default, `where` conditions apply to aggregations.\n\n```ruby\nProduct.search(\"wingtips\").where(color: \"brandy\").aggs(:size)\n# aggregations for brandy wingtips are returned\n```\n\nChange this with:\n\n```ruby\nProduct.search(\"wingtips\").where(color: \"brandy\").aggs(:size).smart_aggs(false)\n# aggregations for all wingtips are returned\n```\n\nSet `where` conditions for each aggregation separately with:\n\n```ruby\nProduct.search(\"wingtips\").aggs(size: {where: {color: \"brandy\"}})\n```\n\nLimit\n\n```ruby\nProduct.search(\"apples\").aggs(store_id: {limit: 10})\n```\n\nOrder\n\n```ruby\nProduct.search(\"wingtips\").aggs(color: {order: {\"_key\" =\u003e \"asc\"}}) # alphabetically\n```\n\n[All of these options are supported](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order)\n\nRanges\n\n```ruby\nprice_ranges = [{to: 20}, {from: 20, to: 50}, {from: 50}]\nProduct.search(\"*\").aggs(price: {ranges: price_ranges})\n```\n\nMinimum document count\n\n```ruby\nProduct.search(\"apples\").aggs(store_id: {min_doc_count: 2})\n```\n\nScript support\n\n```ruby\nProduct.search(\"*\").aggs(color: {script: {source: \"'Color: ' + _value\"}})\n```\n\nDate histogram\n\n```ruby\nProduct.search(\"pear\").aggs(products_per_year: {date_histogram: {field: :created_at, interval: :year}})\n```\n\nFor other aggregation types, including sub-aggregations, use `body_options`:\n\n```ruby\nProduct.search(\"orange\").body_options(aggs: {price: {histogram: {field: :price, interval: 10}}})\n```\n\n## Highlight\n\nSpecify which fields to index with highlighting.\n\n```ruby\nclass Band \u003c ApplicationRecord\n  searchkick highlight: [:name]\nend\n```\n\nHighlight the search query in the results.\n\n```ruby\nbands = Band.search(\"cinema\").highlight\n```\n\nView the highlighted fields with:\n\n```ruby\nbands.with_highlights.each do |band, highlights|\n  highlights[:name] # \"Two Door \u003cem\u003eCinema\u003c/em\u003e Club\"\nend\n```\n\nTo change the tag, use:\n\n```ruby\nBand.search(\"cinema\").highlight(tag: \"\u003cstrong\u003e\")\n```\n\nTo highlight and search different fields, use:\n\n```ruby\nBand.search(\"cinema\").fields(:name).highlight(fields: [:description])\n```\n\nBy default, the entire field is highlighted. To get small snippets instead, use:\n\n```ruby\nbands = Band.search(\"cinema\").highlight(fragment_size: 20)\nbands.with_highlights(multiple: true).each do |band, highlights|\n  highlights[:name].join(\" and \")\nend\n```\n\nAdditional options can be specified for each field:\n\n```ruby\nBand.search(\"cinema\").fields(:name).highlight(fields: {name: {fragment_size: 200}})\n```\n\nYou can find available highlight options in the [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/highlighting.html) or [OpenSearch](https://opensearch.org/docs/latest/search-plugins/searching-data/highlight/) reference.\n\n## Similar Items\n\nFind similar items\n\n```ruby\nproduct = Product.first\nproduct.similar.fields(:name).where(size: \"12 oz\")\n```\n\n## Geospatial Searches\n\n```ruby\nclass Restaurant \u003c ApplicationRecord\n  searchkick locations: [:location]\n\n  def search_data\n    attributes.merge(location: {lat: latitude, lon: longitude})\n  end\nend\n```\n\nReindex and search with:\n\n```ruby\nRestaurant.search(\"pizza\").where(location: {near: {lat: 37, lon: -114}, within: \"100mi\"}) # or 160km\n```\n\nBounded by a box\n\n```ruby\nRestaurant.search(\"sushi\").where(location: {top_left: {lat: 38, lon: -123}, bottom_right: {lat: 37, lon: -122}})\n```\n\n**Note:** `top_right` and `bottom_left` also work\n\nBounded by a polygon\n\n```ruby\nRestaurant.search(\"dessert\").where(location: {geo_polygon: {points: [{lat: 38, lon: -123}, {lat: 39, lon: -123}, {lat: 37, lon: 122}]}})\n```\n\n### Boost By Distance\n\nBoost results by distance - closer results are boosted more\n\n```ruby\nRestaurant.search(\"noodles\").boost_by_distance(location: {origin: {lat: 37, lon: -122}})\n```\n\nAlso supports [additional options](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html#function-decay)\n\n```ruby\nRestaurant.search(\"wings\").boost_by_distance(location: {origin: {lat: 37, lon: -122}, function: \"linear\", scale: \"30mi\", decay: 0.5})\n```\n\n### Geo Shapes\n\nYou can also index and search geo shapes.\n\n```ruby\nclass Restaurant \u003c ApplicationRecord\n  searchkick geo_shape: [:bounds]\n\n  def search_data\n    attributes.merge(\n      bounds: {\n        type: \"envelope\",\n        coordinates: [{lat: 4, lon: 1}, {lat: 2, lon: 3}]\n      }\n    )\n  end\nend\n```\n\nSee the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html) for details.\n\nFind shapes intersecting with the query shape\n\n```ruby\nRestaurant.search(\"soup\").where(bounds: {geo_shape: {type: \"polygon\", coordinates: [[{lat: 38, lon: -123}, ...]]}})\n```\n\nFalling entirely within the query shape\n\n```ruby\nRestaurant.search(\"salad\").where(bounds: {geo_shape: {type: \"circle\", relation: \"within\", coordinates: {lat: 38, lon: -123}, radius: \"1km\"}})\n```\n\nNot touching the query shape\n\n```ruby\nRestaurant.search(\"burger\").where(bounds: {geo_shape: {type: \"envelope\", relation: \"disjoint\", coordinates: [{lat: 38, lon: -123}, {lat: 37, lon: -122}]}})\n```\n\n## Inheritance\n\nSearchkick supports single table inheritance.\n\n```ruby\nclass Dog \u003c Animal\nend\n```\n\nIn your parent model, set:\n\n```ruby\nclass Animal \u003c ApplicationRecord\n  searchkick inheritance: true\nend\n```\n\nThe parent and child model can both reindex.\n\n```ruby\nAnimal.reindex\nDog.reindex # equivalent, all animals reindexed\n```\n\nAnd to search, use:\n\n```ruby\nAnimal.search(\"*\")                # all animals\nDog.search(\"*\")                   # just dogs\nAnimal.search(\"*\").type(Dog, Cat) # just cats and dogs\n```\n\n**Notes:**\n\n1. The `suggest` option retrieves suggestions from the parent at the moment.\n\n    ```ruby\n    Dog.search(\"airbudd\").suggest # suggestions for all animals\n    ```\n2. This relies on a `type` field that is automatically added to the indexed document. Be wary of defining your own `type` field in `search_data`, as it will take precedence.\n\n## Debugging Queries\n\nTo help with debugging queries, you can use:\n\n```ruby\nProduct.search(\"soap\").debug\n```\n\nThis prints useful info to `stdout`.\n\nSee how the search server scores your queries with:\n\n```ruby\nProduct.search(\"soap\").explain.response\n```\n\nSee how the search server tokenizes your queries with:\n\n```ruby\nProduct.search_index.tokens(\"Dish Washer Soap\", analyzer: \"searchkick_index\")\n# [\"dish\", \"dishwash\", \"washer\", \"washersoap\", \"soap\"]\n\nProduct.search_index.tokens(\"dishwasher soap\", analyzer: \"searchkick_search\")\n# [\"dishwashersoap\"] - no match\n\nProduct.search_index.tokens(\"dishwasher soap\", analyzer: \"searchkick_search2\")\n# [\"dishwash\", \"soap\"] - match!!\n```\n\nPartial matches\n\n```ruby\nProduct.search_index.tokens(\"San Diego\", analyzer: \"searchkick_word_start_index\")\n# [\"s\", \"sa\", \"san\", \"d\", \"di\", \"die\", \"dieg\", \"diego\"]\n\nProduct.search_index.tokens(\"dieg\", analyzer: \"searchkick_word_search\")\n# [\"dieg\"] - match!!\n```\n\nSee the [complete list of analyzers](lib/searchkick/index_options.rb#L36).\n\n## Testing\n\nAs you iterate on your search, it’s a good idea to add tests.\n\nFor performance, only enable Searchkick callbacks for the tests that need it.\n\n### Rails\n\nAdd to your `test/test_helper.rb`:\n\n```ruby\nmodule ActiveSupport\n  class TestCase\n    parallelize_setup do |worker|\n      Searchkick.index_suffix = worker\n\n      # reindex models for parallel tests\n      Product.reindex\n    end\n  end\nend\n\n# reindex models for non-parallel tests\nProduct.reindex\n\n# and disable callbacks\nSearchkick.disable_callbacks\n```\n\nAnd use:\n\n```ruby\nclass ProductTest \u003c ActiveSupport::TestCase\n  setup do\n    Searchkick.enable_callbacks\n  end\n\n  teardown do\n    Searchkick.disable_callbacks\n  end\n\n  test \"search\" do\n    Product.create!(name: \"Apple\")\n    Product.search_index.refresh\n    assert_equal [\"Apple\"], Product.search(\"apple\").map(\u0026:name)\n  end\nend\n```\n\n### Minitest\n\nAdd to your `test/test_helper.rb`:\n\n```ruby\n# reindex models\nProduct.reindex\n\n# and disable callbacks\nSearchkick.disable_callbacks\n```\n\nAnd use:\n\n```ruby\nclass ProductTest \u003c Minitest::Test\n  def setup\n    Searchkick.enable_callbacks\n  end\n\n  def teardown\n    Searchkick.disable_callbacks\n  end\n\n  def test_search\n    Product.create!(name: \"Apple\")\n    Product.search_index.refresh\n    assert_equal [\"Apple\"], Product.search(\"apple\").map(\u0026:name)\n  end\nend\n```\n\n### RSpec\n\nAdd to your `spec/spec_helper.rb`:\n\n```ruby\nRSpec.configure do |config|\n  config.before(:suite) do\n    # reindex models\n    Product.reindex\n\n    # and disable callbacks\n    Searchkick.disable_callbacks\n  end\n\n  config.around(:each, search: true) do |example|\n    Searchkick.callbacks(nil) do\n      example.run\n    end\n  end\nend\n```\n\nAnd use:\n\n```ruby\ndescribe Product, search: true do\n  it \"searches\" do\n    Product.create!(name: \"Apple\")\n    Product.search_index.refresh\n    assert_equal [\"Apple\"], Product.search(\"apple\").map(\u0026:name)\n  end\nend\n```\n\n### Factory Bot\n\nDefine a trait for each model:\n\n```ruby\nFactoryBot.define do\n  factory :product do\n    trait :reindex do\n      after(:create) do |product, _|\n        product.reindex(refresh: true)\n      end\n    end\n  end\nend\n```\n\nAnd use:\n\n```ruby\nFactoryBot.create(:product, :reindex)\n```\n\n### GitHub Actions\n\nCheck out [setup-elasticsearch](https://github.com/ankane/setup-elasticsearch) for an easy way to install Elasticsearch:\n\n```yml\n    - uses: ankane/setup-elasticsearch@v1\n```\n\nAnd [setup-opensearch](https://github.com/ankane/setup-opensearch) for an easy way to install OpenSearch:\n\n```yml\n    - uses: ankane/setup-opensearch@v1\n```\n\n## Deployment\n\nFor the search server, Searchkick uses `ENV[\"ELASTICSEARCH_URL\"]` for Elasticsearch and `ENV[\"OPENSEARCH_URL\"]` for OpenSearch. This defaults to `http://localhost:9200`.\n\n- [Elastic Cloud](#elastic-cloud)\n- [Amazon OpenSearch Service](#amazon-opensearch-service)\n- [Heroku](#heroku)\n- [Self-Hosted and Other](#self-hosted-and-other)\n\n### Elastic Cloud\n\nCreate an initializer `config/initializers/elasticsearch.rb` with:\n\n```ruby\nENV[\"ELASTICSEARCH_URL\"] = \"https://user:password@host:port\"\n```\n\nThen deploy and reindex:\n\n```sh\nrake searchkick:reindex:all\n```\n\n### Amazon OpenSearch Service\n\nCreate an initializer `config/initializers/opensearch.rb` with:\n\n```ruby\nENV[\"OPENSEARCH_URL\"] = \"https://es-domain-1234.us-east-1.es.amazonaws.com:443\"\n```\n\nTo use signed requests, include in your Gemfile:\n\n```ruby\ngem \"faraday_middleware-aws-sigv4\"\n```\n\nand add to your initializer:\n\n```ruby\nSearchkick.aws_credentials = {\n  access_key_id: ENV[\"AWS_ACCESS_KEY_ID\"],\n  secret_access_key: ENV[\"AWS_SECRET_ACCESS_KEY\"],\n  region: \"us-east-1\"\n}\n```\n\nThen deploy and reindex:\n\n```sh\nrake searchkick:reindex:all\n```\n\n### Heroku\n\nChoose an add-on: [Bonsai](https://elements.heroku.com/addons/bonsai), [SearchBox](https://elements.heroku.com/addons/searchbox), or [Elastic Cloud](https://elements.heroku.com/addons/foundelasticsearch).\n\nFor Elasticsearch on Bonsai:\n\n```sh\nheroku addons:create bonsai\nheroku config:set ELASTICSEARCH_URL=`heroku config:get BONSAI_URL`\n```\n\nFor OpenSearch on Bonsai:\n\n```sh\nheroku addons:create bonsai --engine=opensearch\nheroku config:set OPENSEARCH_URL=`heroku config:get BONSAI_URL`\n```\n\nFor SearchBox:\n\n```sh\nheroku addons:create searchbox:starter\nheroku config:set ELASTICSEARCH_URL=`heroku config:get SEARCHBOX_URL`\n```\n\nFor Elastic Cloud (previously Found):\n\n```sh\nheroku addons:create foundelasticsearch\nheroku addons:open foundelasticsearch\n```\n\nVisit the Shield page and reset your password. You’ll need to add the username and password to your url. Get the existing url with:\n\n```sh\nheroku config:get FOUNDELASTICSEARCH_URL\n```\n\nAnd add `elastic:password@` right after `https://` and add port `9243` at the end:\n\n```sh\nheroku config:set ELASTICSEARCH_URL=https://elastic:password@12345.us-east-1.aws.found.io:9243\n```\n\nThen deploy and reindex:\n\n```sh\nheroku run rake searchkick:reindex:all\n```\n\n### Self-Hosted and Other\n\nCreate an initializer with:\n\n```ruby\nENV[\"ELASTICSEARCH_URL\"] = \"https://user:password@host:port\"\n# or\nENV[\"OPENSEARCH_URL\"] = \"https://user:password@host:port\"\n```\n\nThen deploy and reindex:\n\n```sh\nrake searchkick:reindex:all\n```\n\n### Data Protection\n\nWe recommend encrypting data at rest and in transit (even inside your own network). This is especially important if you send [personal data](https://en.wikipedia.org/wiki/Personally_identifiable_information) of your users to the search server.\n\nBonsai, Elastic Cloud, and Amazon OpenSearch Service all support encryption at rest and HTTPS.\n\n### Automatic Failover\n\nCreate an initializer with multiple hosts:\n\n```ruby\nENV[\"ELASTICSEARCH_URL\"] = \"https://user:password@host1,https://user:password@host2\"\n# or\nENV[\"OPENSEARCH_URL\"] = \"https://user:password@host1,https://user:password@host2\"\n```\n\n### Client Options\n\nCreate an initializer with:\n\n```ruby\nSearchkick.client_options[:reload_connections] = true\n```\n\nSee the docs for [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/advanced-config.html) or [Opensearch](https://rubydoc.info/gems/opensearch-transport#configuration) for a complete list of options.\n\n### Lograge\n\nAdd the following to `config/environments/production.rb`:\n\n```ruby\nconfig.lograge.custom_options = lambda do |event|\n  options = {}\n  options[:search] = event.payload[:searchkick_runtime] if event.payload[:searchkick_runtime].to_f \u003e 0\n  options\nend\n```\n\nSee [Production Rails](https://github.com/ankane/production_rails) for other good practices.\n\n## Performance\n\n### JSON Generation\n\nIncrease performance with faster JSON generation. Add to your Gemfile:\n\n```ruby\ngem \"json\", \"\u003e= 2.10.2\"\n```\n\nAnd create an initializer with:\n\n```ruby\nclass SearchSerializer\n  CODER = JSON::Coder.new { |v, _| v.is_a?(Time) ? v.as_json : v }\n\n  def dump(object)\n    CODER.generate(object)\n  end\nend\n\nElasticsearch::API.settings[:serializer] = SearchSerializer.new\n# or\nOpenSearch::API.settings[:serializer] = SearchSerializer.new\n```\n\n### Persistent HTTP Connections\n\nSignificantly increase performance with persistent HTTP connections. Add [Typhoeus](https://github.com/typhoeus/typhoeus) to your Gemfile and it’ll automatically be used.\n\n```ruby\ngem \"typhoeus\"\n```\n\nTo reduce log noise, create an initializer with:\n\n```ruby\nEthon.logger = Logger.new(nil)\n```\n\n### Searchable Fields\n\nBy default, all string fields are searchable (can be used in `fields` option). Speed up indexing and reduce index size by only making some fields searchable.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick searchable: [:name]\nend\n```\n\n### Filterable Fields\n\nBy default, all string fields are filterable (can be used in `where` option). Speed up indexing and reduce index size by only making some fields filterable.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick filterable: [:brand]\nend\n```\n\n**Note:** Non-string fields are always filterable and should not be passed to this option.\n\n### Parallel Reindexing\n\nFor large data sets, you can use background jobs to parallelize reindexing.\n\n```ruby\nProduct.reindex(mode: :async)\n# {index_name: \"products_production_20250111210018065\"}\n```\n\nOnce the jobs complete, promote the new index with:\n\n```ruby\nProduct.search_index.promote(index_name)\n```\n\nYou can optionally track the status with Redis:\n\n```ruby\nSearchkick.redis = Redis.new\n```\n\nAnd use:\n\n```ruby\nSearchkick.reindex_status(index_name)\n```\n\nYou can also have Searchkick wait for reindexing to complete\n\n```ruby\nProduct.reindex(mode: :async, wait: true)\n```\n\nYou can use your background job framework to control concurrency. For Solid Queue, create an initializer with:\n\n```ruby\nmodule SearchkickBulkReindexConcurrency\n  extend ActiveSupport::Concern\n\n  included do\n    limits_concurrency to: 3, key: \"\"\n  end\nend\n\nRails.application.config.after_initialize do\n  Searchkick::BulkReindexJob.include(SearchkickBulkReindexConcurrency)\nend\n```\n\nThis will allow only 3 jobs to run at once.\n\n### Refresh Interval\n\nYou can specify a longer refresh interval while reindexing to increase performance.\n\n```ruby\nProduct.reindex(mode: :async, refresh_interval: \"30s\")\n```\n\n**Note:** This only makes a noticeable difference with parallel reindexing.\n\nWhen promoting, have it restored to the value in your mapping (defaults to `1s`).\n\n```ruby\nProduct.search_index.promote(index_name, update_refresh_interval: true)\n```\n\n### Queuing\n\nPush ids of records needing reindexing to a queue and reindex in bulk for better performance. First, set up Redis in an initializer. We recommend using [connection_pool](https://github.com/mperham/connection_pool).\n\n```ruby\nSearchkick.redis = ConnectionPool.new { Redis.new }\n```\n\nAnd ask your models to queue updates.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick callbacks: :queue\nend\n```\n\nThen, set up a background job to run.\n\n```ruby\nSearchkick::ProcessQueueJob.perform_later(class_name: \"Product\")\n```\n\nYou can check the queue length with:\n\n```ruby\nProduct.search_index.reindex_queue.length\n```\n\nFor more tips, check out [Keeping Elasticsearch in Sync](https://www.elastic.co/blog/found-keeping-elasticsearch-in-sync).\n\n### Routing\n\nSearchkick supports [routing](https://www.elastic.co/blog/customizing-your-document-routing), which can significantly speed up searches.\n\n```ruby\nclass Business \u003c ApplicationRecord\n  searchkick routing: true\n\n  def search_routing\n    city_id\n  end\nend\n```\n\nReindex and search with:\n\n```ruby\nBusiness.search(\"ice cream\").routing(params[:city_id])\n```\n\n### Partial Reindexing\n\nReindex a subset of attributes to reduce time spent generating search data and cut down on network traffic.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  def search_data\n    {\n      name: name,\n      category: category\n    }.merge(prices_data)\n  end\n\n  def prices_data\n    {\n      price: price,\n      sale_price: sale_price\n    }\n  end\nend\n```\n\nAnd use:\n\n```ruby\nProduct.reindex(:prices_data)\n```\n\nIgnore errors for missing documents with:\n\n```ruby\nProduct.reindex(:prices_data, ignore_missing: true)\n```\n\n## Advanced\n\nSearchkick makes it easy to use the Elasticsearch or OpenSearch DSL on its own.\n\n### Advanced Mapping\n\nCreate a custom mapping:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick mappings: {\n    properties: {\n      name: {type: \"keyword\"}\n    }\n  }\nend\n```\n**Note:** If you use a custom mapping, you'll need to use [custom searching](#advanced-search) as well.\n\nTo keep the mappings and settings generated by Searchkick, use:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick merge_mappings: true, mappings: {...}\nend\n```\n\n### Advanced Search\n\nAnd use the `body` option to search:\n\n```ruby\nproducts = Product.search.body(query: {match: {name: \"milk\"}})\n```\n\nView the response with:\n\n```ruby\nproducts.response\n```\n\nTo modify the query generated by Searchkick, use:\n\n```ruby\nproducts = Product.search(\"milk\").body_options(min_score: 1)\n```\n\nor\n\n```ruby\nproducts =\n  Product.search(\"apples\") do |body|\n    body[:min_score] = 1\n  end\n```\n\n### Client\n\nTo access the `Elasticsearch::Client` or `OpenSearch::Client` directly, use:\n\n```ruby\nSearchkick.client\n```\n\n## Multi Search\n\nTo batch search requests for performance, use:\n\n```ruby\nproducts = Product.search(\"snacks\")\ncoupons = Coupon.search(\"snacks\")\nSearchkick.multi_search([products, coupons])\n```\n\nThen use `products` and `coupons` as typical results.\n\n**Note:** Errors are not raised as with single requests. Use the `error` method on each query to check for errors.\n\n## Multiple Models\n\nSearch across multiple models with:\n\n```ruby\nSearchkick.search(\"milk\").models(Product, Category)\n```\n\nBoost specific models with:\n\n```ruby\nindices_boost(Category =\u003e 2, Product =\u003e 1)\n```\n\n## Multi-Tenancy\n\nCheck out [this great post](https://www.tiagoamaro.com.br/2014/12/11/multi-tenancy-with-searchkick/) on the [Apartment](https://github.com/influitive/apartment) gem. Follow a similar pattern if you use another gem.\n\n## Scroll API\n\nSearchkick also supports the [scroll API](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results). Scrolling is not intended for real time user requests, but rather for processing large amounts of data.\n\n```ruby\nProduct.search(\"*\").scroll(\"1m\") do |batch|\n  # process batch ...\nend\n```\n\nYou can also scroll batches manually.\n\n```ruby\nproducts = Product.search(\"*\").scroll(\"1m\")\nwhile products.any?\n  # process batch ...\n\n  products = products.scroll\nend\n\nproducts.clear_scroll\n```\n\n## Deep Paging\n\nBy default, Elasticsearch and OpenSearch limit paging to the first 10,000 results. [Here’s why](https://www.elastic.co/guide/en/elasticsearch/guide/current/pagination.html). We don’t recommend changing this, but if you really need all results, you can use:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick deep_paging: true\nend\n```\n\nIf you just need an accurate total count, you can instead use:\n\n```ruby\nProduct.search(\"pears\").body_options(track_total_hits: true)\n```\n\n## Nested Data\n\nTo query nested data, use dot notation.\n\n```ruby\nProduct.search(\"san\").fields(\"store.city\").where(\"store.zip_code\" =\u003e 12345)\n```\n\n## Nearest Neighbor Search\n\n*Available for Elasticsearch 8.6+ and OpenSearch 2.4+*\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick knn: {embedding: {dimensions: 3, distance: \"cosine\"}}\nend\n```\n\nAlso supports `euclidean` and `inner_product`\n\nReindex and search with:\n\n```ruby\nProduct.search.knn(field: :embedding, vector: [1, 2, 3]).limit(10)\n```\n\n### HNSW Options\n\nNearest neighbor search uses [HNSW](https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world) for indexing.\n\nSpecify `m` and `ef_construction`\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick knn: {embedding: {dimensions: 3, distance: \"cosine\", m: 16, ef_construction: 100}}\nend\n```\n\nSpecify `ef_search`\n\n```ruby\nProduct.search.knn(field: :embedding, vector: [1, 2, 3], ef_search: 40).limit(10)\n```\n\n## Semantic Search\n\nFirst, add [nearest neighbor search](#nearest-neighbor-search) to your model\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick knn: {embedding: {dimensions: 768, distance: \"cosine\"}}\nend\n```\n\nGenerate an embedding for each record (you can use an external service or a library like [Informers](https://github.com/ankane/informers))\n\n```ruby\nembed = Informers.pipeline(\"embedding\", \"Snowflake/snowflake-arctic-embed-m-v1.5\")\nembed_options = {model_output: \"sentence_embedding\", pooling: \"none\"} # specific to embedding model\n\nProduct.find_each do |product|\n  embedding = embed.(product.name, **embed_options)\n  product.update!(embedding: embedding)\nend\n```\n\nFor search, generate an embedding for the query (the query prefix is specific to the [embedding model](https://huggingface.co/Snowflake/snowflake-arctic-embed-m-v1.5))\n\n```ruby\nquery_prefix = \"Represent this sentence for searching relevant passages: \"\nquery_embedding = embed.(query_prefix + query, **embed_options)\n```\n\nAnd perform nearest neighbor search\n\n```ruby\nProduct.search.knn(field: :embedding, vector: query_embedding).limit(20)\n```\n\nSee a [full example](examples/semantic.rb)\n\n## Hybrid Search\n\nPerform keyword search and semantic search in parallel\n\n```ruby\nkeyword_search = Product.search(query).limit(20)\nsemantic_search = Product.search.knn(field: :embedding, vector: query_embedding).limit(20)\nSearchkick.multi_search([keyword_search, semantic_search])\n```\n\nTo combine the results, use Reciprocal Rank Fusion (RRF)\n\n```ruby\nSearchkick::Reranking.rrf(keyword_search, semantic_search).first(5)\n```\n\nOr a reranking model\n\n```ruby\nrerank = Informers.pipeline(\"reranking\", \"mixedbread-ai/mxbai-rerank-xsmall-v1\")\nresults = (keyword_search.to_a + semantic_search.to_a).uniq\nrerank.(query, results.map(\u0026:name)).first(5).map { |v| results[v[:doc_id]] }\n```\n\nSee a [full example](examples/hybrid.rb)\n\n## Reference\n\nReindex one record\n\n```ruby\nproduct = Product.find(1)\nproduct.reindex\n```\n\nReindex multiple records\n\n```ruby\nProduct.where(store_id: 1).reindex\n```\n\nReindex associations\n\n```ruby\nstore.products.reindex\n```\n\nRemove old indices\n\n```ruby\nProduct.search_index.clean_indices\n```\n\nUse custom settings\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick settings: {number_of_shards: 3}\nend\n```\n\nUse a different index name\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick index_name: \"products_v2\"\nend\n```\n\nUse a dynamic index name\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick index_name: -\u003e { \"#{name.tableize}-#{I18n.locale}\" }\nend\n```\n\nPrefix the index name\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick index_prefix: \"datakick\"\nend\n```\n\nFor all models\n\n```ruby\nSearchkick.index_prefix = \"datakick\"\n```\n\nUse a different term for boosting by conversions\n\n```ruby\nProduct.search(\"banana\").conversions_v2(term: \"organic banana\")\n```\n\nDefine multiple conversion fields\n\n```ruby\nclass Product \u003c ApplicationRecord\n  has_many :searches, class_name: \"Searchjoy::Search\"\n\n  searchkick conversions_v2: [\"unique_conversions\", \"total_conversions\"]\n\n  def search_data\n    {\n      name: name,\n      unique_conversions: searches.group(:query).distinct.count(:user_id),\n      total_conversions: searches.group(:query).count\n    }\n  end\nend\n```\n\nAnd specify which to use\n\n```ruby\nProduct.search(\"banana\") # boost by both fields (default)\nProduct.search(\"banana\").conversions_v2(\"total_conversions\") # only boost by total_conversions\nProduct.search(\"banana\").conversions_v2(false) # no conversion boosting\n```\n\nChange timeout\n\n```ruby\nSearchkick.timeout = 15 # defaults to 10\n```\n\nSet a lower timeout for searches\n\n```ruby\nSearchkick.search_timeout = 3\n```\n\nChange the search method name\n\n```ruby\nSearchkick.search_method_name = :lookup\n```\n\nChange the queue name\n\n```ruby\nSearchkick.queue_name = :search_reindex # defaults to :searchkick\n```\n\nChange the queue name or priority for a model\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick job_options: {queue: \"critical\", priority: 10}\nend\n```\n\nChange the queue name or priority for a specific call\n\n```ruby\nProduct.reindex(mode: :async, job_options: {queue: \"critical\", priority: 10})\n```\n\nChange the parent job\n\n```ruby\nSearchkick.parent_job = \"ApplicationJob\" # defaults to \"ActiveJob::Base\"\n```\n\nEager load associations\n\n```ruby\nProduct.search(\"milk\").includes(:brand, :stores)\n```\n\nEager load different associations by model\n\n```ruby\nSearchkick.search(\"*\").models(Product, Store).model_includes(Product =\u003e [:store], Store =\u003e [:product])\n```\n\nRun additional scopes on results\n\n```ruby\nProduct.search(\"milk\").scope_results(-\u003e(r) { r.with_attached_images })\n```\n\nSet opaque id for slow logs\n\n```ruby\nProduct.search(\"milk\").opaque_id(\"some-id\")\n# or\nSearchkick.multi_search(searches, opaque_id: \"some-id\")\n```\n\nSpecify default fields to search\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick default_fields: [:name]\nend\n```\n\nTurn off special characters\n\n```ruby\nclass Product \u003c ApplicationRecord\n  # A will not match Ä\n  searchkick special_characters: false\nend\n```\n\nTurn on stemming for conversions\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick stem_conversions: true\nend\n```\n\nMake search case-sensitive\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick case_sensitive: true\nend\n```\n\n**Note:** If misspellings are enabled (default), results with a single character case difference will match. Turn off misspellings if this is not desired.\n\nChange import batch size\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick batch_size: 200 # defaults to 1000\nend\n```\n\nCreate index without importing\n\n```ruby\nProduct.reindex(import: false)\n```\n\nUse a different id\n\n```ruby\nclass Product \u003c ApplicationRecord\n  def search_document_id\n    custom_id\n  end\nend\n```\n\nAdd [request parameters](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html#search-search-api-query-params) like `search_type`\n\n```ruby\nProduct.search(\"carrots\").request_params(search_type: \"dfs_query_then_fetch\")\n```\n\nSet options across all models\n\n```ruby\nSearchkick.model_options = {\n  batch_size: 200\n}\n```\n\nReindex conditionally\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick callback_options: {if: :search_data_changed?}\n\n  def search_data_changed?\n    previous_changes.include?(\"name\")\n  end\nend\n```\n\nReindex all models - Rails only\n\n```sh\nrake searchkick:reindex:all\n```\n\nTurn on misspellings after a certain number of characters\n\n```ruby\nProduct.search(\"api\").misspellings(prefix_length: 2) # api, apt, no ahi\n```\n\nBigDecimal values are indexed as floats by default so they can be used for boosting. Convert them to strings to keep full precision.\n\n```ruby\nclass Product \u003c ApplicationRecord\n  def search_data\n    {\n      units: units.to_s(\"F\")\n    }\n  end\nend\n```\n\n## Gotchas\n\n### Consistency\n\nElasticsearch and OpenSearch are eventually consistent, meaning it can take up to a second for a change to reflect in search. You can use the `refresh` method to have it show up immediately.\n\n```ruby\nproduct.save!\nProduct.search_index.refresh\n```\n\n### Inconsistent Scores\n\nDue to the distributed nature of Elasticsearch and OpenSearch, you can get incorrect results when the number of documents in the index is low. You can [read more about it here](https://www.elastic.co/blog/understanding-query-then-fetch-vs-dfs-query-then-fetch). To fix this, do:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick settings: {number_of_shards: 1}\nend\n```\n\nFor convenience, this is set by default in the test environment.\n\n## Upgrading\n\n### 6.0\n\nSearchkick 6 brings a new query builder API:\n\n```ruby\nProduct.search(\"apples\").where(in_stock: true).limit(10).offset(50)\n```\n\nAll existing options can be used as methods, or you can continue to use the existing API.\n\nThis release also significantly improves the performance of searches when using conversions. To upgrade without downtime, add `conversions_v2` to your model and an additional field to `search_data`:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick conversions: [:conversions], conversions_v2: [:conversions_v2]\n\n  def search_data\n    conversions = searches.group(:query).distinct.count(:user_id)\n    {\n      conversions: conversions,\n      conversions_v2: conversions\n    }\n  end\nend\n```\n\nReindex, then remove `conversions`:\n\n```ruby\nclass Product \u003c ApplicationRecord\n  searchkick conversions_v2: [:conversions_v2]\n\n  def search_data\n    {\n      conversions_v2: searches.group(:query).distinct.count(:user_id)\n    }\n  end\nend\n```\n\nOther improvements include the option to ignore errors for missing documents with partial reindexing and more customization for background jobs. Check out the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md) for the full list of changes.\n\n## History\n\nView the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md)\n\n## Thanks\n\nThanks to Karel Minarik for [Elasticsearch Ruby](https://github.com/elasticsearch/elasticsearch-ruby) and [Tire](https://github.com/karmi/retire), Jaroslav Kalistsuk for [zero downtime reindexing](https://gist.github.com/jarosan/3124884), and Alex Leschenko for [Elasticsearch autocomplete](https://github.com/leschenko/elasticsearch_autocomplete).\n\n## Contributing\n\nEveryone is encouraged to help improve this project. Here are a few ways you can help:\n\n- [Report bugs](https://github.com/ankane/searchkick/issues)\n- Fix bugs and [submit pull requests](https://github.com/ankane/searchkick/pulls)\n- Write, clarify, or fix documentation\n- Suggest or add new features\n\nTo get started with development:\n\n```sh\ngit clone https://github.com/ankane/searchkick.git\ncd searchkick\nbundle install\nbundle exec rake test\n```\n\nFeel free to open an issue to get feedback on your idea before spending too much time on it.\n","funding_links":[],"categories":["Searching","Active Record Plugins","Search","Ruby","数据搜索引擎","搜索","Gems"],"sub_categories":["Omniauth","Rails Search","资源传输下载","Articles"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fsearchkick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankane%2Fsearchkick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fsearchkick/lists"}