Add support for custom metadata in document operations

[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)?
• 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!

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.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR adds support for attaching custom metadata to document operations in the Meilisearch Java SDK. New overloaded methods are introduced in the Documents and Index classes to accept an optional customMetadata string parameter, which is conditionally appended as a query parameter to API requests. A corresponding customMetadata field is added to the Task model, and integration tests are provided to validate the functionality.

Changes

Cohort / File(s)	Change Summary
Document Operations in Documents class src/main/java/com/meilisearch/sdk/Documents.java	Six new overloads added: addDocuments, updateDocuments, deleteDocument, deleteDocuments, deleteDocumentsByFilter, and deleteAllDocuments, each accepting an optional customMetadata parameter. Existing overloads delegate to new versions with null metadata to preserve backward compatibility.
Document Operations in Index class src/main/java/com/meilisearch/sdk/Index.java	Six corresponding public methods added that delegate to the Documents class overloads, passing through customMetadata. One deleteDocuments batch variant marked @Deprecated.
Task Model src/main/java/com/meilisearch/sdk/model/Task.java	New field added: protected String customMetadata = null to store metadata returned from API responses.
Integration Tests src/test/java/com/meilisearch/integration/DocumentsTest.java	Six test methods added: testAddDocumentsWithCustomMetadata, testUpdateDocumentsWithCustomMetadata, testDeleteDocumentWithCustomMetadata, testDeleteDocumentsBatchWithCustomMetadata, testDeleteDocumentsByFilterWithCustomMetadata, and testDeleteAllDocumentsWithCustomMetadata. Each validates metadata handling and task result assertions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Repetitive pattern application: The same delegation logic is applied consistently across six methods in each of two classes, reducing cognitive load per method.
• Straightforward logic: All additions involve parameter threading and conditional query parameter attachment with no complex control flow.
• Homogeneous test structure: Integration tests follow a consistent pattern of operation → assertion, minimizing per-test review complexity.
• Areas for attention:
  • Verify that null-checking for customMetadata is consistent across all overloads in both Documents and Index.
  • Confirm that the URL parameter encoding handles special characters in customMetadata values correctly.
  • Ensure the Task.java field addition supports proper serialization/deserialization by the JSON framework in use.

Poem

🐰 Metadata now travels with every task we send,
Custom whispers attached from beginning to end,
Add, update, delete—all operations now speak,
With metadata magic, our workflows complete! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding support for custom metadata in document operations across the SDK.
Linked Issues check	✅ Passed	The PR implements all required objectives: adds customMetadata parameters to all specified document operation endpoints, updates the Task model, and includes comprehensive integration tests.
Out of Scope Changes check	✅ Passed	All changes are directly related to issue #905 and adding custom metadata support to document operations; no extraneous modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 96.88% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

src/main/java/com/meilisearch/sdk/Index.java (2)

434-450: Deprecated method receives new overload.

While technically correct, adding a customMetadata parameter to the deprecated deleteDocuments method may encourage continued use. Consider whether this aligns with your deprecation strategy.

---

239-258: Consider adding customMetadata support to batch operations.

The addDocumentsInBatches and updateDocumentsInBatches methods don't support the new customMetadata parameter. This means users performing batch operations cannot attach custom metadata to individual batch tasks.

If this is intentional (e.g., due to implementation complexity), consider documenting this limitation. Otherwise, add overloads that accept customMetadata:

public TaskInfo[] addDocumentsInBatches(String document, Integer batchSize, String primaryKey, String customMetadata)
        throws MeilisearchException {
    // ... existing logic, but pass customMetadata to addDocuments calls
    arrayResponses.add(
            this.documents.addDocuments(
                    this.uid, jsonSubArray.toString(), primaryKey, null, customMetadata));
    // ...
}

Also applies to: 353-372

src/test/java/com/meilisearch/integration/DocumentsTest.java (1)

735-867: Consider adding edge case tests for custom metadata.

The current tests cover the happy path well, but consider adding tests for edge cases to ensure robustness:

• Special characters in metadata (quotes, Unicode, etc.)
• Very long metadata strings
• Empty string vs null metadata (to ensure they behave as expected)

Example test skeleton:

@Test
public void testAddDocumentsWithSpecialCharactersInCustomMetadata() throws Exception {
    String indexUid = "AddDocumentsSpecialCharsMetadata";
    Index index = client.index(indexUid);
    
    String specialMetadata = "metadata with \"quotes\" and 日本語";
    TaskInfo task = index.addDocuments("[" + singleDocument + "]", null, null, specialMetadata);
    
    index.waitForTask(task.getTaskUid());
    com.meilisearch.sdk.model.Task taskDetails = index.getTask(task.getTaskUid());
    assertThat(taskDetails.getCustomMetadata(), is(equalTo(specialMetadata)));
}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 45861af and 23bcabe.

📒 Files selected for processing (4)

• src/main/java/com/meilisearch/sdk/Documents.java (6 hunks)
• src/main/java/com/meilisearch/sdk/Index.java (6 hunks)
• src/main/java/com/meilisearch/sdk/model/Task.java (1 hunks)
• src/test/java/com/meilisearch/integration/DocumentsTest.java (1 hunks)

🔇 Additional comments (18)

src/main/java/com/meilisearch/sdk/model/Task.java (1)

23-23: LGTM!

The customMetadata field addition is appropriate for capturing custom metadata from task responses. The field will be automatically serialized/deserialized via the JSON handler, and Lombok's @Getter will provide accessor methods.

src/main/java/com/meilisearch/sdk/Documents.java (6)

207-241: LGTM! Consistent implementation.

The updateDocuments method follows the same backward-compatible pattern as addDocuments.

---

251-271: LGTM! Consistent implementation.

The deleteDocument method follows the established pattern.

---

281-301: LGTM! Consistent implementation.

The deleteDocuments batch method follows the established pattern.

---

311-337: LGTM! Consistent implementation.

The deleteDocumentsByFilter method follows the established pattern.

---

346-364: LGTM! Consistent implementation.

The deleteAllDocuments method follows the established pattern.

---

162-196: URL encoding is not currently implemented in URLBuilder; verify this aligns with API design expectations.

The URLBuilder.addParameter() method appends parameter values directly without URL encoding them. This applies to all parameters—including customMetadata, primaryKey, and csvDelimiter—and is a pre-existing pattern, not specific to this PR. While the implementation is consistent with the existing design, special characters (spaces, quotes, ampersands, etc.) in the customMetadata value could potentially break URL parsing or cause unexpected behavior if not handled by the caller or HTTP client.

No integration tests verify customMetadata with special characters, and no URLEncoder usage exists in the codebase for parameter encoding.

src/main/java/com/meilisearch/sdk/Index.java (5)

207-225: LGTM! Clean delegation pattern.

The new addDocuments overload properly delegates to the Documents class with the customMetadata parameter.

---

321-339: LGTM! Consistent delegation.

The new updateDocuments overload follows the same delegation pattern.

---

402-416: LGTM! Consistent delegation.

The new deleteDocument overload follows the established pattern.

---

467-482: LGTM! Consistent delegation.

The new deleteDocumentsByFilter overload follows the established pattern.

---

497-509: LGTM! Consistent delegation.

The new deleteAllDocuments overload follows the established pattern.

src/test/java/com/meilisearch/integration/DocumentsTest.java (6)

735-753: LGTM! Good test coverage for add operation.

The test properly verifies that custom metadata is attached to the add documents task and can be retrieved.

---

755-776: LGTM! Good test coverage for update operation.

The test properly verifies custom metadata handling for update operations.

---

778-797: LGTM! Good test coverage for single document deletion.

The test properly verifies custom metadata handling for single document deletion.

---

799-819: LGTM! Good test coverage for batch deletion.

The test properly verifies custom metadata handling for batch document deletion.

---

821-843: LGTM! Good test coverage for filter-based deletion.

The test properly verifies custom metadata handling for filter-based document deletion.

---

845-867: LGTM! Good test coverage for delete all operation.

The test properly verifies custom metadata handling for deleting all documents.

[curquiza]

Thank you

bors merge

[meili-bors]

Build succeeded:

• integration-and-unit-tests
• linter