meilisearch-rails 0.14.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab897ac0b83c33721dc40eab5be2d2cc5013c14380a1d47df590f44339433fc
-  data.tar.gz: d99e1fd1970915a665a328233df77bf526f0510478fa2087b502a6224e8a2635
+  metadata.gz: 317b4503e3616fe8f309ac194c2eb85a902222edda8ae58824c53f081280a0de
+  data.tar.gz: f9ef605f39f533307b5af4d6204c8fd19fb5d49dd507e72010d7d5458b37e066
 SHA512:
-  metadata.gz: 67e71e231498dd94223096fd3bb02a7f79a8861a4a013f3a628ee3141db3436e323df1cd671caeb20937fe39533c558bd540c4eceae6f6b69713a3af8ceb1a93
-  data.tar.gz: 23ac15e8d4d42a1af5d9f2c38e84b9e7c810979af2ca8264eb818b80aaaf84d2ad973512857f2c40c0708dee82a6d67ddc2097e542cc71c4e64f7bc1cb72edbe
+  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,13 +236,75 @@ 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' }
 )
 ```
 
-You can iterate through the results with `.each` or `.each_result`:
+Use `#each_result` to loop through pairs of your provided keys and the results:
+```erb
+<% 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>
+```
+
+Records are loaded when the keys are models, or when `:scope` option is passed:
+
+```ruby
+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 }
+)
+```
+
+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', scope: Book, index_uid: 'books_production' },
+  'japanese' => { q: 'Attack', scope: Manga, index_uid: 'mangas_production' }
+)
+```
+
+### Multi search the same index <!-- omit in toc -->
+
+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, 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 <!-- omit in toc -->
+
+**DEPRECATED:** You used to be able to iterate through a flattened collection with `.each`:
 
 ```erb
 <% multi_search_results.each do |record| %>
@@ -257,30 +320,175 @@ You can iterate through the results with `.each` or `.each_result`:
 <p>Iseyama</p>
 ```
 
-```erb
-<% multi_search_results.each_result do |klass, results| %>
-  <p><%= klass.name.pluralize %></p>
+But this has been deprecated in favor of **federated search**.
 
-  <ul>
-    <% results.each do |record| %>
-      <li><%= record.title %></li>
-    <% end %>
-  </ul>
-<% end %>
+See the [official multi search documentation](https://www.meilisearch.com/docs/reference/api/multi_search).
 
+## 🔍🔍 Federated search
 
-<p>Books</p>
+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>
-  <li>Harry Potter and the Philosopher's Stone</li>
-  <li>Harry Potter and the Chamber of Secrets</li>
+  <% results.each do |record| %>
+    <li><%= record.title %></li>
+  <% end %>
 </ul>
-<p>Mangas</p>
+
+
 <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>
 ```
 
-See the [official multi search documentation](https://www.meilisearch.com/docs/reference/api/multi_search).
+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
 
@@ -295,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
@@ -344,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 # ...
@@ -365,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.
 
@@ -377,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
@@ -387,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
@@ -400,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.
@@ -411,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
@@ -422,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
@@ -441,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
@@ -473,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
@@ -484,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
 
@@ -503,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?
 
@@ -526,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'
@@ -555,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
 
@@ -567,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
 
@@ -585,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
@@ -599,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
@@ -629,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
@@ -659,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
@@ -683,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
@@ -693,7 +901,7 @@ class Author < ActiveRecord::Base
 end
 
 class Book < ActiveRecord::Base
-  include MeiliSearch::Rails
+  include Meilisearch::Rails
 
   belongs_to :author
   after_touch :index!
@@ -712,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
 
@@ -734,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!
@@ -757,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
@@ -769,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
@@ -781,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
 
@@ -834,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?
@@ -849,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
@@ -862,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