azure-documentdb-haystack 1.0.0__py3-none-any.whl

azure_documentdb_haystack-1.0.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: azure-documentdb-haystack
+Version: 1.0.0
+Summary: An integration of Azure DocumentDB with Haystack
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/azure_documentdb/README.md
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Author-email: deepset GmbH <info@deepset.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE.txt
+Keywords: azure,documentdb,haystack,rag,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: azure-identity>=1.15.0
+Requires-Dist: haystack-ai>=2.28.0
+Requires-Dist: pymongo[srv]>=4.13.0
+Description-Content-Type: text/markdown
+
+# azure-documentdb-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/azure-documentdb-haystack.svg)](https://pypi.org/project/azure-documentdb-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/azure-documentdb-haystack.svg)](https://pypi.org/project/azure-documentdb-haystack)
+
+Haystack document store and retrievers for [Azure DocumentDB](https://learn.microsoft.com/azure/documentdb/overview).
+
+## Installation
+
+```bash
+pip install azure-documentdb-haystack
+```
+
+## Authentication
+
+Microsoft Entra ID is the default and recommended authentication method. `DefaultAzureCredential` supports local Azure
+CLI credentials, workload identity, and managed identity without changing application code. Assign the identity an
+appropriate Azure DocumentDB data-plane role, then set the cluster name:
+
+```bash
+AZURE_DOCUMENTDB_CLUSTER_NAME=my-cluster
+```
+
+For local development and integration testing only, a connection string can be supplied through
+`AZURE_DOCUMENTDB_CONNECTION_STRING`. The integration emits a warning whenever this fallback is used.
+
+## Usage
+
+```python
+from haystack_integrations.document_stores.azure_documentdb import AzureDocumentDBDocumentStore
+
+store = AzureDocumentDBDocumentStore(
+    database_name="haystack",
+    collection_name="documents",
+)
+
+# Create once. The collection must exist before initializing the store.
+store.create_vector_index(dimensions=1536, kind="vector-hnsw", similarity="COS", m=16, efConstruction=64)
+```
+
+Use `AzureDocumentDBEmbeddingRetriever` for `cosmosSearch` vector queries. `AzureDocumentDBFullTextRetriever` supports
+Azure DocumentDB BM25 full-text search, which is currently a gated preview and must be enabled on the cluster.
+
+- [Azure DocumentDB vector search](https://learn.microsoft.com/azure/documentdb/vector-search)
+- [Azure DocumentDB full-text search](https://learn.microsoft.com/azure/documentdb/full-text-search-overview)
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/azure_documentdb/CHANGELOG.md)
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).

azure_documentdb_haystack-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+haystack_integrations/components/retrievers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/retrievers/azure_documentdb/__init__.py,sha256=B_XC2m3RSmH7v026Ue2YtjouucCjnxvXzoRbDRFm-7w,467
+haystack_integrations/components/retrievers/azure_documentdb/embedding_retriever.py,sha256=QlCOMAt1leEnSivdBy7TiZYIpmz_lt9P15UHC3h-OEU,4915
+haystack_integrations/components/retrievers/azure_documentdb/full_text_retriever.py,sha256=GmSZQ1rtQyUng4bL-AqneTueYq_T1P7h6OK3rirxRag,5178
+haystack_integrations/document_stores/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/document_stores/azure_documentdb/__init__.py,sha256=Vqe31JYuSn1RPf58VVB2PcGmRVDt6b5Xj9IaYJjMkus,266
+haystack_integrations/document_stores/azure_documentdb/document_store.py,sha256=UfOnxc6i8LvPN-soN6R1F5HhuNMqUlzmQlw82EKgLJ4,35492
+haystack_integrations/document_stores/azure_documentdb/filters.py,sha256=gzP49vIVhxZc72BMJR3q5JuvWzPv0JB1IhT_PYrkIAc,3713
+azure_documentdb_haystack-1.0.0.dist-info/METADATA,sha256=8XbKo8DPUJsUIZRaCpapFkdxh53awFjBpBNH21nKxgA,3494
+azure_documentdb_haystack-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+azure_documentdb_haystack-1.0.0.dist-info/licenses/LICENSE.txt,sha256=ntqrug2pqJYB34vlUCCLoaSaMp20iNtHW3kVivo_jlI,10249
+azure_documentdb_haystack-1.0.0.dist-info/RECORD,,

azure_documentdb_haystack-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

azure_documentdb_haystack-1.0.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this definition, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright 2026-present deepset GmbH
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

haystack_integrations/components/retrievers/azure_documentdb/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.components.retrievers.azure_documentdb.embedding_retriever import (
+    AzureDocumentDBEmbeddingRetriever,
+)
+from haystack_integrations.components.retrievers.azure_documentdb.full_text_retriever import (
+    AzureDocumentDBFullTextRetriever,
+)
+
+__all__ = ["AzureDocumentDBEmbeddingRetriever", "AzureDocumentDBFullTextRetriever"]

haystack_integrations/components/retrievers/azure_documentdb/embedding_retriever.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.types import FilterPolicy
+from haystack.document_stores.types.filter_policy import apply_filter_policy
+
+from haystack_integrations.document_stores.azure_documentdb import AzureDocumentDBDocumentStore
+
+
+@component
+class AzureDocumentDBEmbeddingRetriever:
+    """Retrieve documents from Azure DocumentDB using `cosmosSearch` vector similarity."""
+
+    def __init__(
+        self,
+        *,
+        document_store: AzureDocumentDBDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    ) -> None:
+        """
+        Create the embedding retriever.
+
+        :param document_store: Azure DocumentDB document store to query.
+        :param filters: Default Haystack metadata filters.
+        :param top_k: Maximum number of documents to return.
+        :param filter_policy: Policy for combining initialization and runtime filters.
+        """
+        if not isinstance(document_store, AzureDocumentDBDocumentStore):
+            msg = "document_store must be an instance of AzureDocumentDBDocumentStore"
+            raise ValueError(msg)
+        if top_k <= 0:
+            msg = "top_k must be greater than zero"
+            raise ValueError(msg)
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.filter_policy = (
+            filter_policy if isinstance(filter_policy, FilterPolicy) else FilterPolicy.from_str(filter_policy)
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize this component to a dictionary.
+
+        :returns: Serialized retriever configuration.
+        """
+        return default_to_dict(
+            self,
+            document_store=self.document_store.to_dict(),
+            filters=self.filters,
+            top_k=self.top_k,
+            filter_policy=self.filter_policy.value,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AzureDocumentDBEmbeddingRetriever":
+        """
+        Deserialize this component from a dictionary.
+
+        :param data: Serialized retriever configuration.
+        :returns: The deserialized retriever.
+        """
+        data["init_parameters"]["document_store"] = AzureDocumentDBDocumentStore.from_dict(
+            data["init_parameters"]["document_store"]
+        )
+        if policy := data["init_parameters"].get("filter_policy"):
+            data["init_parameters"]["filter_policy"] = FilterPolicy.from_str(policy)
+        return default_from_dict(cls, data)
+
+    def close(self) -> None:
+        """Release synchronous document-store resources."""
+        self.document_store.close()
+
+    async def close_async(self) -> None:
+        """Release asynchronous document-store resources."""
+        await self.document_store.close_async()
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents by vector similarity.
+
+        :param query_embedding: Query vector.
+        :param filters: Runtime Haystack metadata filters.
+        :param top_k: Runtime maximum number of documents.
+        :returns: A dictionary containing the retrieved `documents`.
+        """
+        effective_filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        documents = self.document_store._embedding_retrieval(
+            query_embedding=query_embedding,
+            filters=effective_filters,
+            top_k=self.top_k if top_k is None else top_k,
+        )
+        return {"documents": documents}
+
+    @component.output_types(documents=list[Document])
+    async def run_async(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Asynchronously retrieve documents by vector similarity.
+
+        :param query_embedding: Query vector.
+        :param filters: Runtime Haystack metadata filters.
+        :param top_k: Runtime maximum number of documents.
+        :returns: A dictionary containing the retrieved `documents`.
+        """
+        effective_filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        documents = await self.document_store._embedding_retrieval_async(
+            query_embedding=query_embedding,
+            filters=effective_filters,
+            top_k=self.top_k if top_k is None else top_k,
+        )
+        return {"documents": documents}

haystack_integrations/components/retrievers/azure_documentdb/full_text_retriever.py

@@ -0,0 +1,135 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.types import FilterPolicy
+from haystack.document_stores.types.filter_policy import apply_filter_policy
+
+from haystack_integrations.document_stores.azure_documentdb import AzureDocumentDBDocumentStore
+
+
+@component
+class AzureDocumentDBFullTextRetriever:
+    """Retrieve documents using Azure DocumentDB BM25 full-text search, currently a gated preview."""
+
+    def __init__(
+        self,
+        *,
+        document_store: AzureDocumentDBDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    ) -> None:
+        """
+        Create the full-text retriever.
+
+        :param document_store: Azure DocumentDB document store to query.
+        :param filters: Default Haystack metadata filters.
+        :param top_k: Maximum number of documents to return.
+        :param filter_policy: Policy for combining initialization and runtime filters.
+        """
+        if not isinstance(document_store, AzureDocumentDBDocumentStore):
+            msg = "document_store must be an instance of AzureDocumentDBDocumentStore"
+            raise ValueError(msg)
+        if top_k <= 0:
+            msg = "top_k must be greater than zero"
+            raise ValueError(msg)
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.filter_policy = (
+            filter_policy if isinstance(filter_policy, FilterPolicy) else FilterPolicy.from_str(filter_policy)
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize this component to a dictionary.
+
+        :returns: Serialized retriever configuration.
+        """
+        return default_to_dict(
+            self,
+            document_store=self.document_store.to_dict(),
+            filters=self.filters,
+            top_k=self.top_k,
+            filter_policy=self.filter_policy.value,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AzureDocumentDBFullTextRetriever":
+        """
+        Deserialize this component from a dictionary.
+
+        :param data: Serialized retriever configuration.
+        :returns: The deserialized retriever.
+        """
+        data["init_parameters"]["document_store"] = AzureDocumentDBDocumentStore.from_dict(
+            data["init_parameters"]["document_store"]
+        )
+        if policy := data["init_parameters"].get("filter_policy"):
+            data["init_parameters"]["filter_policy"] = FilterPolicy.from_str(policy)
+        return default_from_dict(cls, data)
+
+    def close(self) -> None:
+        """Release synchronous document-store resources."""
+        self.document_store.close()
+
+    async def close_async(self) -> None:
+        """Release asynchronous document-store resources."""
+        await self.document_store.close_async()
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query: str | list[str],
+        fuzzy: dict[str, int] | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents by BM25 keyword search.
+
+        :param query: Query string or strings.
+        :param fuzzy: Azure DocumentDB fuzzy-search options such as `maxEdits`.
+        :param filters: Runtime Haystack metadata filters.
+        :param top_k: Runtime maximum number of documents.
+        :returns: A dictionary containing the retrieved `documents`.
+        """
+        effective_filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        documents = self.document_store._full_text_retrieval(
+            query=query,
+            fuzzy=fuzzy,
+            filters=effective_filters,
+            top_k=self.top_k if top_k is None else top_k,
+        )
+        return {"documents": documents}
+
+    @component.output_types(documents=list[Document])
+    async def run_async(
+        self,
+        query: str | list[str],
+        fuzzy: dict[str, int] | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Asynchronously retrieve documents by BM25 keyword search.
+
+        :param query: Query string or strings.
+        :param fuzzy: Azure DocumentDB fuzzy-search options such as `maxEdits`.
+        :param filters: Runtime Haystack metadata filters.
+        :param top_k: Runtime maximum number of documents.
+        :returns: A dictionary containing the retrieved `documents`.
+        """
+        effective_filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        documents = await self.document_store._full_text_retrieval_async(
+            query=query,
+            fuzzy=fuzzy,
+            filters=effective_filters,
+            top_k=self.top_k if top_k is None else top_k,
+        )
+        return {"documents": documents}

haystack_integrations/document_stores/azure_documentdb/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.document_stores.azure_documentdb.document_store import AzureDocumentDBDocumentStore
+
+__all__ = ["AzureDocumentDBDocumentStore"]

haystack_integrations/document_stores/azure_documentdb/document_store.py

@@ -0,0 +1,765 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import re
+from contextlib import suppress
+from typing import Any, Literal
+
+from azure.core.credentials import TokenCredential
+from azure.identity import DefaultAzureCredential
+from haystack import default_from_dict, default_to_dict, logging
+from haystack.dataclasses import Document
+from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.utils import Secret, deserialize_secrets_inplace
+from pymongo import AsyncMongoClient, InsertOne, MongoClient, ReplaceOne, UpdateOne
+from pymongo.asynchronous.collection import AsyncCollection
+from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult
+from pymongo.collection import Collection
+from pymongo.driver_info import DriverInfo
+from pymongo.errors import BulkWriteError
+
+from haystack_integrations.document_stores.azure_documentdb.filters import _normalize_filters
+
+logger = logging.getLogger(__name__)
+
+_DOCUMENTDB_TOKEN_SCOPE = "https://ossrdbms-aad.database.windows.net/.default"
+_DOCUMENTDB_HOST_SUFFIX = "global.mongocluster.cosmos.azure.com"
+_DRIVER_INFO = DriverInfo(name="AzureDocumentDBHaystackIntegration")
+
+
+class AzureIdentityTokenCallback(OIDCCallback):
+    """Fetch Microsoft Entra access tokens for PyMongo's OIDC authentication."""
+
+    def __init__(self, credential: TokenCredential) -> None:
+        self._credential = credential
+
+    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:  # noqa: ARG002
+        """
+        Fetch an access token for Azure DocumentDB.
+
+        :param context: PyMongo OIDC callback context.
+        :returns: The OIDC callback result containing a Microsoft Entra access token.
+        """
+        token = self._credential.get_token(_DOCUMENTDB_TOKEN_SCOPE)
+        return OIDCCallbackResult(access_token=token.token)
+
+
+class AzureDocumentDBDocumentStore:
+    """
+    A Haystack document store backed by Azure DocumentDB.
+
+    The default authentication mode uses Microsoft Entra ID through `DefaultAzureCredential`. Supply the Azure
+    DocumentDB cluster name with `cluster_name` or the `AZURE_DOCUMENTDB_CLUSTER_NAME` environment variable.
+
+    A connection string can be supplied through `mongo_connection_string` or
+    `AZURE_DOCUMENTDB_CONNECTION_STRING` for local development and integration tests. Connection strings can contain
+    credentials and aren't recommended for production workloads.
+
+    The collection must already exist. For embedding retrieval, create a `cosmosSearch` vector index by calling
+    `create_vector_index` or provisioning it separately. Filtered vector search also requires a regular index for
+    every filtered metadata field, such as `meta.category`. Values used with `>`, `>=`, `<`, or `<=` must be numbers
+    or ISO-formatted date strings.
+
+    Usage:
+
+    ```python
+    from haystack_integrations.document_stores.azure_documentdb import AzureDocumentDBDocumentStore
+
+    document_store = AzureDocumentDBDocumentStore(database_name="haystack", collection_name="documents")
+    document_store.create_vector_index(dimensions=1536, similarity="COS")
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        database_name: str,
+        collection_name: str,
+        vector_search_index: str = "haystack_vector_index",
+        full_text_search_index: str | None = None,
+        cluster_name: str | None = None,
+        mongo_connection_string: Secret | None = Secret.from_env_var(  # noqa: B008
+            "AZURE_DOCUMENTDB_CONNECTION_STRING", strict=False
+        ),
+        azure_token_credential: TokenCredential | None = None,
+        embedding_field: str = "embedding",
+        content_field: str = "content",
+    ) -> None:
+        """
+        Create an Azure DocumentDB document store.
+
+        :param database_name: Name of the existing database.
+        :param collection_name: Name of the existing collection.
+        :param vector_search_index: Name used when creating the vector index. Azure DocumentDB selects vector indexes
+            by path at query time, so this name is not included in vector search queries.
+        :param full_text_search_index: Name of an Azure DocumentDB full-text search index. Full-text search is currently
+            a gated preview and must be enabled on the cluster before using the full-text retriever.
+        :param cluster_name: Azure DocumentDB cluster name. If omitted, `AZURE_DOCUMENTDB_CLUSTER_NAME` is used.
+        :param mongo_connection_string: Optional MongoDB connection string intended only for local development and
+            integration tests. Microsoft Entra authentication is used when this value is absent.
+        :param azure_token_credential: Azure credential used for Microsoft Entra authentication. If omitted,
+            `DefaultAzureCredential` is used.
+        :param embedding_field: Field containing document embeddings.
+        :param content_field: Field containing document content.
+        :raises ValueError: If database, collection, or field names are invalid.
+        """
+        for name, value in (("database_name", database_name), ("collection_name", collection_name)):
+            if not value or not re.fullmatch(r"[A-Za-z0-9_-]+", value):
+                msg = f"Invalid {name}: {value!r}. It can only contain letters, numbers, hyphens, or underscores."
+                raise ValueError(msg)
+        if not embedding_field or embedding_field.startswith("$"):
+            msg = "embedding_field must be a non-empty MongoDB field path and cannot start with '$'."
+            raise ValueError(msg)
+        if not content_field or content_field.startswith("$"):
+            msg = "content_field must be a non-empty MongoDB field path and cannot start with '$'."
+            raise ValueError(msg)
+
+        self.database_name = database_name
+        self.collection_name = collection_name
+        self.vector_search_index = vector_search_index
+        self.full_text_search_index = full_text_search_index
+        self.cluster_name = cluster_name
+        self.mongo_connection_string = mongo_connection_string
+        self.azure_token_credential = azure_token_credential
+        self.embedding_field = embedding_field
+        self.content_field = content_field
+
+        self._connection: MongoClient | None = None
+        self._connection_async: AsyncMongoClient | None = None
+        self._collection: Collection | None = None
+        self._collection_async: AsyncCollection | None = None
+        self._credential: TokenCredential | None = None
+
+    def _client_kwargs(self) -> tuple[str, dict[str, Any]]:
+        connection_string = self.mongo_connection_string.resolve_value() if self.mongo_connection_string else None
+        if connection_string:
+            logger.warning(
+                "Azure DocumentDB is using connection-string authentication. This fallback is intended only for "
+                "local development and integration tests. Use Microsoft Entra managed identity in production."
+            )
+            return connection_string, {"retryWrites": False, "driver": _DRIVER_INFO}
+
+        cluster_name = self.cluster_name or os.getenv("AZURE_DOCUMENTDB_CLUSTER_NAME")
+        if not cluster_name:
+            msg = (
+                "Azure DocumentDB cluster name is required. Set `cluster_name` or the "
+                "AZURE_DOCUMENTDB_CLUSTER_NAME environment variable."
+            )
+            raise DocumentStoreError(msg)
+
+        if self._credential is None:
+            self._credential = self.azure_token_credential or DefaultAzureCredential()
+        callback = AzureIdentityTokenCallback(self._credential)
+        uri = f"mongodb+srv://{cluster_name}.{_DOCUMENTDB_HOST_SUFFIX}/"
+        return uri, {
+            "authMechanism": "MONGODB-OIDC",
+            "authMechanismProperties": {"OIDC_CALLBACK": callback},
+            "retryWrites": False,
+            "tls": True,
+            "driver": _DRIVER_INFO,
+        }
+
+    def _connection_is_valid(self, connection: MongoClient) -> bool:
+        try:
+            connection.admin.command("ping")
+            return True
+        except Exception as error:
+            logger.error("Connection to Azure DocumentDB failed: {error}", error=error)
+            return False
+
+    async def _connection_is_valid_async(self, connection: AsyncMongoClient) -> bool:
+        try:
+            await connection.admin.command("ping")
+            return True
+        except Exception as error:
+            logger.error("Connection to Azure DocumentDB failed: {error}", error=error)
+            return False
+
+    def _ensure_connection_setup(self) -> None:
+        if self._connection is None:
+            uri, kwargs = self._client_kwargs()
+            self._connection = MongoClient(uri, **kwargs)
+        if not self._connection_is_valid(self._connection):
+            msg = "Connection to Azure DocumentDB failed."
+            raise DocumentStoreError(msg)
+        database = self._connection[self.database_name]
+        if self.collection_name not in database.list_collection_names():
+            msg = f"Collection '{self.collection_name}' does not exist in database '{self.database_name}'."
+            raise DocumentStoreError(msg)
+        self._collection = database[self.collection_name]
+        self._collection.create_index("id", unique=True)
+
+    async def _ensure_connection_setup_async(self) -> None:
+        if self._connection_async is None:
+            uri, kwargs = self._client_kwargs()
+            self._connection_async = AsyncMongoClient(uri, **kwargs)
+        if not await self._connection_is_valid_async(self._connection_async):
+            msg = "Connection to Azure DocumentDB failed."
+            raise DocumentStoreError(msg)
+        database = self._connection_async[self.database_name]
+        if self.collection_name not in await database.list_collection_names():
+            msg = f"Collection '{self.collection_name}' does not exist in database '{self.database_name}'."
+            raise DocumentStoreError(msg)
+        self._collection_async = database[self.collection_name]
+        await self._collection_async.create_index("id", unique=True)
+
+    @property
+    def connection(self) -> MongoClient | AsyncMongoClient:
+        """
+        Return the active Azure DocumentDB client.
+
+        :returns: The synchronous or asynchronous PyMongo client.
+        :raises DocumentStoreError: If no connection has been established.
+        """
+        if self._connection is not None:
+            return self._connection
+        if self._connection_async is not None:
+            return self._connection_async
+        msg = "The connection is not established yet."
+        raise DocumentStoreError(msg)
+
+    @property
+    def collection(self) -> Collection | AsyncCollection:
+        """
+        Return the active Azure DocumentDB collection.
+
+        :returns: The synchronous or asynchronous PyMongo collection.
+        :raises DocumentStoreError: If no collection has been initialized.
+        """
+        if self._collection is not None:
+            return self._collection
+        if self._collection_async is not None:
+            return self._collection_async
+        msg = "The collection is not established yet."
+        raise DocumentStoreError(msg)
+
+    def close(self) -> None:
+        """Release synchronous client resources."""
+        if self._connection is not None:
+            with suppress(Exception):
+                self._connection.close()
+            self._connection = None
+            self._collection = None
+
+    async def close_async(self) -> None:
+        """Release asynchronous client resources."""
+        if self._connection_async is not None:
+            with suppress(Exception):
+                await self._connection_async.close()
+            self._connection_async = None
+            self._collection_async = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize this document store to a dictionary.
+
+        :returns: Serialized document-store configuration.
+        """
+        if self.azure_token_credential is not None:
+            logger.warning(
+                "AzureDocumentDBDocumentStore was initialized with `azure_token_credential`, which cannot be "
+                "serialized and must be provided again after deserialization."
+            )
+        return default_to_dict(
+            self,
+            database_name=self.database_name,
+            collection_name=self.collection_name,
+            vector_search_index=self.vector_search_index,
+            full_text_search_index=self.full_text_search_index,
+            cluster_name=self.cluster_name,
+            mongo_connection_string=self.mongo_connection_string.to_dict() if self.mongo_connection_string else None,
+            embedding_field=self.embedding_field,
+            content_field=self.content_field,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AzureDocumentDBDocumentStore":
+        """
+        Deserialize this document store from a dictionary.
+
+        :param data: Serialized document-store configuration.
+        :returns: The deserialized document store.
+        """
+        deserialize_secrets_inplace(data["init_parameters"], keys=["mongo_connection_string"])
+        return default_from_dict(cls, data)
+
+    def count_documents(self) -> int:
+        """
+        Return the number of documents in the store.
+
+        :returns: The number of documents.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        return self._collection.count_documents({})
+
+    async def count_documents_async(self) -> int:
+        """
+        Asynchronously return the number of documents in the store.
+
+        :returns: The number of documents.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        return await self._collection_async.count_documents({})
+
+    def filter_documents(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Return documents matching Haystack metadata filters.
+
+        :param filters: Haystack metadata filters. Strings in ordered comparisons must be ISO-formatted dates.
+        :returns: Documents matching the filters.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        query = _normalize_filters(filters) if filters else {}
+        return [self._mongo_doc_to_haystack_doc(doc) for doc in self._collection.find(query)]
+
+    async def filter_documents_async(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Asynchronously return documents matching Haystack metadata filters.
+
+        :param filters: Haystack metadata filters. Strings in ordered comparisons must be ISO-formatted dates.
+        :returns: Documents matching the filters.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        query = _normalize_filters(filters) if filters else {}
+        documents = await self._collection_async.find(query).to_list(length=None)
+        return [self._mongo_doc_to_haystack_doc(doc) for doc in documents]
+
+    def write_documents(self, documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int:
+        """
+        Write documents to Azure DocumentDB using the requested duplicate policy.
+
+        :param documents: Documents to write.
+        :param policy: How to handle documents whose IDs already exist.
+        :returns: The number of documents written.
+        :raises ValueError: If `documents` contains an object that is not a `Document`.
+        :raises DuplicateDocumentError: If a duplicate ID is written with `DuplicatePolicy.FAIL`.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        return self._write_documents(self._collection, documents, policy)
+
+    def _write_documents(self, collection: Collection, documents: list[Document], policy: DuplicatePolicy) -> int:
+        existing = 0
+        if policy == DuplicatePolicy.SKIP:
+            existing = collection.count_documents({"id": {"$in": [document.id for document in documents]}})
+        operations, written = self._prepare_write_operations(documents, policy, existing)
+        if not operations:
+            return 0
+        try:
+            collection.bulk_write(operations)
+        except BulkWriteError as error:
+            details = error.details.get("writeErrors", []) if error.details else []
+            msg = f"Duplicate documents found: {details}"
+            raise DuplicateDocumentError(msg) from error
+        return written
+
+    def _prepare_write_operations(
+        self, documents: list[Document], policy: DuplicatePolicy, existing: int = 0
+    ) -> tuple[list[InsertOne[dict[str, Any]] | ReplaceOne[dict[str, Any]] | UpdateOne], int]:
+        if any(not isinstance(document, Document) for document in documents):
+            msg = "param 'documents' must contain a list of objects of type Document"
+            raise ValueError(msg)
+        if not documents:
+            return [], 0
+        if policy == DuplicatePolicy.NONE:
+            policy = DuplicatePolicy.FAIL
+        mongo_documents = [self._haystack_doc_to_mongo_doc(document) for document in documents]
+        operations: list[InsertOne[dict[str, Any]] | ReplaceOne[dict[str, Any]] | UpdateOne]
+        if policy == DuplicatePolicy.SKIP:
+            operations = [UpdateOne({"id": doc["id"]}, {"$setOnInsert": doc}, upsert=True) for doc in mongo_documents]
+            written = len(documents) - existing
+        elif policy == DuplicatePolicy.FAIL:
+            operations = [InsertOne(doc) for doc in mongo_documents]
+            written = len(documents)
+        else:
+            operations = [ReplaceOne({"id": doc["id"]}, doc, upsert=True) for doc in mongo_documents]
+            written = len(documents)
+        return operations, written
+
+    async def write_documents_async(
+        self, documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
+    ) -> int:
+        """
+        Asynchronously write documents using the requested duplicate policy.
+
+        :param documents: Documents to write.
+        :param policy: How to handle documents whose IDs already exist.
+        :returns: The number of documents written.
+        :raises ValueError: If `documents` contains an object that is not a `Document`.
+        :raises DuplicateDocumentError: If a duplicate ID is written with `DuplicatePolicy.FAIL`.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        existing = 0
+        if policy == DuplicatePolicy.SKIP:
+            existing = await self._collection_async.count_documents(
+                {"id": {"$in": [document.id for document in documents]}}
+            )
+        operations, written = self._prepare_write_operations(documents, policy, existing)
+        if not operations:
+            return 0
+        try:
+            await self._collection_async.bulk_write(operations)
+        except BulkWriteError as error:
+            details = error.details.get("writeErrors", []) if error.details else []
+            msg = f"Duplicate documents found: {details}"
+            raise DuplicateDocumentError(msg) from error
+        return written
+
+    def delete_documents(self, document_ids: list[str]) -> None:
+        """
+        Delete documents with matching Haystack IDs.
+
+        :param document_ids: IDs of documents to delete.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        if document_ids:
+            self._collection.delete_many({"id": {"$in": document_ids}})
+
+    async def delete_documents_async(self, document_ids: list[str]) -> None:
+        """
+        Asynchronously delete documents with matching Haystack IDs.
+
+        :param document_ids: IDs of documents to delete.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        if document_ids:
+            await self._collection_async.delete_many({"id": {"$in": document_ids}})
+
+    def delete_by_filter(self, filters: dict[str, Any]) -> int:
+        """
+        Delete documents matching filters.
+
+        :param filters: Haystack metadata filters selecting documents to delete.
+        :returns: The number of documents deleted.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        result = self._collection.delete_many(_normalize_filters(filters))
+        return result.deleted_count
+
+    async def delete_by_filter_async(self, filters: dict[str, Any]) -> int:
+        """
+        Asynchronously delete documents matching filters.
+
+        :param filters: Haystack metadata filters selecting documents to delete.
+        :returns: The number of documents deleted.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        result = await self._collection_async.delete_many(_normalize_filters(filters))
+        return result.deleted_count
+
+    def update_by_filter(self, filters: dict[str, Any], meta: dict[str, Any]) -> int:
+        """
+        Update metadata on documents matching filters.
+
+        :param filters: Haystack metadata filters selecting documents to update.
+        :param meta: Metadata fields and values to set.
+        :returns: The number of documents updated.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        update = {"$set": {f"meta.{key}": value for key, value in meta.items()}}
+        result = self._collection.update_many(_normalize_filters(filters), update)
+        return result.modified_count
+
+    async def update_by_filter_async(self, filters: dict[str, Any], meta: dict[str, Any]) -> int:
+        """
+        Asynchronously update metadata on documents matching filters.
+
+        :param filters: Haystack metadata filters selecting documents to update.
+        :param meta: Metadata fields and values to set.
+        :returns: The number of documents updated.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        update = {"$set": {f"meta.{key}": value for key, value in meta.items()}}
+        result = await self._collection_async.update_many(_normalize_filters(filters), update)
+        return result.modified_count
+
+    def delete_all_documents(self, *, recreate_collection: bool = False) -> None:
+        """
+        Delete all documents, optionally recreating the collection.
+
+        :param recreate_collection: Drop and recreate the collection instead of deleting documents individually.
+        """
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        assert self._connection is not None
+        if recreate_collection:
+            database = self._connection[self.database_name]
+            collection_info = database.list_collections(filter={"name": self.collection_name})
+            options = next(collection_info, {}).get("options", {})
+            indexes = [index for index in self._collection.list_indexes() if index["name"] != "_id_"]
+            self._collection.drop()
+            database.create_collection(self.collection_name, **options)
+            self._collection = database[self.collection_name]
+            for index in indexes:
+                keys = list(index["key"].items())
+                index_options = {key: value for key, value in index.items() if key not in {"key", "v", "ns"}}
+                self._collection.create_index(keys, **index_options)
+        else:
+            self._collection.delete_many({})
+
+    async def delete_all_documents_async(self, *, recreate_collection: bool = False) -> None:
+        """
+        Asynchronously delete all documents, optionally recreating the collection.
+
+        :param recreate_collection: Drop and recreate the collection instead of deleting documents individually.
+        """
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        assert self._connection_async is not None
+        if recreate_collection:
+            database = self._connection_async[self.database_name]
+            collection_info = await database.list_collections(filter={"name": self.collection_name})
+            collection_info_list = await collection_info.to_list(length=1)
+            options = collection_info_list[0].get("options", {}) if collection_info_list else {}
+            indexes_cursor = await self._collection_async.list_indexes()
+            indexes = [index for index in await indexes_cursor.to_list(length=None) if index["name"] != "_id_"]
+            await self._collection_async.drop()
+            await database.create_collection(self.collection_name, **options)
+            self._collection_async = database[self.collection_name]
+            for index in indexes:
+                keys = list(index["key"].items())
+                index_options = {key: value for key, value in index.items() if key not in {"key", "v", "ns"}}
+                await self._collection_async.create_index(keys, **index_options)
+        else:
+            await self._collection_async.delete_many({})
+
+    def create_vector_index(
+        self,
+        *,
+        dimensions: int,
+        similarity: Literal["COS", "L2", "IP"] = "COS",
+        kind: Literal["vector-ivf", "vector-hnsw", "vector-diskann"] = "vector-hnsw",
+        **index_options: Any,
+    ) -> None:
+        """
+        Create the configured Azure DocumentDB `cosmosSearch` vector index.
+
+        :param dimensions: Number of dimensions in each embedding.
+        :param similarity: Similarity metric: cosine (`COS`), Euclidean (`L2`), or inner product (`IP`).
+        :param kind: Vector index algorithm.
+        :param index_options: Algorithm-specific Azure DocumentDB index options.
+        :raises ValueError: If `dimensions` is not positive.
+        :raises DocumentStoreError: If index creation fails.
+        """
+        if dimensions <= 0:
+            msg = "dimensions must be greater than zero"
+            raise ValueError(msg)
+        self._ensure_connection_setup()
+        assert self._connection is not None
+        options = {"kind": kind, "dimensions": dimensions, "similarity": similarity, **index_options}
+        command = {
+            "createIndexes": self.collection_name,
+            "indexes": [
+                {
+                    "name": self.vector_search_index,
+                    "key": {self.embedding_field: "cosmosSearch"},
+                    "cosmosSearchOptions": options,
+                }
+            ],
+        }
+        try:
+            self._connection[self.database_name].command(command)
+        except Exception as error:
+            msg = f"Failed to create Azure DocumentDB vector index: {error}"
+            raise DocumentStoreError(msg) from error
+
+    async def create_vector_index_async(
+        self,
+        *,
+        dimensions: int,
+        similarity: Literal["COS", "L2", "IP"] = "COS",
+        kind: Literal["vector-ivf", "vector-hnsw", "vector-diskann"] = "vector-hnsw",
+        **index_options: Any,
+    ) -> None:
+        """
+        Asynchronously create the configured `cosmosSearch` vector index.
+
+        :param dimensions: Number of dimensions in each embedding.
+        :param similarity: Similarity metric: cosine (`COS`), Euclidean (`L2`), or inner product (`IP`).
+        :param kind: Vector index algorithm.
+        :param index_options: Algorithm-specific Azure DocumentDB index options.
+        :raises ValueError: If `dimensions` is not positive.
+        :raises DocumentStoreError: If index creation fails.
+        """
+        if dimensions <= 0:
+            msg = "dimensions must be greater than zero"
+            raise ValueError(msg)
+        await self._ensure_connection_setup_async()
+        assert self._connection_async is not None
+        options = {"kind": kind, "dimensions": dimensions, "similarity": similarity, **index_options}
+        command = {
+            "createIndexes": self.collection_name,
+            "indexes": [
+                {
+                    "name": self.vector_search_index,
+                    "key": {self.embedding_field: "cosmosSearch"},
+                    "cosmosSearchOptions": options,
+                }
+            ],
+        }
+        try:
+            await self._connection_async[self.database_name].command(command)
+        except Exception as error:
+            msg = f"Failed to create Azure DocumentDB vector index: {error}"
+            raise DocumentStoreError(msg) from error
+
+    def _embedding_pipeline(
+        self, query_embedding: list[float], filters: dict[str, Any] | None, top_k: int
+    ) -> list[dict[str, Any]]:
+        if not query_embedding:
+            msg = "Query embedding must not be empty"
+            raise ValueError(msg)
+        if top_k <= 0:
+            msg = "top_k must be greater than zero"
+            raise ValueError(msg)
+        cosmos_search: dict[str, Any] = {
+            "vector": query_embedding,
+            "path": self.embedding_field,
+            "k": top_k,
+        }
+        if filters:
+            cosmos_search["filter"] = _normalize_filters(filters)
+        return [
+            {"$search": {"cosmosSearch": cosmos_search, "returnStoredSource": True}},
+            {"$project": {"document": "$$ROOT", "score": {"$meta": "searchScore"}}},
+        ]
+
+    def _embedding_retrieval(
+        self, query_embedding: list[float], filters: dict[str, Any] | None = None, top_k: int = 10
+    ) -> list[Document]:
+        """Retrieve documents by Azure DocumentDB vector similarity."""
+        pipeline = self._embedding_pipeline(query_embedding, filters, top_k)
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        try:
+            results = list(self._collection.aggregate(pipeline))
+        except Exception as error:
+            msg = f"Vector retrieval from Azure DocumentDB failed: {error}"
+            raise DocumentStoreError(msg) from error
+        return [self._search_result_to_haystack_doc(result) for result in results]
+
+    async def _embedding_retrieval_async(
+        self, query_embedding: list[float], filters: dict[str, Any] | None = None, top_k: int = 10
+    ) -> list[Document]:
+        """Asynchronously retrieve documents by Azure DocumentDB vector similarity."""
+        pipeline = self._embedding_pipeline(query_embedding, filters, top_k)
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        try:
+            cursor = await self._collection_async.aggregate(pipeline)
+            results = await cursor.to_list(length=None)
+        except Exception as error:
+            msg = f"Vector retrieval from Azure DocumentDB failed: {error}"
+            raise DocumentStoreError(msg) from error
+        return [self._search_result_to_haystack_doc(result) for result in results]
+
+    def _full_text_pipeline(
+        self, query: str | list[str], fuzzy: dict[str, int] | None, filters: dict[str, Any] | None, top_k: int
+    ) -> list[dict[str, Any]]:
+        if not query:
+            msg = "Argument query must not be empty."
+            raise ValueError(msg)
+        if not self.full_text_search_index:
+            msg = "full_text_search_index must be configured to use full-text retrieval."
+            raise ValueError(msg)
+        if top_k <= 0:
+            msg = "top_k must be greater than zero"
+            raise ValueError(msg)
+        text_search: dict[str, Any] = {"query": query, "path": self.content_field}
+        if fuzzy:
+            text_search["fuzzy"] = fuzzy
+        pipeline: list[dict[str, Any]] = [
+            {"$search": {"index": self.full_text_search_index, "text": text_search}},
+        ]
+        if filters:
+            pipeline.append({"$match": _normalize_filters(filters)})
+        pipeline.extend(
+            [
+                {"$limit": top_k},
+                {"$addFields": {"score": {"$meta": "searchScore"}}},
+                {"$project": {"_id": 0}},
+            ]
+        )
+        return pipeline
+
+    def _full_text_retrieval(
+        self,
+        query: str | list[str],
+        fuzzy: dict[str, int] | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+    ) -> list[Document]:
+        """Retrieve documents with Azure DocumentDB BM25 full-text search (gated preview)."""
+        pipeline = self._full_text_pipeline(query, fuzzy, filters, top_k)
+        self._ensure_connection_setup()
+        assert self._collection is not None
+        try:
+            results = list(self._collection.aggregate(pipeline))
+        except Exception as error:
+            msg = f"Full-text retrieval from Azure DocumentDB failed: {error}"
+            raise DocumentStoreError(msg) from error
+        return [self._mongo_doc_to_haystack_doc(result) for result in results]
+
+    async def _full_text_retrieval_async(
+        self,
+        query: str | list[str],
+        fuzzy: dict[str, int] | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+    ) -> list[Document]:
+        """Asynchronously retrieve documents with Azure DocumentDB BM25 search (gated preview)."""
+        pipeline = self._full_text_pipeline(query, fuzzy, filters, top_k)
+        await self._ensure_connection_setup_async()
+        assert self._collection_async is not None
+        try:
+            cursor = await self._collection_async.aggregate(pipeline)
+            results = await cursor.to_list(length=None)
+        except Exception as error:
+            msg = f"Full-text retrieval from Azure DocumentDB failed: {error}"
+            raise DocumentStoreError(msg) from error
+        return [self._mongo_doc_to_haystack_doc(result) for result in results]
+
+    def _search_result_to_haystack_doc(self, result: dict[str, Any]) -> Document:
+        document = dict(result.get("document", result))
+        if "score" in result:
+            document["score"] = result["score"]
+        return self._mongo_doc_to_haystack_doc(document)
+
+    def _mongo_doc_to_haystack_doc(self, mongo_doc: dict[str, Any]) -> Document:
+        document = dict(mongo_doc)
+        document.pop("_id", None)
+        if self.content_field != "content":
+            document["content"] = document.pop(self.content_field, None)
+        if self.embedding_field != "embedding":
+            document["embedding"] = document.pop(self.embedding_field, None)
+        return Document.from_dict(document)
+
+    def _haystack_doc_to_mongo_doc(self, haystack_doc: Document) -> dict[str, Any]:
+        document = haystack_doc.to_dict(flatten=False)
+        if self.content_field != "content":
+            document[self.content_field] = document.pop("content", None)
+        if self.embedding_field != "embedding":
+            document[self.embedding_field] = document.pop("embedding", None)
+        sparse_embedding = document.pop("sparse_embedding", None)
+        if sparse_embedding:
+            logger.warning(
+                "Document {id} has a sparse embedding, but Azure DocumentDB integration does not support sparse "
+                "embeddings. The field will be ignored.",
+                id=haystack_doc.id,
+            )
+        document.pop("_id", None)
+        return document

haystack_integrations/document_stores/azure_documentdb/filters.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+from haystack.errors import FilterError
+
+
+def _normalize_filters(filters: dict[str, Any]) -> dict[str, Any]:
+    """Convert Haystack filters to MongoDB-compatible Azure DocumentDB filters."""
+    if not isinstance(filters, dict):
+        msg = "Filters must be a dictionary"
+        raise FilterError(msg)
+    if "field" in filters:
+        return _parse_comparison_condition(filters)
+    return _parse_logical_condition(filters)
+
+
+def _parse_logical_condition(condition: dict[str, Any]) -> dict[str, Any]:
+    if "operator" not in condition:
+        msg = f"'operator' key missing in {condition}"
+        raise FilterError(msg)
+    if "conditions" not in condition:
+        msg = f"'conditions' key missing in {condition}"
+        raise FilterError(msg)
+    conditions = [
+        _parse_comparison_condition(item) if "field" in item else _parse_logical_condition(item)
+        for item in condition["conditions"]
+    ]
+    operator = condition["operator"]
+    if operator == "AND":
+        return {"$and": conditions}
+    if operator == "OR":
+        return {"$or": conditions}
+    if operator == "NOT":
+        return {"$nor": [{"$and": conditions}]}
+    msg = f"Unknown logical operator '{operator}'. Valid operators are: 'AND', 'OR', 'NOT'"
+    raise FilterError(msg)
+
+
+def _parse_comparison_condition(condition: dict[str, Any]) -> dict[str, Any]:
+    for key in ("field", "operator", "value"):
+        if key not in condition:
+            msg = f"'{key}' key missing in {condition}"
+            raise FilterError(msg)
+    operator = condition["operator"]
+    if operator not in COMPARISON_OPERATORS:
+        msg = f"Unknown comparison operator '{operator}'"
+        raise FilterError(msg)
+    return COMPARISON_OPERATORS[operator](condition["field"], condition["value"])
+
+
+def _comparison(mongo_operator: str) -> Callable[[str, Any], dict[str, Any]]:
+    def convert(field: str, value: Any) -> dict[str, Any]:
+        return {field: {mongo_operator: value}}
+
+    return convert
+
+
+def _ordered_comparison(mongo_operator: str) -> Callable[[str, Any], dict[str, Any]]:
+    def convert(field: str, value: Any) -> dict[str, Any]:
+        if isinstance(value, list):
+            msg = f"Can't compare {type(value)} using ordered comparison operators."
+            raise FilterError(msg)
+        if isinstance(value, str):
+            try:
+                datetime.fromisoformat(value)
+            except (TypeError, ValueError) as error:
+                msg = "Strings are only comparable if they are ISO formatted dates."
+                raise FilterError(msg) from error
+        if value is None and mongo_operator in {"$gte", "$lte"}:
+            return {field: {"$gt" if mongo_operator == "$gte" else "$lt": None}}
+        return {field: {mongo_operator: value}}
+
+    return convert
+
+
+def _membership(mongo_operator: str) -> Callable[[str, Any], dict[str, Any]]:
+    def convert(field: str, value: Any) -> dict[str, Any]:
+        if not isinstance(value, list):
+            msg = f"{field}'s value must be a list when using a membership comparator"
+            raise FilterError(msg)
+        return {field: {mongo_operator: value}}
+
+    return convert
+
+
+COMPARISON_OPERATORS: dict[str, Callable[[str, Any], dict[str, Any]]] = {
+    "==": _comparison("$eq"),
+    "!=": _comparison("$ne"),
+    ">": _ordered_comparison("$gt"),
+    ">=": _ordered_comparison("$gte"),
+    "<": _ordered_comparison("$lt"),
+    "<=": _ordered_comparison("$lte"),
+    "in": _membership("$in"),
+    "not in": _membership("$nin"),
+}