feat: support additional search_kwargs with OpenSearchEmbeddingRetriever

[tstadel]

Related Issues

• fixes #issue-number

Proposed Changes:

• support additional search kwargs with OpenSearchEmbeddingRetriever
• This is espicially useful for finetuning embedding search (e.g. with ef_search or k parameters), but also enables rescoring
• For a full list of supported search kwargs see https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#request-body-fields

How did you test it?

Notes for the reviewer

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: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.

[Copilot]

Pull request overview

Adds support for passing additional OpenSearch kNN request parameters (search_kwargs) through OpenSearchEmbeddingRetriever into the OpenSearch document store’s embedding search request, enabling further tuning of approximate kNN search behavior.

Changes:

• Extend OpenSearchEmbeddingRetriever to accept, serialize, and forward search_kwargs (sync + async).
• Extend OpenSearchDocumentStore embedding search request builder to merge search_kwargs into the knn query body.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
integrations/opensearch/src/haystack_integrations/document_stores/opensearch/document_store.py	Adds search_kwargs to the embedding-search request builder and merges into the knn.embedding clause.
integrations/opensearch/src/haystack_integrations/components/retrievers/opensearch/embedding_retriever.py	Adds search_kwargs to retriever init/run APIs, persists it on the component, and forwards it to the document store (sync + async).

Comments suppressed due to low confidence (1)

integrations/opensearch/src/haystack_integrations/document_stores/opensearch/document_store.py:1420

• search_kwargs is accepted by _prepare_embedding_search_request, but when custom_query is provided it is currently ignored entirely. This is surprising for callers (they can pass search_kwargs and see no effect). Consider either explicitly documenting that search_kwargs only applies to the default query path, or raising a ValueError when both custom_query and search_kwargs are provided to avoid silent no-ops.

        search_kwargs: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        if not query_embedding:
            msg = "query_embedding must be a non-empty list of floats"
            raise ValueError(msg)

        body: dict[str, Any]
        if isinstance(custom_query, dict):
            body = self._render_custom_query(

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.