Chewy Documentation

Chewy provides specialized tools for data ingestion and retrieval:

• Import: Use various import options, perform raw imports, and manage journaling.
• Querying: Execute search requests, handle pagination, use scopes, utilize scroll, and manage loading.

Chewy configuration and indexing capabilities are covered in the following documentation areas:

• Configuration: Manage client settings, update strategies, notifications, and integrations.
• Indexing: Define indexes, specify field types, use crutches, manage the compiled compose path, and perform index manipulation.

Operational tasks and testing workflows are documented as follows:

• Rake Tasks: Manage reindexing, syncing, journal management, and parallelization.
• Testing: Integration with RSpec, Minitest, and DatabaseCleaner.
• Troubleshooting: Resolving common errors, debugging imports, and addressing Elasticsearch 8 specific issues.

In Rails, Chewy automatically manages update strategies. Without Rails, you must manually manage them to avoid UndefinedUpdateStrategy errors. You have two options:

1. Wrap code in a strategy block: Use Chewy.strategy(:strategy_name) around your import or update logic.
2. Set a root strategy: Set Chewy.root_strategy = :strategy_name globally.

Common strategies include :atomic and :bypass.

# Option 1: Strategy block
Chewy.strategy(:atomic) do
  # your import / update code
end

# Option 2: Root strategy
Chewy.root_strategy = :bypass

Chewy uses a compiled compose path by default to speed up document creation. On the first import, Chewy generates a specialized __chewy_compose__ method for each index that inlines the field tree and accessors. This avoids iterating through the field list at runtime and typically results in 3-4× faster document composition.

Key features:

• Automatically handles (object), (object, crutches), or (object, crutches, context) arguments.
• Supports Symbol#to_proc shorthand.
• Transparently falls back to the legacy iterative path for edge cases like geo_point fields or ignore_blank fields.

Chewy requires an explicit strategy to prevent accidental, expensive reindexing. If update_index is called without a strategy block, it raises Chewy::UndefinedUpdateStrategy.

Example usage:

Chewy.strategy(:atomic) do
  Book.find_each { |b| b.update!(title: b.title.titleize) }
end

Strategies can be nested to allow different update behaviors for different parts of a single operation. You can use block notation or non-block notation.

Block notation:

Chewy.strategy(:atomic) do
  city1.do_update! # Grouped
  Chewy.strategy(:urgent) do
    city2.do_update! # Individual
    city3.do_update! # Individual
  end
  city4.do_update! # Grouped with city1
end

Non-block notation:

Chewy.strategy(:urgent)
city1.do_update! # index updated immediately
Chewy.strategy(:bypass)
city2.do_update! # update bypassed
Chewy.strategy.pop
city3.do_update! # index updated again

# Non-block notation example
Chewy.strategy(:urgent)
city1.do_update! # index updated
Chewy.strategy(:bypass)
city2.do_update! # update bypassed
Chewy.strategy.pop
city3.do_update! # index updated again

Object Fields

To define an object type, nest fields within a field block. This automatically sets the type to object.

field :projects do
  field :title
  field :description
end

Multi-fields

To define a multi-field (e.g., a text field with a keyword sub-field for sorting), specify a type other than object or nested in the root field and provide a block containing the sub-fields.

field :title, type: 'text' do
  field :sorted, type: 'keyword'
end
# Usage: BooksIndex.order('title.sorted': :asc)

When using the ActiveRecord adapter, you can use raw_import to bypass the overhead of full ActiveRecord model instantiation. Instead of loading full objects, Chewy can operate on raw hashes obtained directly from the database.

To use this, provide a proc to the raw_import option that converts the database hash into a lightweight object that mimics the required behavior of your index fields.

You can set this as a default in the index class or pass it explicitly to the import method.

class LightweightProduct
  def initialize(attributes)
    @attributes = attributes
  end

  def created_at
    @attributes['created_at'].tr(' ', 'T') << 'Z'
  end
end

class ProductIndex < Chewy::Index
  index_scope Product
  default_import_options raw_import: ->(hash) {
    LightweightProduct.new(hash)
  }

  field :created_at, 'datetime'
end