feat: add custom metadata support for document tasks

[kumarUjjawal]

Pull Request

Related issue

Fixes #733

What does this PR do?

• ...

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 custom metadata support for all document operations. Users can now attach optional custom metadata to add, update, and delete operations. Metadata is preserved and included in task responses, enabling better tracking, categorization, and monitoring of document operations throughout their lifecycle.

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

[coderabbitai]

Walkthrough

The PR adds custom metadata support to document operations across the Meilisearch SDK, aligning with v1.26 API capabilities. Document operation methods now accept an optional custom_metadata parameter, task structs include a new custom_metadata field, and HTTP requests propagate metadata via a DocumentTaskQuery wrapper.

Changes

Cohort / File(s)	Summary
Core Index API src/indexes.rs	Updated 13 document operation methods (add_or_replace, add_documents, add_or_update, add_documents_in_batches, update_documents_in_batches, update_documents_ndjson, add_documents_ndjson, update_documents_csv, add_documents_csv, delete_all_documents, delete_document, delete_documents, delete_documents_with) to accept optional custom_metadata: Option<&str> parameter. Internal calls now construct and pass DocumentTaskQuery with metadata.
Document Deletion API src/documents.rs	Added DocumentDeletionQuery::execute_with_custom_metadata method; execute now delegates to it. Updated delete_documents_with signature to accept custom_metadata parameter. All test call sites updated.
Client API src/client.rs	Updated public method call sites for add_or_replace, add_documents, and delete_all_documents to pass additional None argument for metadata in examples and tests.
Task-related Structures src/task_info.rs, src/tasks.rs	Added pub custom_metadata: Option<String> field to TaskInfo, SucceededTask, EnqueuedTask, and ProcessingTask. Deserialization includes customMetadata JSON mapping via serde camelCase.
Examples and Documentation examples/cli-app-with-awc/src/main.rs, examples/cli-app/src/main.rs, examples/web_app_graphql/src/graphql_schema/users/query/search.rs, src/lib.rs, src/search.rs	Updated all call sites for document operations to pass None for custom_metadata parameter. Tests updated to validate metadata propagation and handle new struct fields.

Sequence Diagram

sequenceDiagram
    participant App
    participant Index
    participant DocumentTaskQuery
    participant HTTP
    participant TaskInfo

    App->>Index: add_documents(docs, pk, Some("batch-1"))
    Index->>DocumentTaskQuery: new(pk, Some("batch-1"))
    Index->>HTTP: POST /documents with DocumentTaskQuery payload
    HTTP->>TaskInfo: response with customMetadata
    TaskInfo->>App: TaskInfo { custom_metadata: Some("batch-1"), ... }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Areas requiring attention:

• Method signature changes across indexes.rs (13 methods) — verify parameter order consistency and default handling
• DocumentTaskQuery wrapper implementation — confirm proper serialization and metadata propagation
• Struct field additions in task_info.rs and tasks.rs — verify deserialization of customMetadata field
• Breaking API changes — confirm all public method signatures maintain backward compatibility requirements or document breaking changes
• Example and test updates — spot-check representative samples to ensure consistent pattern application

Suggested labels

breaking-change

Suggested reviewers

• curquiza

Poem

🐰 Metadata flows like morning dew,
Through tasks both old and shiny new,
Each document now carries a name,
In batches of glory and tracked fame! 📦✨

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 clearly and concisely describes the main feature being added: custom metadata support for document tasks.
Linked Issues check	✅ Passed	The PR comprehensively addresses all requirements from issue #733: updates all listed API endpoint methods to accept optional metadata, adds metadata support to TaskInfo and task structs, and includes test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly related to adding custom metadata support for document tasks as specified in issue #733; no unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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/tasks.rs (1)

154-175: Expose custom_metadata on task variants in a backward-compatible way

Adding pub custom_metadata: Option<String> to SucceededTask, EnqueuedTask, and ProcessingTask under #[serde(rename_all = "camelCase")] correctly maps the server’s customMetadata field and remains backward-compatible for deserialization (field is optional and existing JSON still matches via .. patterns in tests). Consider adding a brief doc comment on this field to make its relation to Meilisearch’s “tasks custom metadata” feature explicit for SDK users.

Also applies to: 183-196, 204-219

src/documents.rs (1)

415-427: DocumentDeletionQuery metadata extension looks correct and keeps API stable

execute delegating to execute_with_custom_metadata with None preserves the old API while adding the new capability. Lifetimes on custom_metadata: Option<&'a str> are consistent with the struct’s lifetime, and the call into Index::delete_documents_with matches the new signature.

One minor nit: the generic T: DeserializeOwned + 'static on both methods is now unused; if you ever do a breaking release, consider simplifying these to non‑generic fns or adding a PhantomData<T> to avoid the unused type parameter warning. For now, this is harmless and keeps source compatibility.

src/indexes.rs (1)

592-666: Write/update document routes correctly propagate custom_metadata

For add_or_replace, add_documents, add_or_update, and their *_unchecked_payload / NDJSON / CSV variants, the extra custom_metadata: Option<&str> is consistently threaded into a DocumentTaskQuery::new(primary_key, custom_metadata) used as the request’s query payload. This keeps existing primary key behavior intact while adding metadata support on all the expected code paths, including streaming ones.

Given the repeated pattern (build URL, construct DocumentTaskQuery, then call request or stream_request), you might later consider a small private helper to reduce duplication, but it’s not necessary for clarity or correctness right now.

Also applies to: 706-739, 779-846, 884-940, 942-1013, 1055-1078

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 16a31ae and 0fad2af.

📒 Files selected for processing (10)

• examples/cli-app-with-awc/src/main.rs (1 hunks)
• examples/cli-app/src/main.rs (1 hunks)
• examples/web_app_graphql/src/graphql_schema/users/query/search.rs (2 hunks)
• src/client.rs (6 hunks)
• src/documents.rs (5 hunks)
• src/indexes.rs (51 hunks)
• src/lib.rs (2 hunks)
• src/search.rs (3 hunks)
• src/task_info.rs (5 hunks)
• src/tasks.rs (5 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-06-12T13:28:23.700Z

Learnt from: LukasKalbertodt
Repo: meilisearch/meilisearch-rust PR: 625
File: src/search.rs:368-370
Timestamp: 2025-06-12T13:28:23.700Z
Learning: In the Meilisearch Rust client, `SearchQuery` serializes its per-query federation settings under the key `federationOptions`; only the top-level multi-search parameter is named `federation`.

Applied to files:

• src/client.rs

🧬 Code graph analysis (7)

src/tasks.rs (1)

src/client.rs (2)

• None (1532-1532)
• None (1613-1613)

src/task_info.rs (1)

src/client.rs (2)

• None (1532-1532)
• None (1613-1613)

examples/cli-app-with-awc/src/main.rs (1)

src/client.rs (2)

• None (1532-1532)
• None (1613-1613)

src/search.rs (1)

src/client.rs (2)

• None (1532-1532)
• None (1613-1613)

examples/cli-app/src/main.rs (1)

src/client.rs (2)

• None (1532-1532)
• None (1613-1613)

src/client.rs (2)

src/reqwest.rs (1)

• qualified_version (131-135)

src/batches.rs (3)

• None (141-141)
• None (169-169)
• None (193-193)

src/indexes.rs (2)

src/documents.rs (7)

• new (89-94)
• new (218-228)
• new (400-405)
• index (62-64)
• index (161-161)
• index (383-383)
• index (544-544)

src/request.rs (1)

• query (39-47)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: integration-tests

🔇 Additional comments (16)

examples/cli-app-with-awc/src/main.rs (1)

186-194: Example call correctly updated for new add_or_update signature

Adding the trailing None keeps this example in sync with the new add_or_update API while preserving existing behavior (no custom metadata sent).

src/lib.rs (2)

29-38: Top-level “Add Documents” doctest matches extended add_documents API

The extra None parameter correctly accounts for the new optional metadata argument without changing the example’s behavior.

---

182-190: Filterable attributes doctest updated consistently for metadata argument

This doctest’s add_documents call now matches the three-argument signature and keeps the example behavior intact by passing None metadata.

examples/web_app_graphql/src/graphql_schema/users/query/search.rs (1)

24-38: GraphQL example updated correctly for add_documents metadata parameter

Both add_documents calls now include the new optional metadata argument as None, keeping control flow and behavior identical while aligning with the updated API.

examples/cli-app/src/main.rs (1)

110-118: CLI example synchronized with new add_or_update signature

The additional None argument for metadata is correct and keeps this example compiling and behaving as before.

src/tasks.rs (1)

290-299: Docs and tests now use three-argument add_documents consistently

The Task docs example and all affected tests now call add_documents with (…, primary_key_opt, None) which matches the extended API and keeps the existing semantics (no metadata) while exercising the new parameter.

Also applies to: 935-961, 1225-1238, 1258-1289

src/task_info.rs (1)

9-18: TaskInfo now surfaces custom_metadata with solid deserialization coverage

Exposing pub custom_metadata: Option<String> on TaskInfo (camelCase serde) matches the server field, and the updated test_deserialize_task_info verifies correct mapping from "customMetadata". The updated add_documents(&[..], None, None) usage in the async test keeps behavior unchanged while aligning with the new API.

Also applies to: 114-141, 145-176

src/search.rs (1)

972-985: Search examples/tests correctly updated for metadata-aware document APIs

The facet-search documentation now calls add_or_replace with the extra metadata argument as None, and both setup_test_index helpers use the three-argument add_documents signature. All of these keep test and example behavior intact while matching the new API.

Also applies to: 1225-1238, 1258-1289

src/client.rs (2)

167-191: Client documentation kept in sync with extended document/task APIs

The multi-search, wait_for_task, and get_task examples now use add_or_replace, add_documents, and delete_all_documents with their updated signatures (extra metadata or options argument), consistently passing None where no metadata is desired. This maintains example behavior while matching the new public API surface.

Also applies to: 889-919, 956-968

---

1548-1549: Tests correctly import qualified_version and use new add_documents signature

Bringing reqwest::qualified_version into scope matches its use in test_methods_has_qualified_version_as_header, and the two add_documents calls in test_swapping_two_indexes now include the trailing None metadata argument, keeping the test logic unchanged but compatible with the updated API.

Also applies to: 1560-1580

src/documents.rs (1)

144-144: Updated call sites for extra custom_metadata parameter are consistent

The additional None arguments wired into add_or_replace in the doctest, setup_test_index, and the two delete_documents_with test calls align with the new API and keep existing behavior (no metadata) unchanged.

Also applies to: 488-488, 540-541, 569-570

src/indexes.rs (5)

80-103: DocumentTaskQuery design matches Meilisearch query conventions

The internal DocumentTaskQuery<'a> cleanly encapsulates primary_key and custom_metadata with #[serde(rename_all = "camelCase")] and skip_serializing_if = "Option::is_none", which should serialize to the expected primaryKey / customMetadata query parameters only when present. Using separate constructors (new and with_metadata) keeps call sites clear between routes that also set a primary key and those that only tag tasks.

No issues from a correctness perspective.

---

1080-1131: Delete document APIs now support per-task metadata without changing semantics

delete_all_documents, delete_document, delete_documents, and delete_documents_with now all accept custom_metadata: Option<&str> and wrap it via DocumentTaskQuery::with_metadata(custom_metadata) passed as the query component of the HTTP method. Bodies (when present) remain unchanged, so server-side behavior for filters and ID lists is preserved; only the optional metadata is new.

The use of Method::<_, ()>::Delete { query } for DELETE routes is type-correct with the generic Method<Q, B> definition, and lifetimes on the borrowed &str metadata are no stricter than existing borrowed query structs elsewhere in this module.

Also applies to: 1133-1185, 1187-1242, 1285-1302

---

1673-1687: Batch helpers correctly fan out custom_metadata per produced task

add_documents_in_batches and update_documents_in_batches now accept custom_metadata: Option<&str> and forward it unchanged into each inner add_documents / add_or_update call. This matches the doc comments that every task produced by the batch is tagged with the same metadata.

Capacity reservation is still based on the document count (existing behavior); no new performance or correctness concerns introduced here.

Also applies to: 1770-1785

---

2232-2242: Helper and CSV/NDJSON tests give solid coverage of metadata propagation

The expect_task_metadata helper centralizes the assertion on Task::Succeeded { content }.custom_metadata, making the new tests concise and less error-prone.

The test_add_documents_ndjson, test_update_documents_ndjson, test_add_documents_csv, and test_update_documents_csv tests validate that:

• TaskInfo.custom_metadata reflects the provided metadata, and
• The final Task retrieved via wait_for_completion preserves the same metadata.

This is exactly what we need to guard the new behavior on the streaming code paths.

Also applies to: 2413-2514

---

2579-2692: test_document_tasks_custom_metadata thoroughly exercises all main document task variants

This test is a nice end-to-end check that custom_metadata flows correctly through:

• add_documents
• delete_document
• add_or_update
• delete_documents
• delete_documents_with (via DocumentDeletionQuery)
• delete_all_documents

Asserting both TaskInfo.custom_metadata and the Task’s content.custom_metadata via expect_task_metadata gives good confidence that the SDK is correctly wiring the metadata end-to-end for the primary document operations.