Add Azure DocumentDB integration

Microsoft's current Haystack and Azure DocumentDB guide (https://learn.microsoft.com/en-us/azure/documentdb/build-rag-pipelines) explicitly states that there is no first-party Haystack document store and demonstrates a custom retriever as a workaround

Tasks

• The code is documented with docstrings and was merged in the main branch
• Docs are published at https://docs.haystack.deepset.ai/
• There is a Github workflow running the tests for the integration nightly and at every PR
• A new label named like integration:<your integration name> has been added to the list of labels for this repository
• The labeler.yml file has been updated
• The package has been released on PyPI
• An integration tile with a usage example has been added to https://github.com/deepset-ai/haystack-integrations
• The integration has been listed in the Inventory section of this repo README
• The feature was announced through social media

Summary and motivation

Add an official Haystack integration for Azure DocumentDB, the fully managed Azure service built on the open-source DocumentDB database.

Azure DocumentDB is a strong fit for Haystack because it combines a MongoDB-compatible document database with native vector search. A Haystack application can keep source documents, metadata, and embeddings in the same collection instead of operating a separate vector database. This reduces data duplication, synchronization work, infrastructure complexity, and retrieval latency.

The integration would support:

• Retrieval-augmented generation (RAG) pipelines
• Semantic search over documents and metadata
• Metadata-filtered vector retrieval
• BM25 full-text retrieval where the cluster feature is enabled
• Recommendation, similarity, anomaly-detection, and agent-memory workloads
• Existing Azure DocumentDB applications that want to add Haystack without moving data
• Hybrid and multicloud development through a common MongoDB-compatible interface

Azure DocumentDB supports the MongoDB wire protocol and BSON, so the integration can use the mature PyMongo client rather than requiring a proprietary SDK. Microsoft reports 99.03% MongoDB compatibility, allowing developers to reuse familiar tooling and operational knowledge.

The database provides an integrated vector store with DiskANN, HNSW, and IVF indexes. Documents, metadata, and embeddings remain colocated, while metadata filters can be evaluated inside the cosmosSearch operation before nearest-neighbor scoring. This is especially valuable for Haystack because prefiltering preserves meaningful top-$k$ results better than retrieving candidates first and filtering them afterward.

There is also a clear ecosystem gap. Microsoft's current Haystack and Azure DocumentDB guide explicitly states that there is no first-party Haystack document store and demonstrates a custom retriever as a workaround. An official integration would replace that application-specific code with maintained, tested Haystack components and provide a consistent experience alongside other Haystack document-store integrations.

Adoption signals

• GitHub stars of the main repository: The DocumentDB repository has approximately 3.4k stars, 254 forks, and 84 contributors as of September 2026. The project's website also reports more than 3.4k stars and 240 public forks.

• PyPI downloads in the last 30 days of the Python client/SDK: DocumentDB uses standard MongoDB-compatible drivers rather than a dedicated Python SDK. The relevant client for this integration is PyMongo, which recorded approximately 95.2 million downloads in the most recent 30-day period, including 14.3 million in the most recent week. This gives the integration a mature, extensively used client foundation.

• Release activity: The latest open-source release is v0.116-0, released August 20, 2026. Releases in 2026 were also published in March, April, May, June, and July, indicating a cadence of roughly one release every three to five weeks during active development.

• Maintenance: The project is actively maintained, with recent commits, regular releases, open pull requests, published governance, and more than 80 contributors. It is MIT licensed and governed under the Linux Foundation, rather than being controlled solely as a proprietary database project.

  The project reports a Technical Steering Committee with 11 members representing five organizations: Microsoft, Amazon, AB InBev, Rippling, and YugabyteDB. The involvement of multiple database vendors and enterprise users is a strong signal that the project is intended to become a durable, vendor-neutral part of the document-database ecosystem.

• Haystack community demand: Microsoft already publishes an official guide for building RAG pipelines with Haystack and Azure DocumentDB. That guide currently requires users to implement their own cosmosSearch retriever and explicitly identifies the absence of a first-party Haystack store. The guide demonstrates concrete user interest while also showing the maintenance and usability gap this integration would close.

• Anything else showing adoption:

  • Azure DocumentDB is a fully managed Azure service based on the open-source project, giving the integration both a managed-cloud audience and an open-source ecosystem.
  • The project moved to the Linux Foundation in August 2025 after reaching nearly 2,000 stars within its first several months. It has since grown to approximately 3.4k stars.
  • The project is built on PostgreSQL and pgvector, benefiting from established database and vector-search ecosystems.
  • The open-source edition is MIT licensed and can run locally with Docker, on Kubernetes, on-premises, or across clouds.
  • The DocumentDB Kubernetes operator documents AKS, EKS, GKE, local, and on-premises deployment paths.
  • Microsoft documents Azure DocumentDB integrations or patterns for LangChain, LlamaIndex, LangGraph, and Semantic Kernel. Haystack should have an equivalent supported integration rather than relying on custom application code.
  • Microsoft provides Azure DocumentDB RAG samples, AI-agent tutorials, Python vector-search quickstarts, and a Visual Studio Code extension.
  • The project has received public support or participation from Microsoft, Amazon, Google Cloud, YugabyteDB, and other organizations.

DocumentDB is still younger than established databases such as PostgreSQL, Elasticsearch, or MongoDB. Its adoption numbers should therefore be interpreted in that context. Its rapid GitHub growth, Linux Foundation governance, cross-vendor participation, frequent release cadence, managed Azure offering, and dedicated AI-framework documentation indicate that interest is likely to continue growing.

Detailed design

The integration should provide a standard Haystack document store and dedicated retrieval components while using PyMongo and the MongoDB-compatible Azure DocumentDB interface.

Components

AzureDocumentDBDocumentStore

The document store should:

• Connect to an Azure DocumentDB cluster through PyMongo.
• Use Microsoft Entra ID and DefaultAzureCredential by default.
• Support managed identity in production environments.
• Optionally accept a connection string for local development and end-to-end testing, with a clear warning that credential-based connections are a fallback.
• Reuse client instances and connection pools rather than opening a connection for every operation.
• Support synchronous and asynchronous APIs.
• Serialize non-secret configuration through Haystack's standard to_dict() and from_dict() mechanisms.
• Require nonserializable custom credentials to be supplied again after deserialization.

It should implement the normal Haystack document-store operations:

• count_documents()
• filter_documents()
• write_documents()
• delete_documents()

The asynchronous equivalents should also be available.

write_documents() should support Haystack's duplicate policies:

• FAIL
• SKIP
• OVERWRITE

Haystack documents should be mapped to BSON documents while preserving:

• The Haystack document ID as _id.
• Document content.
• Dense embeddings.
• Metadata, including nested metadata.
• Configurable content and embedding field names.

Sparse embeddings should either be rejected or ignored with an explicit warning because Azure DocumentDB's vector indexes expect dense numeric arrays.

Embedding retrieval

AzureDocumentDBEmbeddingRetriever should execute a $search aggregation using the cosmosSearch operator.

It should accept:

• A query embedding.
• top_k.
• Optional Haystack metadata filters.
• A configurable filter policy.
• Configurable content and embedding fields.

The returned values should be standard Haystack Document objects with similarity scores populated, allowing the retriever to connect directly to prompt builders, rankers, and other Haystack pipeline components.

Filters should be inserted into the cosmosSearch.filter clause rather than applied after retrieval. This reduces unnecessary candidate evaluation and preserves the requested top-$k$ behavior.

Supported vector-index families should include:

• DiskANN, recommended for large production datasets and high-throughput retrieval.
• HNSW, suitable when a strong speed-recall tradeoff is required and sufficient memory is available.
• IVF, suitable for smaller collections or workloads prioritizing faster index construction and lower memory use.

The document store should expose a helper for creating vector indexes with configurable:

• Embedding dimensions.
• Similarity metric.
• Index kind.
• Algorithm-specific options such as HNSW construction parameters, IVF list counts, or DiskANN graph parameters.

Index creation should be idempotent when an equivalent index already exists.

Full-text retrieval

AzureDocumentDBFullTextRetriever should provide BM25-style text retrieval through Azure DocumentDB's full-text search support.

It should accept:

• A query string.
• top_k.
• Optional metadata filters.
• Optional fuzzy matching.
• A configurable full-text index name.

Because this capability can require cluster-level enablement and might have different availability from vector search, initialization or execution should return a clear error when the required feature or index is unavailable. The integration should not silently substitute a different retrieval strategy.

Filter conversion

Haystack filters should be translated into MongoDB-compatible query expressions.

The initial implementation should support:

• Equality and inequality.
• Greater-than and less-than comparisons.
• Inclusive range comparisons.
• in and not in.
• Nested AND, OR, and NOT conditions.
• Nested metadata fields through dotted paths.

Validation should reject malformed or unsafe filters before sending them to the database. Examples include:

• An in operator whose value is not a list.
• Ordered comparisons against list values.
• Invalid date strings where date comparison is expected.
• Field paths beginning with $.
• Unsupported Haystack operators.

Filtering should work consistently across document filtering, vector retrieval, and full-text retrieval, subject to the operators supported by the corresponding Azure DocumentDB operation.

Example usage

A typical RAG pipeline would:

1. Initialize AzureDocumentDBDocumentStore using managed identity.
2. Create a vector index for the embedding model's dimensions.
3. Convert and split source files using standard Haystack components.
4. Generate dense embeddings using any compatible Haystack embedder.
5. Write the resulting documents to Azure DocumentDB.
6. Embed the user's query.
7. Retrieve matching documents through AzureDocumentDBEmbeddingRetriever.
8. Pass those documents to PromptBuilder and a generator.

The important architectural benefit is that only the embedder and generator depend on the selected model provider. The storage and retrieval components remain normal Haystack components, and the source content, metadata, and vectors remain in one database.

Corner cases and operational considerations

• The target collection should exist before the document store is initialized, or the integration should document clearly if and when automatic creation occurs.
• Vector dimensions must match the configured index.
• Only numeric arrays supported by Azure DocumentDB should be indexed.
• Documents without a valid embedding should remain available to ordinary document queries but will not appear in vector-search results.
• Index options differ between DiskANN, HNSW, and IVF and must be validated separately.
• Some index types require specific Azure DocumentDB cluster tiers.
• The integration should disable retryable writes if required by Azure DocumentDB.
• Sync and async clients should have independent, well-defined lifecycles.
• Empty document lists and empty ID lists should be handled without unnecessary database calls.
• Metadata filters should be validated before constructing aggregation pipelines.
• Full-text retrieval should clearly document its feature-enablement requirements.
• Secret-bearing connection strings must not appear in serialized component configuration or logs.
• Managed identity and other TokenCredential implementations should be the recommended production authentication mechanism.

Why this belongs in Haystack

Azure DocumentDB is not merely another MongoDB-compatible CRUD store. Its integrated vector indexing, metadata prefiltering, managed identity support, managed scaling, open-source foundation, and compatibility with established MongoDB tooling make it directly relevant to production Haystack workloads.

An official integration would:

• Remove custom retriever code currently required by Microsoft's own Haystack tutorial.
• Give users a supported path from ingestion through vector and full-text retrieval.
• Keep Haystack competitive with LangChain, LlamaIndex, LangGraph, and Semantic Kernel integrations already documented for Azure DocumentDB.
• Serve existing Azure customers who want passwordless, managed-identity-based RAG pipelines.
• Support users who value open-source portability and want an alternative to a dedicated proprietary vector database.
• Reduce operational complexity by keeping application documents, metadata, and embeddings in one scalable store.

The combination of direct technical fit, rapidly increasing adoption, Linux Foundation governance, strong client-library maturity, and an identifiable gap in Haystack's current integration catalog makes Azure DocumentDB a good candidate for an official integration.