Skip to content

Commit ab0cbf6

Browse files
authored
Merge pull request #53389 from MicrosoftDocs/NEW-optimize-query-performance-azure-cosmos-db
New module optimize query performance azure cosmos db from release branch
2 parents a3c128a + c99068a commit ab0cbf6

19 files changed

Lines changed: 1229 additions & 0 deletions
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.introduction
3+
title: Introduction
4+
metadata:
5+
title: Introduction
6+
description: Introduction
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 3
12+
content: |
13+
[!include[](includes/1-introduction.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.understand-indexes-cosmos-db
3+
title: Understand indexes in Azure Cosmos DB
4+
metadata:
5+
title: Understand Indexes in Azure Cosmos DB
6+
description: Understand indexes in Azure Cosmos DB
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 10
12+
content: |
13+
[!include[](includes/2-understand-indexes-cosmos-db.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.configure-range-composite-indexes
3+
title: Configure range and composite indexes
4+
metadata:
5+
title: Configure Range and Composite Indexes
6+
description: Configure range and composite indexes
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 12
12+
content: |
13+
[!include[](includes/3-configure-range-composite-indexes.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.tune-vector-indexes-embeddings
3+
title: Tune vector indexes for embedding workloads
4+
metadata:
5+
title: Tune Vector Indexes for Embedding Workloads
6+
description: Tune vector indexes for embedding workloads
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 11
12+
content: |
13+
[!include[](includes/4-tune-vector-indexes-embeddings.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.reduce-ru-costs-strategic-indexing
3+
title: Reduce RU costs with strategic indexing
4+
metadata:
5+
title: Reduce RU Costs with Strategic Indexing
6+
description: Reduce RU costs with strategic indexing
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 12
12+
content: |
13+
[!include[](includes/5-reduce-ru-costs-strategic-indexing.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.choose-consistency-levels-performance
3+
title: Choose consistency levels for optimal performance
4+
metadata:
5+
title: Choose Consistency Levels for Optimal Performance
6+
description: Choose consistency levels for optimal performance
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 11
12+
content: |
13+
[!include[](includes/6-choose-consistency-levels-performance.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.exercise-optimize-query-performance
3+
title: Exercise - Optimize query performance with vector indexes on Azure Cosmos DB for NoSQL
4+
metadata:
5+
title: Exercise - Optimize Query Performance with Vector Indexes on Azure Cosmos DB for NoSQL
6+
description: Exercise - Optimize query performance with vector indexes on Azure Cosmos DB for NoSQL
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 30
12+
content: |
13+
[!include[](includes/7-exercise-optimize-query-performance.md)]
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.knowledge-check
3+
title: Module assessment
4+
metadata:
5+
title: Module Assessment
6+
description: Module assessment
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 5
12+
content: "Choose the best response for each of the following questions."
13+
quiz:
14+
questions:
15+
- content: "A developer needs to optimize a query that filters documents by documentType and sorts results by uploadDate in descending order. Which index configuration best supports this query pattern?"
16+
choices:
17+
- content: "Create a composite index with documentType (ascending) followed by uploadDate (descending)"
18+
isCorrect: true
19+
explanation: "A composite index with the filter property first and the sort property second supports queries that filter on one property and sort by another. Including documentType in the ORDER BY clause allows the query to use this single composite index efficiently."
20+
- content: "Create separate range indexes on documentType and uploadDate"
21+
isCorrect: false
22+
explanation: "Separate range indexes support filtering on each property individually, but queries that combine filtering with multi-property sorting require composite indexes. Range indexes alone can't optimize the combined filter and sort pattern."
23+
- content: "Create a composite index with uploadDate (descending) followed by documentType (ascending)"
24+
isCorrect: false
25+
explanation: "The order of properties in a composite index matters. For filter-then-sort queries, the filter property should appear first in the composite index definition. Reversing the order doesn't optimize this query pattern."
26+
- content: "An AI application stores 500,000 embeddings per partition and needs to perform fast similarity searches with acceptable accuracy trade-offs. Which vector index type is most appropriate?"
27+
choices:
28+
- content: "flat"
29+
isCorrect: false
30+
explanation: "The flat index performs brute-force search with 100 percent accuracy but is limited to 505 dimensions and becomes slow and expensive for large datasets. It's best suited for small datasets under 1,000 vectors or scenarios where filters significantly reduce the search space."
31+
- content: "diskANN"
32+
isCorrect: true
33+
explanation: "DiskANN is recommended for large datasets with more than 50,000 vectors per partition. It provides the lowest latency and RU cost while maintaining high accuracy. This index type is designed for production AI applications at scale."
34+
- content: "quantizedFlat"
35+
isCorrect: false
36+
explanation: "The quantizedFlat index is designed for medium datasets of roughly 1,000 to 50,000 vectors per partition. While it balances performance and accuracy, diskANN provides better performance for datasets with 500,000 vectors."
37+
- content: "A team discovers that embedding arrays are consuming significant storage space. The embeddings are used only for vector similarity searches. How should they modify the indexing policy to reduce storage costs?"
38+
choices:
39+
- content: "Set indexingMode to none to disable all indexing on the container"
40+
isCorrect: false
41+
explanation: "Disabling indexing entirely prevents any query from using indexes, including metadata filters. This forces all queries to perform full scans and eliminates vector search capability. The goal is to exclude only the embedding arrays from range indexes."
42+
- content: "Change the embedding data type from float32 to float16 in the range index"
43+
isCorrect: false
44+
explanation: "Range indexes don't differentiate by data type in this way. The data type for vector storage is specified in the vector policy, not the range index. To reduce storage, exclude embeddings from range indexes entirely while keeping the vector index."
45+
- content: "Exclude the embedding path from includedPaths and add a vector index for the embedding property"
46+
isCorrect: true
47+
explanation: "Embedding arrays don't benefit from range indexes. They're used only with vector indexes for similarity searches. Excluding the embedding path from range indexing while maintaining a vector index reduces storage costs substantially without affecting vector search capability."
48+
- content: "A document search application queries by category and date range, but users report that recently uploaded documents don't appear in search results. The account uses eventual consistency by default. What change would ensure users see their own uploads immediately?"
49+
choices:
50+
- content: "Change the default consistency to strong consistency for all operations"
51+
isCorrect: false
52+
explanation: "While strong consistency ensures reads return the latest writes, it consumes twice the RUs of session consistency and adds latency. Session consistency provides the read-your-writes guarantee needed for this scenario at lower cost."
53+
- content: "Use session consistency and pass session tokens from write operations to subsequent reads"
54+
isCorrect: true
55+
explanation: "Session consistency provides a read-your-writes guarantee within a client session. When the application passes the session token from the upload operation to subsequent queries, users are guaranteed to see their uploaded documents in search results."
56+
- content: "Increase the container's provisioned throughput to speed up replication"
57+
isCorrect: false
58+
explanation: "Provisioned throughput affects operation capacity, not replication speed or consistency behavior. The issue is that eventual consistency doesn't guarantee users see their own writes. Changing the consistency level is the correct solution."
59+
- content: "Query metrics show that a frequently executed query has low index utilization and high retrieved-to-output document ratios. What does this indicate and how should the developer respond?"
60+
choices:
61+
- content: "The query is performing scans instead of using indexes efficiently. Analyze the query to identify which properties need indexes and add appropriate range or composite indexes."
62+
isCorrect: true
63+
explanation: "Low index utilization means the query isn't using available indexes effectively, causing it to scan and retrieve more documents than necessary. Analyzing the query's filter and sort properties reveals which indexes would improve performance."
64+
- content: "The container has too many indexes. Remove indexes to reduce query overhead and improve index utilization metrics."
65+
isCorrect: false
66+
explanation: "Low index utilization indicates missing indexes, not excess indexes. Removing indexes would worsen query performance. The solution is to add indexes that match the query's filter and sort patterns."
67+
- content: "The query is returning too many results. Add a TOP clause to limit results and improve the retrieved-to-output ratio."
68+
isCorrect: false
69+
explanation: "While limiting results is good practice, a high retrieved-to-output ratio indicates the database retrieves many documents that don't match query criteria. This happens when queries can't use indexes for filtering effectively. Adding appropriate indexes is the correct solution."
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.optimize-query-performance-azure-cosmos-db.summary
3+
title: Summary
4+
metadata:
5+
title: Summary
6+
description: Summary
7+
ms.date: 02/05/2026
8+
author: jeffkoms
9+
ms.author: jeffko
10+
ms.topic: unit
11+
durationInMinutes: 2
12+
content: |
13+
[!include[](includes/9-summary.md)]
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
AI applications demand fast, cost-effective data retrieval that scales with growing datasets and increasing query complexity. This module guides you through optimizing query performance for Azure Cosmos DB for NoSQL, helping you reduce latency, lower costs, and handle production workloads efficiently.
2+
3+
Imagine you're a developer who has built a semantic search platform that helps enterprise users find relevant documents across millions of stored files. Your application stores document metadata, extracted text, and vector embeddings generated by Azure OpenAI. Users search by keywords, filter by date ranges and document types, and expect semantically similar results ranked by relevance. Users expect response times under 100 milliseconds.
4+
5+
The application works well in development, but production testing reveals serious performance issues. Queries consume far more request units than budgeted, and latency spikes during peak usage. Investigation shows that the default indexing policy indexes every property, including large embedding arrays that inflate storage costs. Some queries perform full container scans because the required composite indexes don't exist. Users complain that recently uploaded documents don't appear in search results immediately. Your team needs to optimize the database configuration to support the application's diverse query patterns while staying within cost targets. You need to analyze which queries perform poorly, understand which index types support which query patterns, configure the right indexes for your access patterns, and select consistency levels that ensure users see their uploaded content. This module provides the techniques to transform your slow, expensive queries into efficient operations.
6+
7+
After completing this module, you'll be able to:
8+
9+
- Analyze query patterns and use metrics to identify performance bottlenecks and missing indexes
10+
- Configure range and composite indexes to optimize filter and sort operations for AI retrieval patterns
11+
- Select the appropriate vector index type based on dataset size, accuracy requirements, and performance goals
12+
- Design indexing policies that balance read performance against write costs for your workload profile
13+
- Choose consistency levels that meet application requirements while minimizing RU consumption

0 commit comments

Comments
 (0)