Meilisearch Rails

Meilisearch | Meilisearch Cloud | Documentation | Discord | Roadmap | Website | FAQ

Table of Contents

📖 Documentation

🤖 Compatibility with Meilisearch

🔧 Installation

gem install meilisearch-rails

source 'https://rubygems.org'
gem 'meilisearch-rails'

Run Meilisearch

🚀 Getting started

Configuration

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

bin/rails meilisearch:install

Add documents

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch do
 attribute :title, :author # only the attributes 'title', and 'author' will be sent to Meilisearch
 # all attributes will be sent to Meilisearch if block is left empty
 end
end

Automatic indexing

Basic Backend Search

# Meilisearch is typo-tolerant:
hits = Book.search('harry pottre')
hits.each do |hit|
 puts hit.title
 puts hit.author
end

Extra Configuration

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

Compatibility

⚙️ Settings

class Book < ApplicationRecord
 include Meilisearch::Rails
 meilisearch do
 searchable_attributes [:title, :author, :publisher, :description]
 filterable_attributes [:genre]
 sortable_attributes [:title]
 ranking_rules [
 'proximity',
 'typo',
 'words',
 'attribute',
 'sort',
 'exactness',
 'publication_year:desc'
 ]
 synonyms nyc: ['new york']
 # The following parameters are applied when calling the search() method:
 attributes_to_highlight ['*']
 attributes_to_crop [:description]
 crop_length 10
 faceting max_values_per_facet: 2000
 pagination max_total_hits: 1000
 proximity_precision 'byWord'
 end
end

🔍 Custom search

Book.search('Harry', attributes_to_highlight: ['*'])

harry_book.formatted # => {"id"=>"1", "name"=>"<em>Harry</em> Potter", "description"=>...

🔍 Sorted search

Book.search('*', sort: ['title:asc'])

🔍🔍 Multi search

multi_search_results = Meilisearch::Rails.multi_search(
 Book => { q: 'Harry' },
 Manga => { q: 'Attack' }
)

<% multi_search_results.each_result do |klass, results| %>
 <p><%= klass.name.pluralize %></p>
 <ul>
 <% results.each do |record| %>
 <li><%= record.title %></li>
 <% end %>
 </ul>
<% end %>
<p>Books</p>
<ul>
 <li>Harry Potter and the Philosopher's Stone</li>
 <li>Harry Potter and the Chamber of Secrets</li>
</ul>
<p>Mangas</p>
<ul>
 <li>Attack on Titan</li>
</ul>

multi_search_results = Meilisearch::Rails.multi_search(
 # scope may be a relation
 'books' => { q: 'Harry', scope: Book.all },
 # or a model
 'mangas' => { q: 'Attack', scope: Manga }
)

multi_search_results = Meilisearch::Rails.multi_search(
 'western' => { q: 'Harry', scope: Book, index_uid: 'books_production' },
 'japanese' => { q: 'Attack', scope: Manga, index_uid: 'mangas_production' }
)

Multi search the same index

query = 'hero'
multi_search_results = Meilisearch::Rails.multi_search(
 'Isekai Manga' => { q: query, scope: Manga, filters: 'genre:isekai', index_uid: 'mangas_production' }
 'Shounen Manga' => { q: query, scope: Manga, filters: 'genre:shounen', index_uid: 'mangas_production' }
 'Steampunk Manga' => { q: query, scope: Manga, filters: 'genre:steampunk', index_uid: 'mangas_production' }
)

Deprecated #each

<% multi_search_results.each do |record| %>
 <p><%= record.title %></p>
 <p><%= record.author %></p>
<% end %>
<p>Harry Potter and the Philosopher's Stone</p>
<p>J. K. Rowling</p>
<p>Harry Potter and the Chamber of Secrets</p>
<p>J. K. Rowling</p>
<p>Attack on Titan</p>
<p>Iseyama</p>

🔍🔍 Federated search

results = Meilisearch::Rails.federated_search(
 queries: [
 { q: 'Harry', scope: Book.all },
 { q: 'Attack on Titan', scope: Manga.all }
 ]
)

<ul>
 <% results.each do |record| %>
 <li><%= record.title %></li>
 <% end %>
</ul>
<ul>
 <!-- Attack on Titan appears first even though it was specified second, 
 it's ranked higher because it's a closer match -->
 <li>Attack on Titan</li>
 <li>Harry Potter and the Philosopher's Stone</li>
 <li>Harry Potter and the Chamber of Secrets</li>
</ul>

results = Meilisearch::Rails.federated_search(
 queries: {
 Book => { q: 'Harry' },
 Manga => { q: 'Attack on Titan' }
 }
)

results = Meilisearch::Rails.federated_search(
 queries: {
 'books_production' => { q: 'Harry', scope: Book.all },
 'mangas_production' => { q: 'Attack on Titan', scope: Manga.all }
 }
)

results = Meilisearch::Rails.federated_search(
 queries: {
 'potter' => { q: 'Harry', scope: Book.all, index_uid: 'books_production' },
 'titan' => { q: 'Attack on Titan', scope: Manga.all, index_uid: 'mangas_production' }
 }
)

Loading records

results = Meilisearch::Rails.federated_search(
 queries: [
 { q: 'Harry', scope: Book },
 { q: 'Attack on Titan', scope: Manga },
 ]
)

results = Meilisearch::Rails.federated_search(
 queries: {
 Book => { q: 'Harry' },
 Manga => { q: 'Attack on Titan' }
 }
)

Scoping records

results = Meilisearch::Rails.federated_search(
 queries: [
 { q: 'Harry', scope: Book.where('year <= 2006') },
 { q: 'Attack on Titan', scope: Manga.where(author: Author.find_by(name: 'Iseyama')) },
 ]
)

Specifying the search index

Pagination and other options

results = Meilisearch::Rails.federated_search(
 queries: [
 { q: 'Harry', scope: Book },
 { q: 'Attack on Titan', scope: Manga },
 ],
 federation: { offset: 10, limit: 5 }
)

Metadata

result.metadata
# {
# "processingTimeMs" => 0,
# "limit" => 20,
# "offset" => 0,
# "estimatedTotalHits" => 2,
# "semanticHitCount": 0
# }

🪛 Options

Meilisearch configuration & environment

Backend Pagination with kaminari or will_paginate

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

# controller
@hits = Book.search('harry potter')
# views
<% @hits.each do |hit| %>
 <%= hit.title %>
 <%= hit.author %>
<% end %>

<%= paginate @hits %> # if using kaminari

<%= will_paginate @hits %> # if using will_paginate

Book.search('harry potter', hits_per_page: 10)

Backend Pagination with pagy

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

class Book < ApplicationRecord
 include Meilisearch::Rails
 extend Pagy::Meilisearch
 meilisearch # ...
end

# controllers/books_controller.rb
def search
 hits = Book.pagy_search(params[:query])
 @pagy, @hits = pagy_meilisearch(hits, items: 25)
end
# views/books/search.html.rb
<%== pagy_nav(@pagy) %>

Deactivate Meilisearch in certain moments

Meilisearch::Rails.configuration = {
 meilisearch_url: 'YourMeilisearchUrl',
 meilisearch_api_key: 'YourMeilisearchAPIKey',
 active: false
}

Meilisearch::Rails.deactivate! # all the following HTTP calls will be dismissed.
# or you can pass a block to it:
Meilisearch::Rails.deactivate! do
 # every Meilisearch call here will be dismissed, no error will be raised.
 # after the block, Meilisearch state will be active. 
end

Meilisearch::Rails.activate!

Custom index_uid

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch index_uid: 'MyCustomUID'
end

Index UID according to the environment

Meilisearch::Rails.configuration = {
 meilisearch_url: 'YourMeilisearchUrl',
 meilisearch_api_key: 'YourMeilisearchAPIKey',
 per_environment: true
}

Index configuration

Custom attribute definition

class Author < ApplicationRecord
 include Meilisearch::Rails
 meilisearch do
 attribute :first_name, :last_name
 attribute :full_name do
 "#{first_name} #{last_name}"
 end
 add_attribute :full_name_reversed
 end
 def full_name_reversed
 "#{last_name} #{first_name}"
 end
 def will_save_change_to_full_name?
 will_save_change_to_first_name? || will_save_change_to_last_name?
 end
 def will_save_change_to_full_name_reversed?
 will_save_change_to_first_name? || will_save_change_to_last_name?
 end
end

Custom primary key

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch primary_key: :isbn # isbn is a column in your table definition.
end

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch primary_key: :my_custom_ms_id
 private
 def my_custom_ms_id
 "isbn_#{primary_key}" # ensure this return is unique, otherwise you'll lose data.
 end
end

Conditional indexing

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch if: :published?, unless: :premium?
 def published?
 # [...]
 end
 def premium?
 # [...]
 end
 def will_save_change_to_published?
 # return true only if you know that the 'published' state changed
 end
end

Target multiple indexes

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 PUBLIC_INDEX_UID = 'Books'
 SECURED_INDEX_UID = 'PrivateBooks'
 # store all books in index 'SECURED_INDEX_UID'
 meilisearch index_uid: SECURED_INDEX_UID do
 searchable_attributes [:title, :author]
 # store all 'public' (released and not premium) books in index 'PUBLIC_INDEX_UID'
 add_index PUBLIC_INDEX_UID, if: :public? do
 searchable_attributes [:title, :author]
 end
 end
 private
 def public?
 released? && !premium?
 end
end

Share a single index

class Cat < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch index_uid: 'Animals', primary_key: :ms_id
 private
 def ms_id
 "cat_#{primary_key}" # ensure the cats & dogs primary_keys are not conflicting
 end
end
class Dog < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch index_uid: 'Animals', primary_key: :ms_id
 private
 def ms_id
 "dog_#{primary_key}" # ensure the cats & dogs primary_keys are not conflicting
 end
end

Queues & background jobs

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch enqueue: true # ActiveJob will be triggered using a `meilisearch` queue
end

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch enqueue: :trigger_job do
 attribute :title, :author, :description
 end
 def self.trigger_job(record, remove)
 MyActiveJob.perform_later(record.id, remove)
 end
end
class MyActiveJob < ApplicationJob
 def perform(id, remove)
 if remove
 # The record has likely already been removed from your database so we cannot
 # use ActiveRecord#find to load it.
 # We access the underlying Meilisearch index object.
 Book.index.delete_document(id)
 else
 # The record should be present.
 Book.find(id).index!
 end
 end
end

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch enqueue: :trigger_sidekiq_job do
 attribute :title, :author, :description
 end
 def self.trigger_sidekiq_job(record, remove)
 MySidekiqJob.perform_async(record.id, remove)
 end
end
class MySidekiqJob
 def perform(id, remove)
 if remove
 # The record has likely already been removed from your database so we cannot
 # use ActiveRecord#find to load it.
 # We access the underlying Meilisearch index object.
 Book.index.delete_document(id)
 else
 # The record should be present.
 Book.find(id).index!
 end
 end
end

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch enqueue: :trigger_delayed_job do
 attribute :title, :author, :description
 end
 def self.trigger_delayed_job(record, remove)
 if remove
 record.delay.remove_from_index!
 else
 record.delay.index!
 end
 end
end

Relations

class Author < ActiveRecord::Base
 include Meilisearch::Rails
 has_many :books
 # If your association uses belongs_to
 # - use `touch: true`
 # - do not define an `after_save` hook
 after_save { books.each(&:touch) }
end
class Book < ActiveRecord::Base
 include Meilisearch::Rails
 belongs_to :author
 after_touch :index!
 meilisearch do
 attribute :title, :description, :publisher
 attribute :author do
 author.name
 end
 end
end

# app/models/author.rb
class Author < Sequel::Model
 include Meilisearch::Rails
 one_to_many :books
 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 be triggered
 def touch_associations
 apps.map(&:touch)
 end
 def touch
 super
 touch_associations
 end
end
# app/models/book.rb
class Book < Sequel::Model
 include Meilisearch::Rails
 many_to_one :author
 after_touch :index!
 plugin :timestamps
 plugin :touch
 meilisearch do
 attribute :title, :description, :publisher
 attribute :author do
 author.name
 end
 end
end

Sanitize attributes

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch sanitize: true
end

UTF-8 encoding

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch force_utf8_encoding: true
end

Eager loading

class Author < ActiveRecord::Base
 include Meilisearch::Rails
 has_many :books
 scope :meilisearch_import, -> { includes(:books) }
end

Manual operations

Indexing & deletion

book = Book.create!(title: 'The Little Prince', author: 'Antoine de Saint-Exupéry')
book.index!
book.remove_from_index!
book.destroy!

Book.reindex!
# You can also index a subset of your records
Book.where('updated_at > ?', 10.minutes.ago).reindex!

Book.clear_index!

Access the underlying index object

index = Book.index
# index.get_settings, index.number_of_documents

Development & testing

Exceptions

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 # Only raise exceptions in development environment.
 meilisearch raise_on_failure: Rails.env.development?
end

Testing

Synchronous testing

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch synchronous: true
end

Disable auto-indexing & auto-removal

class Book < ActiveRecord::Base
 include Meilisearch::Rails
 meilisearch auto_index: false, auto_remove: false
end

Book.without_auto_index do
 # Inside this block, auto indexing task will not run.
 1.upto(10000) { Book.create! attributes }
end

⚙️ Development workflow & contributing

👏 Credits