Merge #907

907: Add support for custom metadata in document operations r=curquiza a=Osireg17

# Pull Request

## Related issue
Fixes #905

## What does this PR do?
This pull request adds support for passing custom metadata when performing document operations in the Meilisearch Java SDK. The main changes include updating the `Documents` and `Index` classes to accept an optional `customMetadata` parameter for add, update, and delete operations, storing this metadata in the `Task` model, and introducing comprehensive integration tests to validate the new functionality.

### Model changes

* Updated the `Task` model (`Task.java`) to include a `customMetadata` field, ensuring that metadata attached to tasks is stored and accessible.

### Test coverage

* Added multiple integration tests in `DocumentsTest.java` to verify that custom metadata is correctly attached and retrievable for all document operations (add, update, delete single, delete batch, delete by filter, delete all).


## PR checklist
Please check if your PR fulfills the following requirements:
- [ ] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [ ] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added support for custom metadata across all document operations including add, update, single/batch delete, filter-based delete, and delete-all operations. Custom metadata can now be attached to document operations and is included in task responses.

<sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Osi Obomighie <93836683+Osireg17@users.noreply.github.com>

Author: meili-bors[bot]

src/main/java/com/meilisearch/sdk/Documents.java

@@ -161,13 +161,37 @@ String getRawDocuments(String uid, DocumentsQuery param) throws MeilisearchExcep
      */
     TaskInfo addDocuments(String uid, String document, String primaryKey, String csvDelimiter)
             throws MeilisearchException {
+        return addDocuments(uid, document, primaryKey, csvDelimiter, null);
+    }
+
+    /**
+     * Adds/Replaces a document at the specified index uid
+     *
+     * @param uid Partial index identifier for the document
+     * @param document String containing the document to add
+     * @param primaryKey PrimaryKey of the document
+     * @param csvDelimiter CSV delimiter of the document
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo addDocuments(
+            String uid,
+            String document,
+            String primaryKey,
+            String csvDelimiter,
+            String customMetadata)
+            throws MeilisearchException {
         URLBuilder urlb = documentPath(uid);
         if (primaryKey != null) {
             urlb.addParameter("primaryKey", primaryKey);
         }
         if (csvDelimiter != null) {
             urlb.addParameter("csvDelimiter", csvDelimiter);
         }
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
         return httpClient.post(urlb.getURL(), document, TaskInfo.class);
     }
 
@@ -182,13 +206,37 @@ TaskInfo addDocuments(String uid, String document, String primaryKey, String csv
      */
     TaskInfo updateDocuments(String uid, String document, String primaryKey, String csvDelimiter)
             throws MeilisearchException {
+        return updateDocuments(uid, document, primaryKey, csvDelimiter, null);
+    }
+
+    /**
+     * Replaces a document at the specified index uid
+     *
+     * @param uid Partial index identifier for the document
+     * @param document String containing the document to replace the existing document
+     * @param primaryKey PrimaryKey of the document
+     * @param csvDelimiter CSV delimiter of the document
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo updateDocuments(
+            String uid,
+            String document,
+            String primaryKey,
+            String csvDelimiter,
+            String customMetadata)
+            throws MeilisearchException {
         URLBuilder urlb = documentPath(uid);
         if (primaryKey != null) {
             urlb.addParameter("primaryKey", primaryKey);
         }
         if (csvDelimiter != null) {
             urlb.addParameter("csvDelimiter", csvDelimiter);
         }
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
         return httpClient.put(urlb.getURL(), document, TaskInfo.class);
     }
 
@@ -201,7 +249,25 @@ TaskInfo updateDocuments(String uid, String document, String primaryKey, String
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteDocument(String uid, String identifier) throws MeilisearchException {
-        return httpClient.<TaskInfo>delete(documentPath(uid, identifier).getURL(), TaskInfo.class);
+        return deleteDocument(uid, identifier, null);
+    }
+
+    /**
+     * Deletes the document from the specified index uid with the specified identifier
+     *
+     * @param uid Partial index identifier for the requested document
+     * @param identifier ID of the document
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo deleteDocument(String uid, String identifier, String customMetadata)
+            throws MeilisearchException {
+        URLBuilder urlb = documentPath(uid, identifier);
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
+        return httpClient.<TaskInfo>delete(urlb.getURL(), TaskInfo.class);
     }
 
     /**
@@ -213,7 +279,24 @@ TaskInfo deleteDocument(String uid, String identifier) throws MeilisearchExcepti
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteDocuments(String uid, List<String> identifiers) throws MeilisearchException {
+        return deleteDocuments(uid, identifiers, null);
+    }
+
+    /**
+     * Deletes the documents at the specified index uid with the specified identifiers
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @param identifiers ID of documents to delete
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo deleteDocuments(String uid, List<String> identifiers, String customMetadata)
+            throws MeilisearchException {
         URLBuilder urlb = documentPath(uid).addSubroute("delete-batch");
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
         return httpClient.post(urlb.getURL(), identifiers, TaskInfo.class);
     }
 
@@ -226,13 +309,30 @@ TaskInfo deleteDocuments(String uid, List<String> identifiers) throws Meilisearc
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteDocumentsByFilter(String uid, String filter) throws MeilisearchException {
+        return deleteDocumentsByFilter(uid, filter, null);
+    }
+
+    /**
+     * Deletes the documents matching the given filter
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @param filter filter to match the documents on
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo deleteDocumentsByFilter(String uid, String filter, String customMetadata)
+            throws MeilisearchException {
         if (filter == null || filter.isEmpty()) {
             throw new MeilisearchException(
                     "Null or blank filter not allowed while deleting documents");
         }
         HashMap<String, String> filterMap = new HashMap<>();
         filterMap.put("filter", filter);
         URLBuilder urlb = documentPath(uid).addSubroute("delete");
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
         return httpClient.post(urlb.getURL(), filterMap, TaskInfo.class);
     }
 
@@ -244,7 +344,23 @@ TaskInfo deleteDocumentsByFilter(String uid, String filter) throws MeilisearchEx
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteAllDocuments(String uid) throws MeilisearchException {
-        return httpClient.<TaskInfo>delete(documentPath(uid).getURL(), TaskInfo.class);
+        return deleteAllDocuments(uid, null);
+    }
+
+    /**
+     * Deletes all documents at the specified index uid
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @param customMetadata Custom metadata to attach to the task
+     * @return Meilisearch's TaskInfo API response
+     * @throws MeilisearchException if the client request causes an error
+     */
+    TaskInfo deleteAllDocuments(String uid, String customMetadata) throws MeilisearchException {
+        URLBuilder urlb = documentPath(uid);
+        if (customMetadata != null) {
+            urlb.addParameter("customMetadata", customMetadata);
+        }
+        return httpClient.<TaskInfo>delete(urlb.getURL(), TaskInfo.class);
     }
 
     /** Creates an URLBuilder for the constant route documents. */

src/main/java/com/meilisearch/sdk/Index.java

@@ -204,6 +204,26 @@ public TaskInfo addDocuments(String document, String primaryKey, String csvDelim
         return this.documents.addDocuments(this.uid, document, primaryKey, csvDelimiter);
     }
 
+    /**
+     * Adds/Replaces documents in the index
+     *
+     * @param document Document to add in JSON or CSV string format
+     * @param primaryKey PrimaryKey of the document to add
+     * @param csvDelimiter Custom delimiter to use for the document being added
+     * @param customMetadata Custom metadata to attach to the task
+     * @return TaskInfo Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents">API
+     *     specification</a>
+     */
+    public TaskInfo addDocuments(
+            String document, String primaryKey, String csvDelimiter, String customMetadata)
+            throws MeilisearchException {
+        return this.documents.addDocuments(
+                this.uid, document, primaryKey, csvDelimiter, customMetadata);
+    }
+
     /**
      * Adds/Replaces documents in the index in batches
      *
@@ -298,6 +318,26 @@ public TaskInfo updateDocuments(String document, String primaryKey, String csvDe
         return this.documents.updateDocuments(this.uid, document, primaryKey, csvDelimiter);
     }
 
+    /**
+     * Updates documents in the index
+     *
+     * @param document Document to update in JSON or CSV string format
+     * @param primaryKey PrimaryKey of the document
+     * @param csvDelimiter Custom delimiter to use for the document being added
+     * @param customMetadata Custom metadata to attach to the task
+     * @return TaskInfo Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents">API
+     *     specification</a>
+     */
+    public TaskInfo updateDocuments(
+            String document, String primaryKey, String csvDelimiter, String customMetadata)
+            throws MeilisearchException {
+        return this.documents.updateDocuments(
+                this.uid, document, primaryKey, csvDelimiter, customMetadata);
+    }
+
     /**
      * Updates documents in index in batches
      *
@@ -359,6 +399,22 @@ public TaskInfo deleteDocument(String identifier) throws MeilisearchException {
         return this.documents.deleteDocument(this.uid, identifier);
     }
 
+    /**
+     * Deletes a document from the index
+     *
+     * @param identifier Identifier of the document to delete
+     * @param customMetadata Custom metadata to attach to the task
+     * @return TaskInfo Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#delete-one-document">API
+     *     specification</a>
+     */
+    public TaskInfo deleteDocument(String identifier, String customMetadata)
+            throws MeilisearchException {
+        return this.documents.deleteDocument(this.uid, identifier, customMetadata);
+    }
+
     /**
      * Deletes list of documents from the index
      *
@@ -375,6 +431,24 @@ public TaskInfo deleteDocuments(List<String> documentsIdentifiers) throws Meilis
         return this.documents.deleteDocuments(this.uid, documentsIdentifiers);
     }
 
+    /**
+     * Deletes list of documents from the index
+     *
+     * @param documentsIdentifiers list of identifiers of documents to delete
+     * @param customMetadata Custom metadata to attach to the task
+     * @return TaskInfo Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#delete-documents-by-batch">API
+     *     specification</a>
+     * @see com.meilisearch.sdk.Index#deleteDocumentsByFilter(String) Delete documents using filter
+     */
+    @Deprecated
+    public TaskInfo deleteDocuments(List<String> documentsIdentifiers, String customMetadata)
+            throws MeilisearchException {
+        return this.documents.deleteDocuments(this.uid, documentsIdentifiers, customMetadata);
+    }
+
     /**
      * Deletes list of documents from the index using the given filter
      *
@@ -390,6 +464,23 @@ public TaskInfo deleteDocumentsByFilter(String filter) throws MeilisearchExcepti
         return this.documents.deleteDocumentsByFilter(this.uid, filter);
     }
 
+    /**
+     * Deletes list of documents from the index using the given filter
+     *
+     * @param filter filter to match the documents to delete
+     * @param customMetadata Custom metadata to attach to the task
+     * @return TaskInfo Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#delete-documents-by-filter">API
+     *     specification</a>
+     * @since 1.2
+     */
+    public TaskInfo deleteDocumentsByFilter(String filter, String customMetadata)
+            throws MeilisearchException {
+        return this.documents.deleteDocumentsByFilter(this.uid, filter, customMetadata);
+    }
+
     /**
      * Deletes all documents in the index
      *
@@ -403,6 +494,20 @@ public TaskInfo deleteAllDocuments() throws MeilisearchException {
         return this.documents.deleteAllDocuments(this.uid);
     }
 
+    /**
+     * Deletes all documents in the index
+     *
+     * @param customMetadata Custom metadata to attach to the task
+     * @return List of tasks Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/documents#delete-all-documents">API
+     *     specification</a>
+     */
+    public TaskInfo deleteAllDocuments(String customMetadata) throws MeilisearchException {
+        return this.documents.deleteAllDocuments(this.uid, customMetadata);
+    }
+
     /**
      * Searches documents in the index
      *

src/main/java/com/meilisearch/sdk/model/Task.java

@@ -20,6 +20,7 @@ public class Task {
     protected Date finishedAt = null;
     protected TaskError error = null;
     protected TaskDetails details = null;
+    protected String customMetadata = null;
 
     public Task() {}
 }