Architecture best practices for Azure Cosmos DB for NoSQL

Choose a simple design and avoid unnecessary features. Don't adopt functionality that unnecessarily adds complexity to your workload, like multiple-primary writes and custom indexing. Azure Cosmos DB supports these features, but they can add significant complexity and operational burden. Carefully evaluate whether your workload requires any advanced features.

Offload workload responsibilities and cross-cutting concerns to other services, such as Microsoft Entra ID for authentication and authorization or Azure Monitor and Application Insights for monitoring.

Identify and prioritize workload flows. Not all flows in the application are equally important. Identify the critical paths and assign priorities to each flow to guide your design decisions. User flow design can influence your service tiers, features, and the capacity that you allocate to the Azure Cosmos DB database.

To help identify critical flows that might need special treatment, capture the processing requirements that set them apart in terms of data processing capabilities. For example, some flows might require higher throughput or be more sensitive to latency problems. And some solution flows might require different transaction consistency levels.

Use failure mode analysis to identify potential failures in your workload. Plan mitigation strategies for potential failures. The following table shows examples of failure mode analysis.

For more information, see Failure mode analysis for Azure applications.

Build redundancy to improve resiliency and help meet reliability targets. Design your database account deployment so it spans at least two regions in Azure. Distribute your account across multiple availability zones if your Azure region supports it.

Evaluate the multiple-region and single-region write strategies for your workload. For single-region write, design your workload to have at least a second read region for failover. Enable automatic failover for single-region write and multiple-region read scenarios. For multiple-region write, compare the tradeoffs in complexity and consistency against the advantages of writing to multiple regions. For more information, see Expectations during a regional outage for single-region and multiple-region write accounts.

Consider how your consistency level and replication mode affects the recovery point objective (RPO) in a region-wide outage.

Design an end-to-end test of high availability for your application that includes testing database failover and fail back.

Use native disaster recovery and backup features. Implement database and container backups and restores to meet your requirements. Restore scenarios include point-in-time restore, recovering from accidental destructive operations, restoring deleted resources, and restoring to another region at a point in time. Configure your account with continuous backup. Choose the appropriate retention period based on your business requirements.

Align your Azure Cosmos DB design with industry-standard application design guidance and patterns. Explore the guide to design resilient applications, review the default retry policy for the SDKs, and plan for custom handling for specific transient errors. These guides provide best practices to make application code resilient to transient errors.

Review security baselines. To enhance the security posture of your workload, review the security checklist for Azure databases and the security baseline for Azure Cosmos DB. At a minimum, implement the data protection and identity management security baselines to help secure your Azure Cosmos DB account.

Assess service-level compliance and certifications in the context of current global personal data requirements.

Implement strict, conditional, and auditable identity and access management. Use Microsoft Entra ID for your workload's authentication and authorization needs. Microsoft Entra ID provides centralized authorization and access management.

For control plane and data plane access to your account, create roles, groups, and assignments based on the principle of least-privilege access. Consider disabling key-based authentication.

Encrypt data. Encrypt data at rest or data in motion by using service-managed keys or customer-managed keys.

Apply network segmentation and security controls. Create intentional segmentation and perimeters in your network design and apply defense-in-depth principles by using localized network controls at all network boundaries.

Reduce the surface attack area by using private endpoints in accordance with the security baseline for Azure Cosmos DB.

Implement a holistic security monitoring strategy. Audit user access, security breaches, and resource operations by using control plane logs.

Monitor data egress, data changes, usage, and latency by using data plane metrics.

Use secure development and testing practices. Follow best software development practices for secure access to data. Follow secure coding practices and perform secure code reviews when you develop applications that interact with Azure Cosmos DB.

Optimize your Azure Cosmos DB scaling strategy. Understand how Azure Cosmos DB handles storage and throughput scaling. Determine the right balance of performance and cost to meet your requirements.

Select a throughput allocation schema that suits your workload. Review the benefits of standard and autoscale throughput distributed at the database or container level. Also, consider serverless options when appropriate. Analyze your workload's traffic patterns to select the most suitable throughput allocation scheme.

Determine a partition key or set of partition keys that have high cardinality and remain unchanged. Use existing guidance and best practices to help select an appropriate partition key. Also, consider your indexing policy when you determine a partition key.

Optimize your Azure Cosmos DB data costs. Take an inventory of data and calculate the expected overall data storage for your workload. The size of both items and indexes influence your data storage cost. Calculate the impact of replication and backup on storage costs.

Create a strategy to automatically remove older items that are no longer used or necessary. If required, export these items to a lower-cost storage solution before you remove them.

Optimize your queries for cost. Evaluate your most common queries that minimize cross-partition lookups. Use this information to inform the process of selecting a partition key or customizing an indexing policy.

Use projection to reduce throughput costs of large query result sets. Author queries to project only the minimal number of fields required from a result set. If calculations on fields are necessary, evaluate the throughput cost of performing those calculations server side versus client side.

Avoid using unbounded cross-partition queries. Evaluate and author queries to ensure that they search within a single logical partition whenever possible. Use query filters to control which logical partitions the query targets. If a query must search across logical partitions, bound the query to only search a subset of logical partitions instead of a full scan.

Design an indexing policy that considers the common operations and queries in your workload.

Monitor your Azure Cosmos DB instances. Include Azure Cosmos DB instances across regions in your workload monitoring solution.

Create identifiers in the client application to differentiate workloads. Consider flags, such as the user-agent suffix, to identify what workload each log entry or metric should be associated with.

Draft a log and metrics monitoring strategy to differentiate between different workloads, flag exceptional scenarios, track patterns in exceptions and errors, and track host machine performance.

Define multiple alerts to monitor throttling, analyze throughput allocation, and track the size of your data.

Plan expected metric thresholds based on partition and index design. Create a plan to monitor those metrics to determine how close they are to the planned thresholds.

Automate deployments through infrastructure as code (IaC). Incorporate all Azure Cosmos DB changes, including infrastructure deployments and configuration changes, in your code deployment practices.

Create and enforce best practices to automate the deployment of your Azure Cosmos DB for NoSQL account and resources.

Ensure that your team uses the same templates to deploy to other nonproduction environments.

Plan and proactively manage your Azure Cosmos DB capacity. Define a performance baseline for your application. Measure how many concurrent users and transactions you might need to handle. Consider workload characteristics such as your average user flow, common operations, and spikes in usage.

Research your target users. Determine which Azure regions are closest to them.

Optimize your data design. Design items so their corresponding JSON documents are as small as possible. Consider splitting data across multiple items if necessary.

Keep items less than 100 KB in size. Larger items consume more throughput for common read and write operations. Queries on larger items that project all fields can also add significant throughput cost.

Select the right tier, features, and billing model. Determine if your workload requires an analytical store. Consider analytical stores and services like Azure Synapse Link for complex queries.

Optimize the deployment model. Deploy Azure Cosmos DB for NoSQL to regions closest to your end users. | Reduce latency by deploying Azure Cosmos DB for NoSQL to the regions closest to your end users as much as possible.

Optimize queries for performance. Review the query performance tips and apply the strategies that apply to your use cases.

Identify queries that use one or more ordering fields. Also, identify operations that affect multiple fields. Include these fields explicitly in the indexing policy design.

Design large workloads to use bulk operations whenever possible.

Identify queries on child arrays and determine if they're candidates for more efficient subqueries.

Research your most common and complex queries. Identify queries that use multiple lookups, joins, or aggregates. Consider these queries in any design considerations for the partition key or indexing policy.

For the most common queries, determine the number of results that you expect for each page. This number helps you formalize a buffered item count for prefetched results.

Optimize code logic. Use the singleton pattern for the CosmosClient class in most SDKs. Use the client class in most SDKs as a singleton. The client class manages its own lifecycle and is designed to not be disposed. Constantly creating and disposing instances can result in reduced performance.