Best practices for AI, RAG, and search on Azure Cosmos DB: vector search, full-text search, LangChain/LangGraph integration, and AI-agent design patterns.
When to Apply
Reference these guidelines when building RAG or AI-agent applications on Azure Cosmos DB with vector search, full-text search, or LangChain/LangGraph.
Rules
Vector Search
- vector-distance-query - Use VectorDistance for Similarity Search
- vector-embedding-policy - Define Vector Embedding Policy
- vector-enable-feature - Enable Vector Search Feature on Account
- vector-index-type - Configure Vector Indexes in Indexing Policy
- vector-normalize-embeddings - Normalize Embeddings for Cosine Similarity
- vector-repository-pattern - Implement Repository Pattern for Vector Search
Full-Text Search
- fts-add-index - Add Full-Text Index in the Indexing Policy
- fts-define-policy - Define Full-Text Policy on the Container
- fts-enable-capability - Enable Full-Text Search Capability on Account
- fts-hybrid-queries - Combine FTS predicates with range or equality filters for hybrid queries
- fts-keyword-matching - Use FullTextContains for keyword matching on indexed text fields
- fts-relevance-ranking - Use FullTextScore with ORDER BY RANK for BM25 relevance ranking
SDK Best Practices
- sdk-langchain-async-checkpointer - Initialize Async Cosmos DB Container Before CosmosDBSaver
- sdk-langchain-cosmosdb-saver - Use CosmosDBSaver for LangGraph Checkpointing
- sdk-langchain-js-chat-history - Use AzureCosmosDBNoSQLChatMessageHistory for Persistent Conversations in JS/TS
- sdk-langchain-js-embedding-model - Configure Azure OpenAI Embedding Deployment Name for JS/TS LangChain
- sdk-langchain-js-filter-injection - Prevent Filter Injection in JS/TS LangChain Vector Store Queries
- sdk-langchain-js-fulltext-prerequisites - Configure Full-Text Prerequisites Before JS/TS LangChain Hybrid Search
- sdk-langchain-js-managed-identity - Use Managed Identity for JS/TS LangChain Cosmos DB Integration
- sdk-langchain-js-search-types - Choose the Correct Search Type for JS/TS LangChain Vector Store
- sdk-langchain-js-semantic-cache - Use AzureCosmosDBNoSQLSemanticCache for LLM Cost Reduction in JS/TS
- sdk-langchain-js-vectorstore-init - Correctly Initialize AzureCosmosDBNoSQLVectorStore in JavaScript/TypeScript
- sdk-langchain-mcp-persistent-session - Use Persistent MCP Client Sessions for Multi-Agent Applications
- sdk-langchain-mcp-tool-content-format - Handle MCP ToolMessage Content Format Variations
- sdk-langgraph-mcp-tool-filtering - Filter MCP Tools by Name Prefix for Agent Assignment
Design Patterns
- pattern-ai-grounding-access - Use Point Reads for AI-Grounding and RAG Retrieval When ID Is Known
- pattern-background-task-writes - Use Background Tasks for Non-Blocking Chat History Storage
- pattern-langgraph-agent-name-attribution - Tag AI Messages with Agent Name for API Response Attribution
- pattern-langgraph-agent-routing-cosmosdb - Persist Active Agent in Cosmos DB for Deterministic Routing
- pattern-langgraph-async-cosmos-routing - Wrap Cosmos DB Sync Calls in asyncio.to_thread for LangGraph Routing Functions
- pattern-langgraph-async-cosmos-writes - Use asyncio.to_thread for Active Agent Writes in LangGraph Node Functions
- pattern-langgraph-chat-history-separate - Store Chat History Separately from LangGraph Checkpoints
- pattern-langgraph-fastapi-startup - Initialize LangGraph Agents in FastAPI Startup with Retry
- pattern-langgraph-interrupt-human - Use LangGraph Interrupt for Human-in-the-Loop Confirmation
- pattern-langgraph-multi-agent - Use StateGraph with Conditional Edges for Multi-Agent Routing
- pattern-langgraph-resume-checkpoint - Resume LangGraph from Checkpoint After Interrupt