Meilisearch Rails

To use Meilisearch with Ruby on Rails, add the gem to your Gemfile or install it via the command line.

Requirements:

• Ruby 3.0 or later
• Rails 6.1 or later

Using Bundler (Recommended): Add this to your Gemfile:

source 'https://rubygems.org'

gem 'meilisearch-rails'

Then run bundle install.

Using gem command:

gem install meilisearch-rails

To ensure changes in a related record trigger a re-index of the parent, use touch and after_touch.

ActiveRecord Pattern:

1. Use touch: true on the belongs_to association.
2. Use an after_save hook on the parent to touch children.
3. Use after_touch :index! on the child model.

Sequel Pattern:

1. Use the touch plugin.
2. Use after_touch :index! on the child model.

# ActiveRecord
class Author < ActiveRecord::Base
  include Meilisearch::Rails
  has_many :books
  after_save { books.each(&:touch) }
end

class Book < ActiveRecord::Base
  include Meilisearch::Rails
  belongs_to :author, touch: true
  after_touch :index!

  meilisearch do
    attribute :author do
      author.name
    end
  end
end

To use kaminari or will_paginate for backend pagination, specify the :pagination_backend in your Meilisearch::Rails.configuration. Once configured, calling the search method on your model will return paginated results.

Defaults:

• Hits per page: 20
• You can override this using the hits_per_page parameter in your search call.

Meilisearch::Rails.configuration = {
  meilisearch_url: 'YourMeilisearchUrl',
  meilisearch_api_key: 'YourMeilisearchAPIKey',
  pagination_backend: :kaminari # or :will_paginate
}

# Usage in controller
@hits = Book.search('harry potter', hits_per_page: 10)

# Usage in views (kaminari)
<%= paginate @hits %>

You must configure the MEILISEARCH_HOST and MEILISEARCH_API_KEY to connect the gem to your Meilisearch instance.

You can create the configuration file manually at config/initializers/meilisearch.rb or use the provided Rake task to generate it automatically.

Manual Configuration:

Meilisearch::Rails.configuration = {
  meilisearch_url: ENV.fetch('MEILISEARCH_HOST', 'http://localhost:7700'),
  meilisearch_api_key: ENV.fetch('MEILISEARCH_API_KEY', 'YourMeilisearchAPIKey')
}

Using Rake Task:

bin/rails meilisearch:install

Advanced Configuration: You can also adjust request timeouts and retry logic:

Meilisearch::Rails.configuration = {
  meilisearch_url: 'YourMeilisearchUrl',
  meilisearch_api_key: 'YourMeilisearchAPIKey',
  timeout: 2,
  max_retries: 1,
}

You can execute Rails-related commands or interact with the Rails console inside the playground environment by running a bash session in the container.

To enter the container: docker-compose run --rm playground bash

Once inside, you can start the Rails console with: bundle exec rails c

docker-compose run --rm playground bash
root@49ebb83ca4bf:/home/app# bundle exec rails c

You can disable HTTP requests to Meilisearch to prevent errors in certain environments or moments.

• Globally via configuration: Set active: false in the configuration block.
• Programmatically: Use Meilisearch::Rails.deactivate! to disable all calls. It is recommended to use the block version to ensure the state is restored automatically.
• Manually: Use Meilisearch::Rails.activate! to re-enable connections.

# Global configuration
Meilisearch::Rails.configuration = {
  meilisearch_url: '...',
  meilisearch_api_key: '...',
  active: false
}

# Programmatic block (Recommended)
Meilisearch::Rails.deactivate! do
  # Meilisearch calls here are dismissed without error
end

# Manual activation
Meilisearch::Rails.activate!

To use pagy for pagination, follow these steps:

1. Add pagy to your Gemfile.
2. Create config/initializers/pagy.rb with require 'pagy/extras/meilisearch'.
3. Extend your model with Pagy::Meilisearch.
4. Use pagy_search in your controller and pagy_meilisearch to generate the pagination object.

Note: Do not set pagination_backend in Meilisearch::Rails.configuration when using pagy.

# config/initializers/pagy.rb
require 'pagy/extras/meilisearch'

# app/models/book.rb
class Book < ApplicationRecord
  include Meilisearch::Rails
  extend Pagy::Meilisearch
  meilisearch
end

# app/controllers/books_controller.rb
def search
  hits = Book.pagy_search(params[:query])
  @pagy, @hits = pagy_meilisearch(hits, items: 25)
end

# app/views/books/search.html.erb
<%== pagy_nav(@pagy) %>

To enable Meilisearch for a model (ActiveRecord, Mongoid, or Sequel), include the Meilisearch::Rails module and define a meilisearch block.

Important: Even if you want to use all default options, you must declare an empty meilisearch block in your model.

Defining attributes to index: By default, if the block is empty, all attributes are sent. To limit what is indexed, use the attribute method:

class Book < ActiveRecord::Base
  include Meilisearch::Rails

  meilisearch do
    attribute :title, :author # only 'title' and 'author' will be sent to Meilisearch
  end
end

Once configured, meilisearch-rails automatically synchronizes your database data with Meilisearch using model callbacks.

To set up a local development environment for the playground, use Docker. Run the following commands within a container instance created by docker-compose run --rm playground bash:

1. bundle install to install Ruby dependencies.
2. yarn install to install JavaScript dependencies.
3. bundle exec rails db:setup to initialize the database.

After setup, start the application using:

docker-compose up playground

The application will be available at http://0.0.0.0:3000.

docker-compose run --rm playground bash
# Inside the container:
bundle install
yarn install
bundle exec rails db:setup

# From your host machine:
docker-compose up playground

When configuring which records should be sent to Meilisearch, you can use :if and :unless options. The Meilisearch::Rails::Utilities.indexable? method evaluates these constraints.

Constraints can be:

• A Symbol or String: The method name to be called on the record (e.g., :published?).
• An Enumerable: A list of constraints where all must pass (logical AND).
• A Proc/Callable: A block that receives the record and returns a boolean.

If a constraint is provided as an Enumerable, the record is only considered indexable if every inner constraint evaluates to true.