Add skip_creation option to document add/replace endpoints

.code-samples.meilisearch.yaml

@@ -100,15 +100,15 @@ add_or_replace_documents_1: |-
       overview: 'A boy is given the ability to become an adult superhero in times of need with a single magic word.',
       release_date: '2019-03-23'
     }
-  ])
+  ], skip_creation: true)
 add_or_update_documents_1: |-
   client.index('movies').update_documents([
     {
       id: 287947,
       title: 'Shazam ⚡️',
       genres: 'comedy'
     }
-  ])
+  ], skip_creation: true)
 delete_all_documents_1: |-
   client.index('movies').delete_all_documents
 delete_one_document_1: |-

lib/meilisearch/index.rb

@@ -152,12 +152,15 @@ def documents(options = {})
     #
     # @param documents [Array<Hash{Object => Object>}] The documents to be added.
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
+    # @param skip_creation [Boolean] When true, the task fails if the index does not already exist
+    #   instead of creating it. Defaults to false.
     #
     # @return [Models::Task] The async task that adds the documents.
     # @see https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents Meilisearch API Reference
-    def add_documents(documents, primary_key = nil)
+    def add_documents(documents, primary_key = nil, skip_creation: nil)
       documents = [documents] if documents.is_a?(Hash)
-      response = http_post "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact
+      response = http_post "/indexes/#{@uid}/documents", documents,
+                           { primaryKey: primary_key, skipCreation: skip_creation }.compact
 
       Models::Task.new(response, task_endpoint)
     end
@@ -191,9 +194,10 @@ def add_documents!(documents, primary_key = nil)
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
     #
     # @return [Models::Task] The async task that adds the documents.
-    def add_documents_json(documents, primary_key = nil)
+    def add_documents_json(documents, primary_key = nil, skip_creation: nil)
       options = { convert_body?: false }
-      response = http_post "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+      response = http_post "/indexes/#{@uid}/documents", documents,
+                           { primaryKey: primary_key, skipCreation: skip_creation }.compact, options
 
       Models::Task.new(response, task_endpoint)
     end
@@ -211,9 +215,10 @@ def add_documents_json(documents, primary_key = nil)
     # @return [Models::Task] The async task that adds the documents.
     #
     # @see https://github.com/ndjson/ndjson-spec NDJSON spec
-    def add_documents_ndjson(documents, primary_key = nil)
+    def add_documents_ndjson(documents, primary_key = nil, skip_creation: nil)
       options = { headers: { 'Content-Type' => 'application/x-ndjson' }, convert_body?: false }
-      response = http_post "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+      response = http_post "/indexes/#{@uid}/documents", documents,
+                           { primaryKey: primary_key, skipCreation: skip_creation }.compact, options
 
       Models::Task.new(response, task_endpoint)
     end
@@ -230,12 +235,13 @@ def add_documents_ndjson(documents, primary_key = nil)
     # @param delimiter [String] The delimiter character in your CSV text.
     #
     # @return [Models::Task] The async task that adds the documents.
-    def add_documents_csv(documents, primary_key = nil, delimiter = nil)
+    def add_documents_csv(documents, primary_key = nil, delimiter = nil, skip_creation: nil)
       options = { headers: { 'Content-Type' => 'text/csv' }, convert_body?: false }
 
       response = http_post "/indexes/#{@uid}/documents", documents, {
         primaryKey: primary_key,
-        csvDelimiter: delimiter
+        csvDelimiter: delimiter,
+        skipCreation: skip_creation
       }.compact, options
 
       Models::Task.new(response, task_endpoint)
@@ -252,9 +258,10 @@ def add_documents_csv(documents, primary_key = nil, delimiter = nil)
     #
     # @return [Models::Task] The async task that adds the documents.
     # @see https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents Meilisearch API Reference
-    def update_documents(documents, primary_key = nil)
+    def update_documents(documents, primary_key = nil, skip_creation: nil)
       documents = [documents] if documents.is_a?(Hash)
-      response = http_put "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact
+      response = http_put "/indexes/#{@uid}/documents", documents,
+                          { primaryKey: primary_key, skipCreation: skip_creation }.compact
 
       Models::Task.new(response, task_endpoint)
     end
@@ -268,9 +275,10 @@ def update_documents(documents, primary_key = nil)
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
     #
     # @return [Models::Task] The async task that adds the documents.
-    def update_documents_json(documents, primary_key = nil)
+    def update_documents_json(documents, primary_key = nil, skip_creation: nil)
       options = { convert_body?: false }
-      response = http_put "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+      response = http_put "/indexes/#{@uid}/documents", documents,
+                          { primaryKey: primary_key, skipCreation: skip_creation }.compact, options
 
       Models::Task.new(response, task_endpoint)
     end
@@ -287,9 +295,10 @@ def update_documents_json(documents, primary_key = nil)
     # @return [Models::Task] The async task that adds the documents.
     #
     # @see https://github.com/ndjson/ndjson-spec NDJSON spec
-    def update_documents_ndjson(documents, primary_key = nil)
+    def update_documents_ndjson(documents, primary_key = nil, skip_creation: nil)
       options = { headers: { 'Content-Type' => 'application/x-ndjson' }, convert_body?: false }
-      response = http_put "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+      response = http_put "/indexes/#{@uid}/documents", documents,
+                          { primaryKey: primary_key, skipCreation: skip_creation }.compact, options
 
       Models::Task.new(response, task_endpoint)
     end
@@ -305,12 +314,13 @@ def update_documents_ndjson(documents, primary_key = nil)
     # @param delimiter [String] The delimiter character in your CSV text.
     #
     # @return [Models::Task] The async task that adds the documents.
-    def update_documents_csv(documents, primary_key = nil, delimiter = nil)
+    def update_documents_csv(documents, primary_key = nil, delimiter = nil, skip_creation: nil)
       options = { headers: { 'Content-Type' => 'text/csv' }, convert_body?: false }
 
       response = http_put "/indexes/#{@uid}/documents", documents, {
         primaryKey: primary_key,
-        csvDelimiter: delimiter
+        csvDelimiter: delimiter,
+        skipCreation: skip_creation
       }.compact, options
 
       Models::Task.new(response, task_endpoint)
@@ -326,9 +336,9 @@ def update_documents_csv(documents, primary_key = nil, delimiter = nil)
     # @return [Array<Models::Task>] An array of tasks for each batch.
     #
     # @see https://github.com/ndjson/ndjson-spec NDJSON spec
-    def update_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil)
+    def update_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil, skip_creation: nil)
       documents.lines.each_slice(batch_size).map do |batch|
-        update_documents_ndjson(batch.join, primary_key)
+        update_documents_ndjson(batch.join, primary_key, skip_creation: skip_creation)
       end
     end
 
@@ -340,11 +350,12 @@ def update_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key
     # @param delimiter [String] The delimiter character in your CSV text.
     #
     # @return [Array<Models::Task>] An array of tasks for each batch.
-    def update_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil)
+    def update_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil,
+                                        skip_creation: nil)
       lines = documents.lines
       heading = lines.first
       lines.drop(1).each_slice(batch_size).map do |batch|
-        update_documents_csv(heading + batch.join, primary_key, delimiter)
+        update_documents_csv(heading + batch.join, primary_key, delimiter, skip_creation: skip_creation)
       end
     end
 
@@ -373,9 +384,9 @@ def update_documents!(documents, primary_key = nil)
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
     #
     # @return [Array<Models::Task>] An array of tasks for each batch.
-    def add_documents_in_batches(documents, batch_size = 1000, primary_key = nil)
+    def add_documents_in_batches(documents, batch_size = 1000, primary_key = nil, skip_creation: nil)
       documents.each_slice(batch_size).map do |batch|
-        add_documents(batch, primary_key)
+        add_documents(batch, primary_key, skip_creation: skip_creation)
       end
     end
 
@@ -386,9 +397,9 @@ def add_documents_in_batches(documents, batch_size = 1000, primary_key = nil)
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
     #
     # @return [Array<Models::Task>] An array of tasks for each batch.
-    def add_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil)
+    def add_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil, skip_creation: nil)
       documents.lines.each_slice(batch_size).map do |batch|
-        add_documents_ndjson(batch.join, primary_key)
+        add_documents_ndjson(batch.join, primary_key, skip_creation: skip_creation)
       end
     end
 
@@ -400,11 +411,12 @@ def add_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key =
     # @param delimiter [String] The delimiter character in your CSV text.
     #
     # @return [Array<Models::Task>] An array of tasks for each batch.
-    def add_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil)
+    def add_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil,
+                                      skip_creation: nil)
       lines = documents.lines
       heading = lines.first
       lines.drop(1).each_slice(batch_size).map do |batch|
-        add_documents_csv(heading + batch.join, primary_key, delimiter)
+        add_documents_csv(heading + batch.join, primary_key, delimiter, skip_creation: skip_creation)
       end
     end
 
@@ -432,9 +444,9 @@ def add_documents_in_batches!(documents, batch_size = 1000, primary_key = nil)
     # @param primary_key [String] The name of the primary key field, auto inferred if missing.
     #
     # @return [Array<Models::Task>] An array of tasks for each batch.
-    def update_documents_in_batches(documents, batch_size = 1000, primary_key = nil)
+    def update_documents_in_batches(documents, batch_size = 1000, primary_key = nil, skip_creation: nil)
       documents.each_slice(batch_size).map do |batch|
-        update_documents(batch, primary_key)
+        update_documents(batch, primary_key, skip_creation: skip_creation)
       end
     end
 

spec/meilisearch/index/documents_spec.rb

@@ -61,6 +61,19 @@
           expect(client.index('books').fetch_primary_key).to eq('objectId')
           expect(client.index('books').documents['results'].count).to eq(documents.count)
         end
+
+        it 'adds documents without creating the index when skip_creation is false (default)' do
+          task = index.add_documents(documents, nil, skip_creation: false)
+          expect(task.type).to eq('documentAdditionOrUpdate')
+          task.await
+          expect(index.documents['results']).to contain_exactly(*documents_with_string_keys)
+        end
+
+        it 'fails with skip_creation: true when the index does not already exist' do
+          non_existing_index = client.index("non-existing-#{random_uid}")
+          task = non_existing_index.add_documents(documents, nil, skip_creation: true).await
+          expect(task).to have_failed
+        end
       end
 
       it 'adds documents in a batch (as a array of documents)' do