Merge pull request #1189 from awais786/allow_skip_creation

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

Author: Strift

.code-samples.meilisearch.yaml

@@ -54,13 +54,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

@@ -482,6 +482,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.
 
@@ -494,6 +495,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
         -------
@@ -506,7 +510,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)
 
@@ -517,6 +521,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.
 
@@ -531,6 +536,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
         -------
@@ -548,7 +556,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
@@ -559,6 +569,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.
 
@@ -571,6 +582,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
         -------
@@ -584,14 +598,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.
 
@@ -603,6 +622,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
         -------
@@ -615,12 +637,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.
 
@@ -630,6 +655,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
         -------
@@ -642,7 +670,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,
@@ -652,6 +682,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.
 
@@ -669,6 +700,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
         -------
@@ -681,7 +715,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)
 
@@ -691,6 +727,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.
 
@@ -703,6 +740,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
         -------
@@ -715,14 +755,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.
 
@@ -732,6 +773,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
         -------
@@ -744,14 +788,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.
 
@@ -764,6 +811,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
         -------
@@ -777,14 +827,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.
 
@@ -796,6 +851,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
         -------
@@ -808,7 +866,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,
@@ -818,6 +878,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.
 
@@ -835,6 +896,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
         -------
@@ -847,7 +911,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)
 
@@ -857,6 +923,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.
 
@@ -871,6 +938,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
         -------
@@ -888,7 +958,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
@@ -2359,13 +2431,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)}"