meilisearch-rails 0.14.3 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: babcf0719c23af9294b52e76c7549cacf9baeb578221c18cf2be53db5bbeaaa1
-  data.tar.gz: 33aee866b13502a67657a5803d395fbcebe737456e2f45e812b1312074b5b7df
+  metadata.gz: 317b4503e3616fe8f309ac194c2eb85a902222edda8ae58824c53f081280a0de
+  data.tar.gz: f9ef605f39f533307b5af4d6204c8fd19fb5d49dd507e72010d7d5458b37e066
 SHA512:
-  metadata.gz: 230fc45c263f5aa10ff137eba952673eed221a33bae3ae1c5cb7cfe35adbdc50d9399feaeaf20c7766fd78bf0c29ed440de08880de8f5c2e9d7889bcf6d107c5
-  data.tar.gz: 18bbbc7a7fd9cb64bf1f2429234c10c56b1c3c88a044909a3b01f1e4ceb276449f61cc6ceb52148131c44b8d5dfbeeb09438953dff15ff9857b3d9e7864e2ccd
+  metadata.gz: 1f2d3137a16b624704eeadb64d86c32e0c87864abf7af1fb7df19d8acf90d74ee57db5df1707c073c80a73aec99964519bcace556a6ce8f40828d179b74971f4
+  data.tar.gz: 0a56e1651b062fc45fcde8e4206d2f08c21af07882bfaaeb80d928fe3cf4fa112a5e2102127f7d598120c978076bbacf2c2681c2452cca0406ac5ac15a899d2a

data/README.md

@@ -38,6 +38,7 @@
 - [⚙️ Settings](#️-settings)
 - [🔍 Custom search](#-custom-search)
 - [🔍🔍 Multi search](#-multi-search)
+- [🔍🔍 Federated search](#-federated-search)
 - [🪛 Options](#-options)
   - [Meilisearch configuration & environment](#meilisearch-configuration--environment)
   - [Pagination with `kaminari` or `will_paginate`](#backend-pagination-with-kaminari-or-will_paginate-)
@@ -98,7 +99,7 @@ gem 'meilisearch-rails'
 Create a new file `config/initializers/meilisearch.rb` to setup your `MEILISEARCH_HOST` and `MEILISEARCH_API_KEY`
 
 ```ruby
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: ENV.fetch('MEILISEARCH_HOST', 'http://localhost:7700'),
   meilisearch_api_key: ENV.fetch('MEILISEARCH_API_KEY', 'YourMeilisearchAPIKey')
 }
@@ -120,7 +121,7 @@ The following code will create a `Book` index and add search capabilities to you
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch do
     attribute :title, :author # only the attributes 'title', and 'author' will be sent to Meilisearch
@@ -154,7 +155,7 @@ Requests made to Meilisearch may timeout and retry. To adapt the behavior to
 your needs, you can change the parameters during configuration:
 
 ```ruby
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: 'YourMeilisearchUrl',
   meilisearch_api_key: 'YourMeilisearchAPIKey',
   timeout: 2,
@@ -172,7 +173,7 @@ You can configure the index settings by adding them inside the `meilisearch` blo
 
 ```ruby
 class Book < ApplicationRecord
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch do
     searchable_attributes [:title, :author, :publisher, :description]
@@ -235,7 +236,7 @@ Book.search('*', sort: ['title:asc'])
 Meilisearch supports searching multiple models at the same time (see [🔍 Custom search](#-custom-search) for search options):
 
 ```ruby
-multi_search_results = MeiliSearch::Rails.multi_search(
+multi_search_results = Meilisearch::Rails.multi_search(
   Book => { q: 'Harry' },
   Manga => { q: 'Attack' }
 )
@@ -265,12 +266,14 @@ Use `#each_result` to loop through pairs of your provided keys and the results:
 </ul>
 ```
 
-Records are loaded when the keys are models, or when `:class_name` option is passed:
+Records are loaded when the keys are models, or when `:scope` option is passed:
 
 ```ruby
-multi_search_results = MeiliSearch::Rails.multi_search(
-  'books' => { q: 'Harry', class_name: 'Book' },
-  'mangas' => { q: 'Attack', class_name: 'Manga' }
+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 }
 )
 ```
 
@@ -279,9 +282,9 @@ Otherwise, hashes are returned.
 The index to search is inferred from the model if the key is a model, if the key is a string the key is assumed to be the index unless the `:index_uid` option is passed:
 
 ```ruby
-multi_search_results = MeiliSearch::Rails.multi_search(
-  'western' => { q: 'Harry', class_name: 'Book', index_uid: 'books_production' },
-  'japanese' => { q: 'Attack', class_name: 'Manga', index_uid: 'mangas_production' }
+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' }
 )
 ```
 
@@ -291,10 +294,11 @@ You can search the same index multiple times by specifying `:index_uid`:
 
 ```ruby
 query = 'hero'
-multi_search_results = MeiliSearch::Rails.multi_search(
-  'Isekai Manga' => { q: query, class_name: 'Manga', filters: 'genre:isekai', index_uid: 'mangas_production' }
-  'Shounen Manga' => { q: query, class_name: 'Manga', filters: 'genre:shounen', index_uid: 'mangas_production' }
-  'Steampunk Manga' => { q: query, class_name: 'Manga', filters: 'genre:steampunk', index_uid: 'mangas_production' }
+
+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' }
 )
 ```
 
@@ -320,6 +324,172 @@ But this has been deprecated in favor of **federated search**.
 
 See the [official multi search documentation](https://www.meilisearch.com/docs/reference/api/multi_search).
 
+## 🔍🔍 Federated search
+
+Federated search is similar to multi search, except that results are not grouped but sorted by ranking rules.
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: [
+    { q: 'Harry', scope: Book.all },
+    { q: 'Attack on Titan', scope: Manga.all }
+  ]
+)
+```
+
+An enumerable `FederatedSearchResult` is returned, which can be iterated through with `#each`:
+
+```erb
+<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>
+```
+
+The `queries` parameter may be a multi-search style hash with keys that are either classes, index names, or neither:
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: {
+    Book => { q: 'Harry' },
+    Manga => { q: 'Attack on Titan' }
+  }
+)
+```
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: {
+    'books_production' => { q: 'Harry', scope: Book.all },
+    'mangas_production' => { q: 'Attack on Titan', scope: Manga.all }
+  }
+)
+```
+
+```ruby
+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 <!-- omit in toc -->
+
+Records are loaded when the `:scope` option is passed (may be a model or a relation), 
+or when a hash query is used with models as keys:
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: [
+    { q: 'Harry', scope: Book },
+    { q: 'Attack on Titan', scope: Manga },
+  ]
+)
+```
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: {
+    Book => { q: 'Harry' },
+    Manga => { q: 'Attack on Titan' }
+  }
+)
+```
+
+If the model is not provided, hashes are returned!
+
+### Scoping records <!-- omit in toc -->
+
+Any relation passed as `:scope` is used as the starting point when loading records:
+
+```ruby
+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 <!-- omit in toc -->
+
+In order of precedence, to figure out which index to search, Meilisearch Rails will check:
+
+1. `index_uid` options
+   ```ruby
+   results = Meilisearch::Rails.federated_search(
+     queries: [
+       # Searching the 'fantasy_books' index
+       { q: 'Harry', scope: Book, index_uid: 'fantasy_books' },
+     ]
+   )
+   ```
+2. The index associated with the model
+   ```ruby
+   results = Meilisearch::Rails.federated_search(
+     queries: [
+       # Searching the index associated with the Book model
+       # i. e. Book.index.uid
+       { q: 'Harry', scope: Book },
+     ]
+   )
+   ```
+3. The key when using hash queries
+   ```ruby
+   results = Meilisearch::Rails.federated_search(
+     queries: {
+       # Searching index 'books_production'
+       books_production: { q: 'Harry', scope: Book },
+     }
+   )
+   ```
+
+### Pagination and other options <!-- omit in toc -->
+
+In addition to queries, federated search also accepts `:federation` parameters which allow for finer control of the search:
+
+```ruby
+results = Meilisearch::Rails.federated_search(
+  queries: [
+    { q: 'Harry', scope: Book },
+    { q: 'Attack on Titan', scope: Manga },
+  ],
+  federation: { offset: 10, limit: 5 }
+)
+```
+See a full list of accepted options in [the meilisearch documentation](https://www.meilisearch.com/docs/reference/api/multi_search#federation).
+
+#### Metadata <!-- omit in toc -->
+
+The returned result from a federated search includes a `.metadata` attribute you can use to access everything other than the search hits:
+
+```ruby
+result.metadata
+# {
+#   "processingTimeMs" => 0,
+#   "limit" => 20,
+#   "offset" => 0,
+#   "estimatedTotalHits" => 2,
+#   "semanticHitCount": 0
+# }
+```
+
+The metadata contains facet stats and pagination stats, among others. See the full response in [the documentation](https://www.meilisearch.com/docs/reference/api/multi_search#federated-multi-search-requests).
+
+More details on federated search (such as available `federation:` options) can be found on [the official multi search documentation](https://www.meilisearch.com/docs/reference/api/multi_search).
+
 ## 🪛 Options
 
 ### Meilisearch configuration & environment
@@ -333,7 +503,7 @@ This gem supports:
 Specify the `:pagination_backend` in the configuration file:
 
 ```ruby
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: 'YourMeilisearchUrl',
   meilisearch_api_key: 'YourMeilisearchAPIKey',
   pagination_backend: :kaminari # :will_paginate
@@ -382,7 +552,7 @@ Then in your model you must extend `Pagy::Meilisearch`:
 
 ```rb
 class Book < ApplicationRecord
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
   extend Pagy::Meilisearch
 
   meilisearch # ...
@@ -403,7 +573,7 @@ end
 <%== pagy_nav(@pagy) %>
 ```
 
-:warning: There is no need to set `pagination_backend` in the configuration block `MeiliSearch::Rails.configuration` for `pagy`.
+:warning: There is no need to set `pagination_backend` in the configuration block `Meilisearch::Rails.configuration` for `pagy`.
 
 Check [`ddnexus/pagy`](https://ddnexus.github.io/pagy/extras/meilisearch) for more information.
 
@@ -415,7 +585,7 @@ you have multiple ways to achieve this.
 By adding `active: false` in the configuration initializer:
 
 ```ruby
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: 'YourMeilisearchUrl',
   meilisearch_api_key: 'YourMeilisearchAPIKey',
   active: false
@@ -425,11 +595,11 @@ MeiliSearch::Rails.configuration = {
 Or you can disable programmatically:
 
 ```ruby
-MeiliSearch::Rails.deactivate! # all the following HTTP calls will be dismissed.
+Meilisearch::Rails.deactivate! # all the following HTTP calls will be dismissed.
 
 # or you can pass a block to it:
 
-MeiliSearch::Rails.deactivate! do
+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
@@ -438,7 +608,7 @@ end
 You can also activate if you deactivated earlier:
 
 ```ruby
-MeiliSearch::Rails.activate!
+Meilisearch::Rails.activate!
 ```
 
 :warning: These calls are persistent, so prefer to use the method with the block. This way, you will not forget to activate it afterward.
@@ -449,7 +619,7 @@ By default, the **index_uid** will be the class name, e.g. `Book`. You can custo
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch index_uid: 'MyCustomUID'
 end
@@ -460,7 +630,7 @@ end
 You can suffix the index UID with the current Rails environment by setting it globally:
 
 ```ruby
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: 'YourMeilisearchUrl',
   meilisearch_api_key: 'YourMeilisearchAPIKey',
   per_environment: true
@@ -479,7 +649,7 @@ You can add a custom attribute by using the `add_attribute` option or by using a
 
 ```ruby
 class Author < ApplicationRecord
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch do
     attribute :first_name, :last_name
@@ -511,7 +681,7 @@ Note that the primary key must return a **unique value** otherwise your data cou
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch primary_key: :isbn # isbn is a column in your table definition.
 end
@@ -522,7 +692,7 @@ will be used as the reference to the document when Meilisearch needs it.
 
 ```rb
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch primary_key: :my_custom_ms_id
 
@@ -541,7 +711,7 @@ As soon as you use those constraints, `add_documents` and `delete_documents` cal
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch if: :published?, unless: :premium?
 
@@ -564,7 +734,7 @@ You can index a record in several indexes using the `add_index` option:
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   PUBLIC_INDEX_UID = 'Books'
   SECURED_INDEX_UID = 'PrivateBooks'
@@ -593,7 +763,7 @@ You may want to share an index between several models. You'll need to ensure you
 
 ```ruby
 class Cat < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch index_uid: 'Animals', primary_key: :ms_id
 
@@ -605,7 +775,7 @@ class Cat < ActiveRecord::Base
 end
 
 class Dog < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch index_uid: 'Animals', primary_key: :ms_id
 
@@ -623,7 +793,7 @@ You can configure the auto-indexing & auto-removal process to use a queue to per
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch enqueue: true # ActiveJob will be triggered using a `meilisearch` queue
 end
@@ -637,7 +807,7 @@ With **ActiveJob**:
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch enqueue: :trigger_job do
     attribute :title, :author, :description
@@ -667,7 +837,7 @@ With [**Sidekiq**](https://github.com/mperham/sidekiq):
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch enqueue: :trigger_sidekiq_job do
     attribute :title, :author, :description
@@ -697,7 +867,7 @@ With [**DelayedJob**](https://github.com/collectiveidea/delayed_job):
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch enqueue: :trigger_delayed_job do
     attribute :title, :author, :description
@@ -721,7 +891,7 @@ Extend a change to a related record.
 
 ```ruby
 class Author < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   has_many :books
   # If your association uses belongs_to
@@ -731,7 +901,7 @@ class Author < ActiveRecord::Base
 end
 
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   belongs_to :author
   after_touch :index!
@@ -750,7 +920,7 @@ With **Sequel**, you can use the `touch` plugin to propagate changes.
 ```ruby
 # app/models/author.rb
 class Author < Sequel::Model
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   one_to_many :books
 
@@ -772,7 +942,7 @@ end
 
 # app/models/book.rb
 class Book < Sequel::Model
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   many_to_one :author
   after_touch :index!
@@ -795,7 +965,7 @@ You can strip all HTML tags from your attributes with the `sanitize` option.
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch sanitize: true
 end
@@ -807,7 +977,7 @@ You can force the UTF-8 encoding of all your attributes using the `force_utf8_en
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch force_utf8_encoding: true
 end
@@ -819,7 +989,7 @@ You can eager load associations using `meilisearch_import` scope.
 
 ```ruby
 class Author < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   has_many :books
 
@@ -872,7 +1042,7 @@ You can disable exceptions that could be raised while trying to reach Meilisearc
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   # Only raise exceptions in development environment.
   meilisearch raise_on_failure: Rails.env.development?
@@ -887,7 +1057,7 @@ You can force indexing and removing to be synchronous by setting the following o
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch synchronous: true
 end
@@ -900,7 +1070,7 @@ You can disable auto-indexing and auto-removing setting the following options:
 
 ```ruby
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   meilisearch auto_index: false, auto_remove: false
 end

data/lib/meilisearch/rails/configuration.rb

@@ -1,4 +1,4 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     module Configuration
       def configuration
@@ -44,11 +44,11 @@ module MeiliSearch
       def client
         return black_hole unless active?
 
-        ::MeiliSearch::Client.new(
+        ::Meilisearch::Client.new(
           configuration[:meilisearch_url] || 'http://localhost:7700',
           configuration[:meilisearch_api_key],
           configuration.slice(:timeout, :max_retries)
-                       .merge(client_agents: MeiliSearch::Rails.qualified_version)
+                       .merge(client_agents: Meilisearch::Rails.qualified_version)
         )
       end
     end

data/lib/meilisearch/rails/errors.rb

@@ -1,4 +1,4 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     class NoBlockGiven < StandardError; end
 
@@ -6,7 +6,7 @@ module MeiliSearch
 
     class NotConfigured < StandardError
       def message
-        'Please configure Meilisearch. Set MeiliSearch::Rails.configuration = ' \
+        'Please configure Meilisearch. Set Meilisearch::Rails.configuration = ' \
           "{meilisearch_url: 'YOUR_MEILISEARCH_URL', meilisearch_api_key: 'YOUR_API_KEY'}"
       end
     end

data/lib/meilisearch/rails/ms_clean_up_job.rb

@@ -1,11 +1,11 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     class MSCleanUpJob < ::ActiveJob::Base
       queue_as :meilisearch
 
       def perform(documents)
         documents.each do |document|
-          index = MeiliSearch::Rails.client.index(document[:index_uid])
+          index = Meilisearch::Rails.client.index(document[:index_uid])
 
           if document[:synchronous]
             index.delete_document(document[:primary_key]).await

data/lib/meilisearch/rails/ms_job.rb

@@ -1,4 +1,4 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     class MSJob < ::ActiveJob::Base
       queue_as :meilisearch

data/lib/meilisearch/rails/multi_search/federated_search_result.rb

@@ -0,0 +1,78 @@
+require 'active_support/core_ext/module/delegation'
+
+module Meilisearch
+  module Rails
+    class FederatedSearchResult
+      attr_reader :metadata, :hits
+
+      def initialize(searches, raw_results)
+        hits = raw_results.delete('hits')
+        @hits = load_hits(hits, searches.to_a)
+        @metadata = raw_results
+      end
+
+      include Enumerable
+
+      delegate :each, :to_a, :to_ary, :empty?, :[], :first, :last, to: :@hits
+
+      private
+
+      def load_hits(hits, searches)
+        hits_by_pos = hits.group_by { |hit| hit['_federation']['queriesPosition'] }
+
+        keys_and_records_by_pos = hits_by_pos.to_h do |pos, group_hits|
+          search_target, search_opts = searches[pos]
+
+          scope = if search_opts[:scope]
+                    search_opts[:scope]
+                  elsif search_target.instance_of?(Class)
+                    search_target
+                  end
+
+          if scope.present?
+            [pos, load_results(scope, group_hits)]
+          else
+            [pos, [nil, group_hits]]
+          end
+        end
+
+        hits.filter_map do |hit|
+          hit_cond_key, recs_by_id = keys_and_records_by_pos[hit['_federation']['queriesPosition']]
+
+          if hit_cond_key.present?
+            record = recs_by_id[hit[hit_cond_key.to_s].to_s]
+            record&.formatted = hit['_formatted']
+            record
+          else
+            hit
+          end
+        end
+      end
+
+      def load_results(scope, hits)
+        klass = scope.respond_to?(:model) ? scope.model : scope
+
+        pk_method = klass.ms_primary_key_method
+        pk_method = pk_method.in if Utilities.mongo_model?(klass)
+
+        condition_key = pk_is_virtual?(klass, pk_method) ? klass.primary_key : pk_method
+
+        hits_by_id = hits.index_by { |hit| hit[condition_key.to_s] }
+
+        records = scope.where(condition_key => hits_by_id.keys)
+
+        results_by_id = records.index_by do |record|
+          record.send(condition_key).to_s
+        end
+
+        [condition_key, results_by_id]
+      end
+
+      def pk_is_virtual?(model_class, pk_method)
+        model_class.columns
+                   .map(&(Utilities.sequel_model?(model_class) ? :to_s : :name))
+                   .exclude?(pk_method.to_s)
+      end
+    end
+  end
+end

data/lib/meilisearch/rails/multi_search/{result.rb → multi_search_result.rb}

@@ -1,4 +1,4 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     class MultiSearchResult
       attr_reader :metadata
@@ -9,12 +9,18 @@ module MeiliSearch
 
         searches.zip(raw_results['results']).each do |(target, search_options), result|
           results_class = if search_options[:class_name]
+                            Meilisearch::Rails.logger.warn(
+                              '[meilisearch-rails] The :class_name option in multi search is deprecated, please use :scope instead.'
+                            )
+
                             search_options[:class_name].constantize
                           elsif target.instance_of?(Class)
                             target
+                          elsif search_options[:scope]
+                            search_options[:scope]
                           end
 
-          @results[target] = results_class ? load_results(results_class, result) : result['hits']
+          @results[target] = results_class ? load_results(results_class, result, scope: search_options[:scope]) : result['hits']
 
           @metadata[target] = result.except('hits')
         end
@@ -23,7 +29,7 @@ module MeiliSearch
       include Enumerable
 
       def each_hit(&block)
-        MeiliSearch::Rails.logger.warn(
+        Meilisearch::Rails.logger.warn(
           <<~DEPRECATION
             [meilisearch-rails] Flattening multi search results is deprecated.
             If you do not want the results to be grouped, please use federated search instead.
@@ -36,7 +42,7 @@ module MeiliSearch
       end
 
       def each(&block)
-        MeiliSearch::Rails.logger.info(
+        Meilisearch::Rails.logger.info(
           <<~INFO
             [meilisearch-rails] #each on a multi search now iterates through grouped results.
             If you do not want the results to be grouped, please use federated search instead.
@@ -52,7 +58,7 @@ module MeiliSearch
       end
 
       def to_a
-        MeiliSearch::Rails.logger.warn(
+        Meilisearch::Rails.logger.warn(
           <<~DEPRECATION
             [meilisearch-rails] Flattening multi search results is deprecated.
             If you do not want the results to be grouped, please use federated search instead.
@@ -69,7 +75,9 @@ module MeiliSearch
 
       private
 
-      def load_results(klass, result)
+      def load_results(klass, result, scope:)
+        scope ||= klass
+
         pk_method = klass.ms_primary_key_method
         pk_method = pk_method.in if Utilities.mongo_model?(klass)
 
@@ -78,7 +86,7 @@ module MeiliSearch
         hits_by_id =
           result['hits'].index_by { |hit| hit[condition_key.to_s] }
 
-        records = klass.where(condition_key => hits_by_id.keys)
+        records = scope.where(condition_key => hits_by_id.keys)
 
         if records.respond_to? :in_order_of
           records.in_order_of(condition_key, hits_by_id.keys).each do |record|

data/lib/meilisearch/rails/multi_search.rb

@@ -1,33 +1,72 @@
-require_relative 'multi_search/result'
+require_relative 'multi_search/multi_search_result'
+require_relative 'multi_search/federated_search_result'
 
-module MeiliSearch
+module Meilisearch
   module Rails
     class << self
       def multi_search(searches)
         search_parameters = searches.map do |(index_target, options)|
-          index_target = options.delete(:index_uid) || index_target
+          model_class = options[:scope].respond_to?(:model) ? options[:scope].model : options[:scope]
+          index_target = options.delete(:index_uid) || model_class || index_target
 
           paginate(options) if pagination_enabled?
           normalize(options, index_target)
         end
 
-        MultiSearchResult.new(searches, client.multi_search(search_parameters))
+        MultiSearchResult.new(searches, client.multi_search(queries: search_parameters))
+      end
+
+      def federated_search(queries:, federation: {})
+        if federation.nil?
+          Meilisearch::Rails.logger.warn(
+            '[meilisearch-rails] In federated_search, `nil` is an invalid `:federation` option. To explicitly use defaults, pass `{}`.'
+          )
+
+          federation = {}
+        end
+
+        queries.map! { |item| [nil, item] } if queries.is_a?(Array)
+
+        cleaned_queries = queries.filter_map do |(index_target, options)|
+          model_class = options[:scope].respond_to?(:model) ? options[:scope].model : options[:scope]
+          index_target = options.delete(:index_uid) || index_target || model_class
+
+          strip_pagination_options(options)
+          normalize(options, index_target)
+        end
+
+        raw_results = client.multi_search(queries: cleaned_queries, federation: federation)
+
+        FederatedSearchResult.new(queries, raw_results)
       end
 
       private
 
       def normalize(options, index_target)
+        index_target = index_uid_from_target(index_target)
+
+        return nil if index_target.nil?
+
         options
-          .except(:class_name)
-          .merge!(index_uid: index_uid_from_target(index_target))
+          .except(:class_name, :scope)
+          .merge!(index_uid: index_target)
       end
 
       def index_uid_from_target(index_target)
         case index_target
         when String, Symbol
           index_target
-        else
-          index_target.index.uid
+        when Class
+          if index_target.respond_to?(:index)
+            index_target.index.uid
+          else
+            Meilisearch::Rails.logger.warn <<~MODEL_NOT_INDEXED
+              [meilisearch-rails] This class was passed to a multi/federated search but it does not have an #index: #{index_target}
+              [meilisearch-rails] Are you sure it has a `meilisearch` block?
+            MODEL_NOT_INDEXED
+
+            nil
+          end
         end
       end
 
@@ -43,8 +82,22 @@ module MeiliSearch
         options[:page] ||= 1
       end
 
+      def strip_pagination_options(options)
+        pagination_options = %w[page hitsPerPage hits_per_page limit offset].select do |key|
+          options.delete(key) || options.delete(key.to_sym)
+        end
+
+        return if pagination_options.empty?
+
+        Meilisearch::Rails.logger.warn <<~WRONG_PAGINATION
+          [meilisearch-rails] Pagination options in federated search must apply to whole federation.
+          [meilisearch-rails] These options have been removed: #{pagination_options.join(', ')}.
+          [meilisearch-rails] Please pass them after queries, in the `federation:` option.
+        WRONG_PAGINATION
+      end
+
       def pagination_enabled?
-        MeiliSearch::Rails.configuration[:pagination_backend]
+        Meilisearch::Rails.configuration[:pagination_backend]
       end
     end
   end

data/lib/meilisearch/rails/null_object.rb

@@ -1,6 +1,6 @@
 require 'singleton'
 
-module MeiliSearch
+module Meilisearch
   module Rails
     class NullObject
       include Singleton

data/lib/meilisearch/rails/pagination/kaminari.rb

@@ -1,11 +1,11 @@
 unless defined? Kaminari
-  raise(MeiliSearch::BadConfiguration,
+  raise(Meilisearch::BadConfiguration,
         "Meilisearch: Please add 'kaminari' to your Gemfile to use kaminari pagination backend")
 end
 
 require 'kaminari/models/array_extension'
 
-module MeiliSearch
+module Meilisearch
   module Rails
     module Pagination
       class Kaminari < ::Kaminari::PaginatableArray
@@ -18,7 +18,7 @@ module MeiliSearch
         end
 
         def self.create(results, total_hits, options = {})
-          unless MeiliSearch::Rails.active?
+          unless Meilisearch::Rails.active?
             total_hits = 0
             options[:page] = 1
             options[:per_page] = 1

data/lib/meilisearch/rails/pagination/will_paginate.rb

@@ -1,16 +1,16 @@
 begin
   require 'will_paginate/collection'
 rescue LoadError
-  raise(MeiliSearch::BadConfiguration,
-        "MeiliSearch: Please add 'will_paginate' to your Gemfile to use will_paginate pagination backend")
+  raise(Meilisearch::BadConfiguration,
+        "Meilisearch: Please add 'will_paginate' to your Gemfile to use will_paginate pagination backend")
 end
 
-module MeiliSearch
+module Meilisearch
   module Rails
     module Pagination
       class WillPaginate
         def self.create(results, total_hits, options = {})
-          unless MeiliSearch::Rails.active?
+          unless Meilisearch::Rails.active?
             total_hits = 0
             options[:page] = 1
             options[:per_page] = 1

data/lib/meilisearch/rails/pagination.rb

@@ -1,11 +1,11 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     module Pagination
       autoload :WillPaginate, 'meilisearch/rails/pagination/will_paginate'
       autoload :Kaminari, 'meilisearch/rails/pagination/kaminari'
 
       def self.create(results, total_hits, options = {})
-        pagination_backend = MeiliSearch::Rails.configuration[:pagination_backend]
+        pagination_backend = Meilisearch::Rails.configuration[:pagination_backend]
 
         if pagination_backend.nil? || (is_pagy = pagination_backend.to_s == 'pagy')
           log_pagy_error if is_pagy
@@ -17,12 +17,12 @@ module MeiliSearch
       end
 
       def self.log_pagy_error
-        MeiliSearch::Rails.logger
+        Meilisearch::Rails.logger
           .warn('[meilisearch-rails] Remove `pagination_backend: :pagy` from your initializer, `pagy` it is not required for `pagy`')
       end
 
       def self.load_pagination!(pagination_backend, results, total_hits, options)
-        ::MeiliSearch::Rails::Pagination
+        ::Meilisearch::Rails::Pagination
           .const_get(pagination_backend.to_s.classify)
           .create(results, total_hits, options)
       rescue NameError

data/lib/meilisearch/rails/railtie.rb

@@ -1,6 +1,6 @@
 require 'rails'
 
-module MeiliSearch
+module Meilisearch
   module Rails
     class Railtie < ::Rails::Railtie
       rake_tasks do

data/lib/meilisearch/rails/tasks/meilisearch.rake

@@ -3,21 +3,21 @@ namespace :meilisearch do
   task reindex: :environment do
     puts 'Reindexing all Meilisearch models'
 
-    MeiliSearch::Rails::Utilities.reindex_all_models
+    Meilisearch::Rails::Utilities.reindex_all_models
   end
 
   desc 'Set settings to all indexes'
   task set_all_settings: :environment do
     puts 'Set settings in all Meilisearch models'
 
-    MeiliSearch::Rails::Utilities.set_settings_all_models
+    Meilisearch::Rails::Utilities.set_settings_all_models
   end
 
   desc 'Clear all indexes'
   task clear_indexes: :environment do
     puts 'Clearing indexes from all Meilisearch models'
 
-    MeiliSearch::Rails::Utilities.clear_all_indexes
+    Meilisearch::Rails::Utilities.clear_all_indexes
   end
 
   desc 'Create initializer file'

data/lib/meilisearch/rails/templates/initializer.rb

@@ -1,4 +1,4 @@
-MeiliSearch::Rails.configuration = {
+Meilisearch::Rails.configuration = {
   meilisearch_url: ENV.fetch('MEILISEARCH_HOST', 'http://localhost:7700'),
   meilisearch_api_key: ENV.fetch('MEILISEARCH_API_KEY', 'YourMeilisearchAPIKey')
 }

data/lib/meilisearch/rails/utilities.rb

@@ -1,4 +1,4 @@
-module MeiliSearch
+module Meilisearch
   module Rails
     module Utilities
       class << self
@@ -8,7 +8,7 @@ module MeiliSearch
           elsif ::Rails.application
             ::Rails.application.eager_load!
           end
-          klasses = MeiliSearch::Rails.instance_variable_get(:@included_in)
+          klasses = Meilisearch::Rails.instance_variable_get(:@included_in)
           (klasses + klasses.map(&:descendants).flatten).uniq
         end
 

data/lib/meilisearch/rails/version.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module MeiliSearch
+module Meilisearch
   module Rails
-    VERSION = '0.14.3'
+    VERSION = '0.15.0'
 
     def self.qualified_version
       "Meilisearch Rails (v#{VERSION})"

data/lib/meilisearch-rails.rb

@@ -20,7 +20,13 @@ end
 
 require 'logger'
 
-module MeiliSearch
+# Workaround for the soft deprecation of MeiliSearch (old spelling)
+# The regular `const_get` method does not seem to work
+# too well with autoload and thus does not pull in methods
+# like `client` which are obviously vital.
+MeiliSearch::Rails = Meilisearch::Rails
+
+module Meilisearch
   module Rails
     autoload :Configuration, 'meilisearch/rails/configuration'
     extend Configuration
@@ -97,7 +103,7 @@ module MeiliSearch
               [meilisearch-rails] #{missing_searchable} declared in searchable_attributes but not in attributes. \
               Please add it to attributes if it should be searchable.
             WARNING
-            MeiliSearch::Rails.logger.warn(warning)
+            Meilisearch::Rails.logger.warn(warning)
           end
         end
       end
@@ -270,12 +276,12 @@ module MeiliSearch
       autoload :MSCleanUpJob, 'meilisearch/rails/ms_clean_up_job'
     end
 
-    # this class wraps an MeiliSearch::Index document ensuring all raised exceptions
+    # this class wraps an Meilisearch::Index document ensuring all raised exceptions
     # are correctly logged or thrown depending on the `raise_on_failure` option
     class SafeIndex
       def initialize(index_uid, raise_on_failure, options)
-        client = MeiliSearch::Rails.client
-        primary_key = options[:primary_key] || MeiliSearch::Rails::IndexSettings::DEFAULT_PRIMARY_KEY
+        client = Meilisearch::Rails.client
+        primary_key = options[:primary_key] || Meilisearch::Rails::IndexSettings::DEFAULT_PRIMARY_KEY
         @raise_on_failure = raise_on_failure.nil? || raise_on_failure
 
         SafeIndex.log_or_throw(nil, @raise_on_failure) do
@@ -285,7 +291,7 @@ module MeiliSearch
         @index = client.index(index_uid)
       end
 
-      ::MeiliSearch::Index.instance_methods(false).each do |m|
+      ::Meilisearch::Index.instance_methods(false).each do |m|
         define_method(m) do |*args, &block|
           if m == :update_settings
             args[0].delete(:attributes_to_highlight) if args[0][:attributes_to_highlight]
@@ -294,7 +300,7 @@ module MeiliSearch
           end
 
           SafeIndex.log_or_throw(m, @raise_on_failure) do
-            return MeiliSearch::Rails.black_hole unless MeiliSearch::Rails.active?
+            return Meilisearch::Rails.black_hole unless Meilisearch::Rails.active?
 
             @index.send(m, *args, &block)
           end
@@ -304,7 +310,7 @@ module MeiliSearch
       # Maually define facet_search due to complications with **opts in ruby 2.*
       def facet_search(*args, **opts)
         SafeIndex.log_or_throw(:facet_search, @raise_on_failure) do
-          return MeiliSearch::Rails.black_hole unless MeiliSearch::Rails.active?
+          return Meilisearch::Rails.black_hole unless Meilisearch::Rails.active?
 
           @index.facet_search(*args, **opts)
         end
@@ -323,7 +329,7 @@ module MeiliSearch
       def settings(*args)
         SafeIndex.log_or_throw(:settings, @raise_on_failure) do
           @index.settings(*args)
-        rescue ::MeiliSearch::ApiError => e
+        rescue ::Meilisearch::ApiError => e
           return {} if e.code == 'index_not_found' # not fatal
 
           raise e
@@ -332,11 +338,11 @@ module MeiliSearch
 
       def self.log_or_throw(method, raise_on_failure, &block)
         yield
-      rescue ::MeiliSearch::TimeoutError, ::MeiliSearch::ApiError => e
+      rescue ::Meilisearch::TimeoutError, ::Meilisearch::ApiError => e
         raise e if raise_on_failure
 
         # log the error
-        MeiliSearch::Rails.logger.info("[meilisearch-rails] #{e.message}")
+        Meilisearch::Rails.logger.info("[meilisearch-rails] #{e.message}")
         # return something
         case method.to_s
         when 'search'
@@ -349,7 +355,7 @@ module MeiliSearch
       end
     end
 
-    # these are the class methods added when MeiliSearch is included
+    # these are the class methods added when Meilisearch is included
     module ClassMethods
       def self.extended(base)
         class << base
@@ -379,7 +385,7 @@ module MeiliSearch
         attr_accessor :formatted
 
         if options.key?(:per_environment)
-          raise BadConfiguration, ':per_environment option should be defined globally on MeiliSearch::Rails.configuration block.'
+          raise BadConfiguration, ':per_environment option should be defined globally on Meilisearch::Rails.configuration block.'
         end
 
         if options[:synchronous] == true
@@ -415,7 +421,7 @@ module MeiliSearch
                    raise ArgumentError, "Invalid `enqueue` option: #{options[:enqueue]}"
                  end
           meilisearch_options[:enqueue] = proc do |record, remove|
-            proc.call(record, remove) if ::MeiliSearch::Rails.active? && !ms_without_auto_index_scope
+            proc.call(record, remove) if ::Meilisearch::Rails.active? && !ms_without_auto_index_scope
           end
         end
         unless options[:auto_index] == false
@@ -499,7 +505,7 @@ module MeiliSearch
         Thread.current["ms_without_auto_index_scope_for_#{model_name}"]
       end
 
-      def ms_reindex!(batch_size = MeiliSearch::Rails::IndexSettings::DEFAULT_BATCH_SIZE, synchronous = false)
+      def ms_reindex!(batch_size = Meilisearch::Rails::IndexSettings::DEFAULT_BATCH_SIZE, synchronous = false)
         return if ms_without_auto_index_scope
 
         ms_configurations.each do |options, settings|
@@ -622,7 +628,7 @@ module MeiliSearch
 
           index = ms_ensure_init(options, settings)
           synchronous || options[:synchronous] ? index.delete_all_documents.await : index.delete_all_documents
-          @ms_indexes[MeiliSearch::Rails.active?][settings] = nil
+          @ms_indexes[Meilisearch::Rails.active?][settings] = nil
         end
         nil
       end
@@ -666,7 +672,7 @@ module MeiliSearch
       end
 
       def ms_search(query, params = {})
-        if MeiliSearch::Rails.configuration[:pagination_backend]
+        if Meilisearch::Rails.configuration[:pagination_backend]
           %i[page hitsPerPage hits_per_page].each do |key|
             params[key.to_s.underscore.to_sym] = params[key].to_i if params.key?(key)
           end
@@ -736,7 +742,7 @@ module MeiliSearch
 
       def ms_index_uid(options = nil)
         options ||= meilisearch_options
-        global_options ||= MeiliSearch::Rails.configuration
+        global_options ||= Meilisearch::Rails.configuration
 
         name = options[:index_uid] || model_name.to_s.gsub('::', '_')
         name = "#{name}_#{::Rails.env}" if global_options[:per_environment]
@@ -788,11 +794,11 @@ module MeiliSearch
 
         @ms_indexes ||= { true => {}, false => {} }
 
-        @ms_indexes[MeiliSearch::Rails.active?][settings] ||= SafeIndex.new(ms_index_uid(options), meilisearch_options[:raise_on_failure], meilisearch_options)
+        @ms_indexes[Meilisearch::Rails.active?][settings] ||= SafeIndex.new(ms_index_uid(options), meilisearch_options[:raise_on_failure], meilisearch_options)
 
-        update_settings_if_changed(@ms_indexes[MeiliSearch::Rails.active?][settings], options, user_configuration)
+        update_settings_if_changed(@ms_indexes[Meilisearch::Rails.active?][settings], options, user_configuration)
 
-        @ms_indexes[MeiliSearch::Rails.active?][settings]
+        @ms_indexes[Meilisearch::Rails.active?][settings]
       end
 
       private
@@ -845,7 +851,7 @@ module MeiliSearch
       end
 
       def ms_pk(options = nil)
-        options[:primary_key] || MeiliSearch::Rails::IndexSettings::DEFAULT_PRIMARY_KEY
+        options[:primary_key] || Meilisearch::Rails::IndexSettings::DEFAULT_PRIMARY_KEY
       end
 
       def meilisearch_settings_changed?(server_state, user_configuration)

data/meilisearch-rails.gemspec

@@ -5,7 +5,7 @@ require 'meilisearch/rails/version'
 
 Gem::Specification.new do |s|
   s.name = 'meilisearch-rails'
-  s.version = MeiliSearch::Rails::VERSION
+  s.version = Meilisearch::Rails::VERSION
 
   s.authors = ['Meili']
   s.email = 'bonjour@meilisearch.com'
@@ -34,6 +34,6 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 3.0.0'
 
-  s.add_dependency 'meilisearch', '~> 0.28.4'
+  s.add_dependency 'meilisearch', '~> 0.31.0'
   s.add_dependency 'mutex_m', '~> 0.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meilisearch-rails
 version: !ruby/object:Gem::Version
-  version: 0.14.3
+  version: 0.15.0
 platform: ruby
 authors:
 - Meili
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-13 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: meilisearch
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.4
+        version: 0.31.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.4
+        version: 0.31.0
 - !ruby/object:Gem::Dependency
   name: mutex_m
   requirement: !ruby/object:Gem::Requirement
@@ -57,7 +57,8 @@ files:
 - lib/meilisearch/rails/ms_clean_up_job.rb
 - lib/meilisearch/rails/ms_job.rb
 - lib/meilisearch/rails/multi_search.rb
-- lib/meilisearch/rails/multi_search/result.rb
+- lib/meilisearch/rails/multi_search/federated_search_result.rb
+- lib/meilisearch/rails/multi_search/multi_search_result.rb
 - lib/meilisearch/rails/null_object.rb
 - lib/meilisearch/rails/pagination.rb
 - lib/meilisearch/rails/pagination/kaminari.rb