Get documents by filter

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-05-20 01:53:00 UTC using RuboCop version 1.50.2.
+# 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: 46
+# 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: 321
+  Max: 327
 
 # Offense count: 1
 # Configuration parameters: Max, CountKeywordArgs.

lib/meilisearch/index.rb

@@ -63,8 +63,25 @@ 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
 

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|

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