feat: Adds an optional skipCreation. When set to true, documents that…

.code-samples.meilisearch.yaml

@@ -42,13 +42,13 @@ add_or_replace_documents_1: |-
     'poster': 'https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg',
     '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: |-

meilisearch/index.py

@@ -454,6 +454,7 @@ def add_documents(
         primary_key: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Add documents to the index.
 
@@ -466,6 +467,9 @@ def add_documents(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -478,7 +482,7 @@ def add_documents(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        url = self._build_url(primary_key)
+        url = self._build_url(primary_key, skip_creation=skip_creation)
         add_document_task = self.http.post(url, documents, serializer=serializer)
         return TaskInfo(**add_document_task)
 
@@ -489,6 +493,7 @@ def add_documents_in_batches(
         primary_key: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> List[TaskInfo]:
         """Add documents to the index in batches.
 
@@ -503,6 +508,9 @@ def add_documents_in_batches(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -520,7 +528,9 @@ def add_documents_in_batches(
         tasks: List[TaskInfo] = []
 
         for document_batch in self._batch(documents, batch_size):
-            task = self.add_documents(document_batch, primary_key, serializer=serializer)
+            task = self.add_documents(
+                document_batch, primary_key, serializer=serializer, skip_creation=skip_creation
+            )
             tasks.append(task)
 
         return tasks
@@ -531,6 +541,7 @@ def add_documents_json(
         primary_key: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Add documents to the index from a byte-encoded JSON string.
 
@@ -543,6 +554,9 @@ def add_documents_json(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -556,14 +570,19 @@ def add_documents_json(
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
         return self.add_documents_raw(
-            str_documents, primary_key, "application/json", serializer=serializer
+            str_documents,
+            primary_key,
+            "application/json",
+            serializer=serializer,
+            skip_creation=skip_creation,
         )
 
     def add_documents_csv(
         self,
         str_documents: bytes,
         primary_key: Optional[str] = None,
         csv_delimiter: Optional[str] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Add documents to the index from a byte-encoded CSV string.
 
@@ -575,6 +594,9 @@ def add_documents_csv(
             The primary-key used in index. Ignored if already set up.
         csv_delimiter:
             One ASCII character used to customize the delimiter for CSV. Comma used by default.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -587,12 +609,15 @@ def add_documents_csv(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        return self.add_documents_raw(str_documents, primary_key, "text/csv", csv_delimiter)
+        return self.add_documents_raw(
+            str_documents, primary_key, "text/csv", csv_delimiter, skip_creation=skip_creation
+        )
 
     def add_documents_ndjson(
         self,
         str_documents: bytes,
         primary_key: Optional[str] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Add documents to the index from a byte-encoded NDJSON string.
 
@@ -602,6 +627,9 @@ def add_documents_ndjson(
             Byte-encoded NDJSON string.
         primary_key (optional):
             The primary-key used in index. Ignored if already set up.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -614,7 +642,9 @@ def add_documents_ndjson(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        return self.add_documents_raw(str_documents, primary_key, "application/x-ndjson")
+        return self.add_documents_raw(
+            str_documents, primary_key, "application/x-ndjson", skip_creation=skip_creation
+        )
 
     def add_documents_raw(
         self,
@@ -624,6 +654,7 @@ def add_documents_raw(
         csv_delimiter: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Add documents to the index from a byte-encoded string.
 
@@ -641,6 +672,9 @@ def add_documents_raw(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -653,7 +687,9 @@ def add_documents_raw(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        url = self._build_url(primary_key=primary_key, csv_delimiter=csv_delimiter)
+        url = self._build_url(
+            primary_key=primary_key, csv_delimiter=csv_delimiter, skip_creation=skip_creation
+        )
         response = self.http.post(url, str_documents, content_type, serializer=serializer)
         return TaskInfo(**response)
 
@@ -663,6 +699,7 @@ def update_documents(
         primary_key: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Update documents in the index.
 
@@ -675,6 +712,9 @@ def update_documents(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -687,14 +727,15 @@ def update_documents(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        url = self._build_url(primary_key)
+        url = self._build_url(primary_key, skip_creation=skip_creation)
         response = self.http.put(url, documents, serializer=serializer)
         return TaskInfo(**response)
 
     def update_documents_ndjson(
         self,
         str_documents: str,
         primary_key: Optional[str] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Update documents as a ndjson string in the index.
 
@@ -704,6 +745,9 @@ def update_documents_ndjson(
             String of document from a NDJSON file.
         primary_key (optional):
             The primary-key used in index. Ignored if already set up
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -716,14 +760,17 @@ def update_documents_ndjson(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        return self.update_documents_raw(str_documents, primary_key, "application/x-ndjson")
+        return self.update_documents_raw(
+            str_documents, primary_key, "application/x-ndjson", skip_creation=skip_creation
+        )
 
     def update_documents_json(
         self,
         str_documents: str,
         primary_key: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Update documents as a json string in the index.
 
@@ -736,6 +783,9 @@ def update_documents_json(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -749,14 +799,19 @@ def update_documents_json(
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
         return self.update_documents_raw(
-            str_documents, primary_key, "application/json", serializer=serializer
+            str_documents,
+            primary_key,
+            "application/json",
+            serializer=serializer,
+            skip_creation=skip_creation,
         )
 
     def update_documents_csv(
         self,
         str_documents: str,
         primary_key: Optional[str] = None,
         csv_delimiter: Optional[str] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Update documents as a csv string in the index.
 
@@ -768,6 +823,9 @@ def update_documents_csv(
             The primary-key used in index. Ignored if already set up.
         csv_delimiter:
             One ASCII character used to customize the delimiter for CSV. Comma used by default.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -780,7 +838,9 @@ def update_documents_csv(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        return self.update_documents_raw(str_documents, primary_key, "text/csv", csv_delimiter)
+        return self.update_documents_raw(
+            str_documents, primary_key, "text/csv", csv_delimiter, skip_creation=skip_creation
+        )
 
     def update_documents_raw(
         self,
@@ -790,6 +850,7 @@ def update_documents_raw(
         csv_delimiter: Optional[str] = None,
         *,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> TaskInfo:
         """Update documents as a string in the index.
 
@@ -807,6 +868,9 @@ def update_documents_raw(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -819,7 +883,9 @@ def update_documents_raw(
         MeilisearchApiError
             An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
         """
-        url = self._build_url(primary_key=primary_key, csv_delimiter=csv_delimiter)
+        url = self._build_url(
+            primary_key=primary_key, csv_delimiter=csv_delimiter, skip_creation=skip_creation
+        )
         response = self.http.put(url, str_documents, content_type, serializer=serializer)
         return TaskInfo(**response)
 
@@ -829,6 +895,7 @@ def update_documents_in_batches(
         batch_size: int = 1000,
         primary_key: Optional[str] = None,
         serializer: Optional[Type[JSONEncoder]] = None,
+        skip_creation: Optional[bool] = None,
     ) -> List[TaskInfo]:
         """Update documents to the index in batches.
 
@@ -843,6 +910,9 @@ def update_documents_in_batches(
         serializer (optional):
             A custom JSONEncode to handle serializing fields that the build in json.dumps
             cannot handle, for example UUID and datetime.
+        skip_creation (optional):
+            If True, documents that don't exist in the index are silently ignored rather
+            than created. If False or None (default), existing behavior is preserved.
 
         Returns
         -------
@@ -860,7 +930,9 @@ def update_documents_in_batches(
         tasks = []
 
         for document_batch in self._batch(documents, batch_size):
-            update_task = self.update_documents(document_batch, primary_key, serializer=serializer)
+            update_task = self.update_documents(
+                document_batch, primary_key, serializer=serializer, skip_creation=skip_creation
+            )
             tasks.append(update_task)
 
         return tasks
@@ -2331,13 +2403,16 @@ def _build_url(
         self,
         primary_key: Optional[str] = None,
         csv_delimiter: Optional[str] = None,
+        skip_creation: Optional[bool] = None,
     ) -> str:
         parameters = {}
         if primary_key:
             parameters["primaryKey"] = primary_key
         if csv_delimiter:
             parameters["csvDelimiter"] = csv_delimiter
-        if primary_key is None and csv_delimiter is None:
+        if skip_creation is True:
+            parameters["skipCreation"] = "true"
+        if not parameters:
             return f"{self.config.paths.index}/{self.uid}/{self.config.paths.document}"
         return f"{self.config.paths.index}/{self.uid}/{self.config.paths.document}?{parse.urlencode(parameters)}"