{"id":10247,"date":"2025-05-19T09:00:22","date_gmt":"2025-05-19T16:00:22","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=10247"},"modified":"2025-05-17T15:17:33","modified_gmt":"2025-05-17T22:17:33","slug":"boost-query-performance-with-global-secondary-indexes-in-azure-cosmos-db","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/boost-query-performance-with-global-secondary-indexes-in-azure-cosmos-db\/","title":{"rendered":"Boost Query Performance with Global Secondary Indexes in Azure Cosmos DB"},"content":{"rendered":"

Global secondary indexes for Azure Cosmos DB\u2014now in Public Preview\u2014make it easier to query data efficiently, especially as your datasets grow.<\/span>\u00a0<\/span><\/p>\n

Distributed databases like\u202fAzure Cosmos DB scale with dataset growth by partitioning data across multiple physical machines. When your queries include the\u202fpartition key, the client routes them directly to the appropriate partition. Queries that include the partition key remain low-latency regardless of how many partitions exist.<\/span><\/p>\n

But in real-world applications, or in the case of AI apps and agents, you often need to query data without including the partition key. That\u2019s where global secondary indexes (GSIs) help. GSIs let you define an alternate partition key and data model, allowing for fast, efficient lookups across a wider range of query patterns.<\/span>\u00a0<\/span><\/p>\n

 <\/p>\n

When to use GSI<\/span><\/span><\/h3>\n

Adding global secondary indexes (GSIs) can lower costs and boost performance for many workloads. Azure Cosmos DB automatically syncs changes to data from the source container to the GSI container. Data is kept up to date with no extra work on your part. Because GSIs have their own container properties\u2014such as partition key, data model, and indexing policy\u2014you can optimize for diverse query patterns while avoiding cross-partition queries on the source container.<\/span>\u00a0<\/span><\/p>\n

You can also add GSIs to containers as your application evolves, keeping queries efficient over time. Since GSIs exist as separate containers, they let you isolate specific parts of your workload. For example, you can create vector or full-text search indexes in the GSI to support vector and hybrid search, all without affecting transactional operations on the source container.<\/span>\u00a0<\/span><\/p>\n

 <\/p>\n

Let\u2019s<\/span> see a real<\/span>–<\/span>world example<\/span><\/span>\u00a0<\/span><\/h3>\n

Contoso, a fictitious company, stores user information in an Azure Cosmos DB container. Because their verification process often involves looking up users by email, they chose to partition the container using the email address. However, some users prefer verification by phone number, so Contoso also needs to support lookups by that field.<\/span>\u00a0<\/span><\/p>\n

The users<\/strong> container spans 10 physical partitions and currently holds 200,000 user records. Queries by email perform efficiently thanks to the partitioning strategy, but queries by phone number are less optimized and need to search across all 10 partitions. To improve performance and reduce query cost, Contoso added a global secondary index (GSI) called <\/span>usersByPhone<\/span><\/b>. They partitioned the GSI by phone number and used it to compare performance.<\/span><\/p>\n

 <\/p>\n

SELECT *  \r\nFROM c  \r\nWHERE c.phoneNumber = \"555-123-4567\" <\/code><\/pre>\n
RU charge on users container<\/em>: 27.93\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Execution time<\/em>: 6.90 seconds<\/p>\n
RU charge on GSI container<\/em>: 2.82\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Execution time<\/em>: 0.49 seconds<\/p>\n
 <\/p>\n
In this scenario, executing the same query on the GSI container reduces both RU charges and execution time by <\/span><\/span>90%<\/span><\/span><\/strong>.<\/span> Since Contoso performs thousands of phone number lookups per second during peak load, the GSI delivers significant cost savings and improved performance.<\/span> This improvement is driven by the client routing the query directly to the correct GSI partition, as shown below.<\/span><\/span>\u00a0<\/span><\/p>\n
\"GSI<\/a><\/p>\n
 <\/p>\n
Because GSIs are implemented as independent containers, you can define a custom indexing policy to further optimize queries. For example, Contoso runs targeted promotions for active users in specific area codes. To support this, they query their GSI and have added a composite index on isActive<\/strong> and phoneNumber<\/strong> to accelerate those lookups.<\/p>\n
 <\/p>\n
SELECT * \r\nFROM c \r\nWHERE STARTSWITH(c.phoneNumber, \"555\") AND c.isActive = true<\/code><\/pre>\n
RU charge on users container<\/em>: 33.32\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Execution time<\/em>: 1.82 seconds<\/p>\n
RU charge on GSI container<\/em>: 6.98\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Execution time<\/em>: 0.53 seconds<\/p>\n
 <\/p>\n
For this query, Contoso sees an 80% reduction in RU charges and a 70% improvement in execution time. The exact savings depend on the query\u2019s complexity and the container\u2019s configuration. By leveraging Azure Cosmos DB\u2019s rich query syntax and flexible indexing capabilities, GSIs offer a powerful way to optimize performance.<\/p>\n
If you\u2019d like to try this sample yourself, the code is available on GitHub<\/a>. The repository includes setup instructions, a data loader project, and a console app to run the queries and see the performance impact firsthand.<\/p>\n
 <\/p>\n
Getting started with global secondary indexes<\/h3>\n
You can enable global secondary indexes on your Azure Cosmos DB for NoSQL account directly from the Azure Portal. We\u2019ve also added support for accounts that use continuous backup\u2014this backup mode is now required before you can enable GSIs on your account.<\/p>\n
\"enable<\/a><\/p>\n
 <\/p>\n
Global secondary indexes (GSIs) are the evolution of the former materialized views feature. We\u2019ve made them easier and more cost-effective by removing the need to provision, manage, or pay for the builder component that handles data synchronization. Once you enable GSIs on your account, you can immediately start creating GSI containers\u2014either through the Azure Portal or using the Azure CLI. GSI containers should be created using autoscale throughput to account for spikes and dips in traffic without falling too far behind the source container. After creation, the GSI automatically begins syncing data from the source container.<\/p>\n
\"create<\/a><\/p>\n
 <\/p>\n
Global secondary indexes offer a powerful and flexible way to optimize query performance in Azure Cosmos DB for NoSQL. By supporting alternate partition keys and custom indexing policies, GSIs help you adapt to evolving application needs without compromising performance or scalability. Whether you’re improving lookup efficiency, isolating workloads, or enabling new query patterns, GSIs can help reduce cost and complexity.<\/p>\n
 <\/p>\n
Learn more<\/h3>\n
Explore the following resources to help you get started and make the most of GSIs in your applications:<\/p>\n