Add routing support for OpenSearchDocumentStore

[GauravBansal29]

Related Issues

• fixes Support opensearch routing #2560

Proposed Changes

This PR adds support for OpenSearch routing functionality to the OpenSearchDocumentStore. Routing allows documents to be distributed across specific shards, which improves query performance when searching for documents belonging to specific tenants or groups.

Changes implemented:

1. Write operations with routing:

• Documents can now include _routing in their metadata during write operations
• The _routing field is automatically extracted from document metadata and passed as a routing parameter to OpenSearch
• The _routing field is removed from the stored document metadata to comply with OpenSearch requirements (routing must be a request parameter, not a document field)

2. Delete operations with routing:

• Added optional routing parameter to delete_documents() and delete_documents_async() methods
• Accepts a dictionary mapping document IDs to their routing values: routing: Optional[dict[str, str]]
• Ensures documents are deleted from the correct shards when routing was used during indexing

3. Implementation details:

• Modified _prepare_bulk_write_request() to extract _routing from document metadata and add it to the bulk action
• Modified _prepare_bulk_delete_request() to accept and apply routing parameters
• Both sync and async methods are supported

How did you test it?

Unit tests (mocked):

• test_routing_extracted_from_metadata(): Verifies routing is correctly extracted from document metadata and added to bulk actions
• test_routing_in_delete(): Verifies routing parameters are correctly applied to delete operations

Integration tests:

• TestDocumentStore. test_write_with_routing(): Tests writing documents with routing metadata to a live OpenSearch instance
• TestDocumentStore.test_delete_with_routing(): Tests deleting documents with routing from a live OpenSearch instance

All tests verify that:

• _routing is removed from document metadata before storage
• _routing is correctly passed as an action-level parameter to OpenSearch
• Documents without routing continue to work as expected
• Other metadata fields are preserved correctly

Notes for the reviewer

• The key implementation is in _prepare_bulk_write_request() (lines 395-420) where _routing is extracted from doc_dict at the top level (Haystack's Document.to_dict() flattens metadata fields)
• The _prepare_bulk_delete_request() method now accepts an optional routing parameter with signature: routing: Optional[dict[str, str]] = None
• Both sync and async code paths have been updated:
  • write_documents() and write_documents_async()
  • delete_documents() and delete_documents_async()
• The mock tests use .get("meta", {}) to handle cases where the meta dict may not exist after routing extraction

Checklist

I have read the contributors guidelines and the code of conduct
I have updated the related issue with new insights and changes
I added unit tests and updated the docstrings
I've used one of the conventional commit types for my PR title: feat: Add routing support for OpenSearchDocumentStore

[CLAassistant]

All committers have signed the CLA.

[GauravBansal29]

Hi @mpangrazzi @anakin87 👋
This PR adds OpenSearch routing support to the OpenSearchDocumentStore.

Could you please take a look when you get a chance?
Happy to address any feedback or changes needed. Thanks!

[GunaPalanivel]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.You have signed the CLA already but the status is still pending? Let us recheck it.

Hi @GauravBansal29, thanks for the PR!

Just a quick note — the CLA check still seems to be pending. Maintainers usually can’t review until that’s completed.
Once the CLA is confirmed (or rechecked if already signed), the review should move forward smoothly.

[GauravBansal29]

Thanks for informing @GunaPalanivel ; have signed the CLA