Merge #437

437: Changes related to the next Meilisearch release (v1.2.0) r=brunoocasali a=meili-bot

Related to this issue: meilisearch/integration-guides#261

This PR:
- gathers the changes related to the next Meilisearch release (v1.2.0) so that this package is ready when the official release is out.
- should pass the tests against the [latest pre-release of Meilisearch](https://github.com/meilisearch/meilisearch/releases).
- might eventually contain test failures until the Meilisearch v1.2.0 is out.

⚠️ This PR should NOT be merged until the next release of Meilisearch (v1.2.0) is out.

_This PR is auto-generated for the [pre-release week](https://github.com/meilisearch/integration-guides/blob/main/resources/pre-release-week.md) purpose._


Co-authored-by: meili-bot <[email protected]>
Co-authored-by: Bruno Casali <[email protected]>

Author: 3 people

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-03-30 12:31:09 UTC using RuboCop version 1.48.1.
+# on 2023-05-20 02:24:12 UTC using RuboCop version 1.50.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -14,7 +14,7 @@ Gemspec/RequireMFA:
   Exclude:
     - 'meilisearch.gemspec'
 
-# Offense count: 45
+# Offense count: 47
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -23,7 +23,7 @@ Metrics/BlockLength:
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 318
+  Max: 327
 
 # Offense count: 1
 # Configuration parameters: Max, CountKeywordArgs.

lib/meilisearch/index.rb

@@ -63,8 +63,24 @@ def document(document_id, fields: nil)
     alias get_document document
     alias get_one_document document
 
+    # Public: Retrieve documents from a index.
+    #
+    # options - The hash options used to refine the selection (default: {}):
+    #           :limit  - Number of documents to return (optional).
+    #           :offset - Number of documents to skip (optional).
+    #           :fields - Array of document attributes to show (optional).
+    #           :filter - Filter queries by an attribute's value.
+    #                     Available ONLY with Meilisearch v1.2 and newer (optional).
+    #
+    # Returns the documents results object.
     def documents(options = {})
-      http_get "/indexes/#{@uid}/documents", Utils.parse_query(options, [:limit, :offset, :fields])
+      Utils.version_error_handler(__method__) do
+        if options.key?(:filter)
+          http_post "/indexes/#{@uid}/documents/fetch", Utils.filter(options, [:limit, :offset, :fields, :filter])
+        else
+          http_get "/indexes/#{@uid}/documents", Utils.parse_query(options, [:limit, :offset, :fields])
+        end
+      end
     end
     alias get_documents documents
 
@@ -153,11 +169,24 @@ def update_documents_in_batches!(documents, batch_size = 1000, primary_key = nil
       responses
     end
 
-    def delete_documents(documents_ids)
-      if documents_ids.is_a?(Array)
-        http_post "/indexes/#{@uid}/documents/delete-batch", documents_ids
-      else
-        delete_document(documents_ids)
+    # Public: Delete documents from an index
+    #
+    # options: A Hash or an Array containing documents_ids or a hash with filter:.
+    #   filter: - A hash containing a filter that should match documents.
+    #             Available ONLY with Meilisearch v1.2 and newer (optional)
+    #
+    # Returns a Task object.
+    def delete_documents(options = {})
+      Utils.version_error_handler(__method__) do
+        if options.is_a?(Hash) && options.key?(:filter)
+          http_post "/indexes/#{@uid}/documents/delete", options
+        else
+          # backwards compatibility:
+          # expect to be a array or/number/string to send alongside as documents_ids.
+          options = [options] unless options.is_a?(Array)
+
+          http_post "/indexes/#{@uid}/documents/delete-batch", options
+        end
       end
     end
     alias delete_multiple_documents delete_documents

lib/meilisearch/utils.rb

@@ -23,8 +23,12 @@ def self.parse(body)
         end
     end
 
+    def self.filter(original_options, allowed_params = [])
+      original_options.transform_keys(&:to_sym).slice(*allowed_params)
+    end
+
     def self.parse_query(original_options, allowed_params = [])
-      only_allowed_params = original_options.transform_keys(&:to_sym).slice(*allowed_params)
+      only_allowed_params = filter(original_options, allowed_params)
 
       Utils.transform_attributes(only_allowed_params).then do |body|
         body.transform_values do |v|
@@ -33,6 +37,21 @@ def self.parse_query(original_options, allowed_params = [])
       end
     end
 
-    private_class_method :parse
+    def self.message_builder(current_message, method_name)
+      "#{current_message}\nHint: It might not be working because maybe you're not up " \
+        "to date with the Meilisearch version that `#{method_name}` call requires."
+    end
+
+    def self.version_error_handler(method_name)
+      yield if block_given?
+    rescue MeiliSearch::ApiError => e
+      message = message_builder(e.http_message, method_name)
+
+      raise MeiliSearch::ApiError.new(e.http_code, message, e.http_body)
+    rescue StandardError => e
+      raise e.class, message_builder(e.message, method_name)
+    end
+
+    private_class_method :parse, :message_builder
   end
 end

spec/meilisearch/index/documents_spec.rb

@@ -37,28 +37,28 @@
       end
 
       it 'adds JSON documents (as a array of documents)' do
-        documents = <<JSON
-        [
-          { "objectRef": 123,  "title": "Pride and Prejudice",                    "comment": "A great book" },
-          { "objectRef": 456,  "title": "Le Petit Prince",                        "comment": "A french book" },
-          { "objectRef": 1,    "title": "Alice In Wonderland",                    "comment": "A weird book" },
-          { "objectRef": 1344, "title": "The Hobbit",                             "comment": "An awesome book" },
-          { "objectRef": 4,    "title": "Harry Potter and the Half-Blood Prince", "comment": "The best book" }
-        ]
-JSON
+        documents = <<~JSON
+          [
+            { "objectRef": 123,  "title": "Pride and Prejudice",                    "comment": "A great book" },
+            { "objectRef": 456,  "title": "Le Petit Prince",                        "comment": "A french book" },
+            { "objectRef": 1,    "title": "Alice In Wonderland",                    "comment": "A weird book" },
+            { "objectRef": 1344, "title": "The Hobbit",                             "comment": "An awesome book" },
+            { "objectRef": 4,    "title": "Harry Potter and the Half-Blood Prince", "comment": "The best book" }
+          ]
+        JSON
         response = index.add_documents_json(documents, 'objectRef')
 
         index.wait_for_task(response['taskUid'])
         expect(index.documents['results'].count).to eq(5)
       end
 
       it 'adds NDJSON documents (as a array of documents)' do
-        documents = <<NDJSON
-        { "objectRef": 123,  "title": "Pride and Prejudice",                    "comment": "A great book" }
-        { "objectRef": 456,  "title": "Le Petit Prince",                        "comment": "A french book" }
-        { "objectRef": 1,    "title": "Alice In Wonderland",                    "comment": "A weird book" }
-        { "objectRef": 4,    "title": "Harry Potter and the Half-Blood Prince", "comment": "The best book" }
-NDJSON
+        documents = <<~NDJSON
+          { "objectRef": 123,  "title": "Pride and Prejudice",                    "comment": "A great book" }
+          { "objectRef": 456,  "title": "Le Petit Prince",                        "comment": "A french book" }
+          { "objectRef": 1,    "title": "Alice In Wonderland",                    "comment": "A weird book" }
+          { "objectRef": 4,    "title": "Harry Potter and the Half-Blood Prince", "comment": "The best book" }
+        NDJSON
         response = index.add_documents_ndjson(documents, 'objectRef')
 
         index.wait_for_task(response['taskUid'])
@@ -196,7 +196,12 @@
     end
 
     describe 'accessing documents' do
-      before { index.add_documents!(documents) }
+      before do
+        index.add_documents(documents)
+
+        task = index.update_filterable_attributes(['title', 'objectId'])
+        client.wait_for_task(task['taskUid'])
+      end
 
       it 'gets one document from its primary-key' do
         task = index.document(123)
@@ -228,6 +233,25 @@
         expect(docs).to be_a(Array)
         expect(docs.first.keys).to eq(['title'])
       end
+
+      it 'retrieves documents by filters' do
+        docs = index.documents(filter: 'objectId > 400')['results']
+
+        expect(docs).to be_a(Array)
+        expect(docs.first).to eq({
+                                   'objectId' => 456,
+                                   'title' => 'Le Petit Prince',
+                                   'comment' => 'A french book'
+                                 })
+      end
+
+      it 'retrieves documents by filters & other parameters' do
+        docs = index.documents(fields: ['title'], filter: 'objectId > 100')['results']
+
+        expect(docs).to be_a(Array)
+        expect(docs.size).to eq(3)
+        expect(docs.first.keys).to eq(['title'])
+      end
     end
 
     describe 'updating documents' do
@@ -390,6 +414,23 @@
         expect { index.document(id) }.to raise_document_not_found_meilisearch_api_error
       end
 
+      it 'deletes documents based on filter from index (with delete route)' do
+        expect do
+          index.update_filterable_attributes(['objectId'])
+          task = index.delete_documents(filter: ['objectId > 0'])
+
+          client.wait_for_task(task['taskUid'])
+        end.to(change { index.documents['results'].size }.by(-documents.size))
+      end
+
+      it 'ignores filter even when documents_ids is empty (with delete-batch route)' do
+        expect do
+          task = index.delete_documents(filter: ['objectId > 0'])
+
+          client.wait_for_task(task['taskUid'])
+        end.to(change { index.documents['results'].size }.by(0))
+      end
+
       it 'deletes one document synchronously from index (with delete-batch route)' do
         id = 2
         expect do

spec/meilisearch/index/search/multi_params_spec.rb

@@ -59,7 +59,7 @@
     expect(response['hits'].first).not_to have_key('objectId')
     expect(response['hits'].first).not_to have_key('genre')
     expect(response['hits'].first).to have_key('title')
-    expect(response['hits'].first['_formatted']['title']).to eq('Harry Potter and the Half-Blood <em>Princ</em>e')
+    expect(response['hits'].first['_formatted']['title']).to eq('Harry Potter and the Half-Blood <em>Prince</em>')
   end
 
   it 'does a custom search with facets and limit' do

spec/meilisearch/utils_spec.rb

@@ -46,4 +46,30 @@
       )
     end
   end
+
+  describe '.version_error_handler' do
+    it 'spawns same error message' do
+      expect do
+        MeiliSearch::Utils.version_error_handler(:my_method) do
+          raise MeiliSearch::ApiError.new(405, 'I came from Meili server', {})
+        end
+      end.to raise_error(MeiliSearch::ApiError, /I came from Meili server/)
+    end
+
+    it 'spawns message with version hint' do
+      expect do
+        MeiliSearch::Utils.version_error_handler(:my_method) do
+          raise MeiliSearch::ApiError.new(405, 'I came from Meili server', {})
+        end
+      end.to raise_error(MeiliSearch::ApiError, /that `my_method` call requires/)
+    end
+
+    it 'adds hints to all error types' do
+      expect do
+        MeiliSearch::Utils.version_error_handler(:my_method) do
+          raise MeiliSearch::CommunicationError, 'I am an error'
+        end
+      end.to raise_error(MeiliSearch::CommunicationError, /that `my_method` call requires/)
+    end
+  end
 end