Adding support to create GSI containers by mbhaskar · Pull Request #48480 · Azure/azure-sdk-for-java

mbhaskar · 2026-03-19T22:04:38Z

Description

GlobalSecondaryIndex View Support — Change Summary

Overview

This branch adds client-side support for GlobalSecondaryIndex Views/Global Secondary Index in the Azure Cosmos DB Java SDK.
GlobalSecondaryIndex views are derived containers built from a source container using a SQL-like projection
query. The changes expose two properties that the service already supports:

Property	Direction	Description
`GlobalSecondaryIndexDefinition`	Read / Write	Defines the source container and query for a GlobalSecondaryIndex view container
`GlobalSecondaryIndexViews`	Read-only	List of GlobalSecondaryIndex view containers derived from a source container, populated by the service in `container.read()` responses

Important Changes

`CosmosGlobalSecondaryIndexViewDefinition.java`

Package: com.azure.cosmos.models

Represents the write-side definition of a GlobalSecondaryIndex view container. The source
container Rid should be set when creating a GlobalSecondaryIndex view container.

Example usage:

CosmosGlobalSecondaryIndexViewDefinition mvDef = new CosmosGlobalSecondaryIndexViewDefinition()
    .setSourceContainerId("src-container")
    .setDefinition("SELECT c.customerId, c.emailAddress FROM c");

containerProperties.setGlobalSecondaryIndexViewDefinition(mvDef);

Method	Description
`getSourceContainerRid()`	Returns the `_rid` of the source container
`setSourceContainerRid(String)`	Sets the `_rid` of the source container. Fluent.
`getDefinition()`	Returns the SQL-like projection query
`setDefinition(String)`	Sets the SQL-like projection query. Fluent.

`CosmosGlobalSecondaryIndexView.java`

Package: com.azure.cosmos.models

A read-only model representing a single entry in the GlobalSecondaryIndexViews array returned by the
service when reading a source container. Each entry identifies one derived GlobalSecondaryIndex view
container.

Method	Description
`getId()`	The container id
`getResourceId()`	The container `_rid`

Example Usage:

CosmosContainerResponse response = container.read();
List<CosmosGlobalSecondaryIndexView> GlobalSecondaryIndexViews = response.getProperties().getGlobalSecondaryIndexViews();
for (CosmosGlobalSecondaryIndexView mv : GlobalSecondaryIndexViews) {
    System.out.println("GlobalSecondaryIndex view container id: " + mv.getId());
    System.out.println("GlobalSecondaryIndex view container _rid: " + mv.getResourceId());
}

`CosmosContainerProperties.java`

Two new public methods:

Method	Description
`setGlobalSecondaryIndexViewDefinition(CosmosGlobalSecondaryIndexViewDefinition)`	Sets the GlobalSecondaryIndex view definition. Used when creating a GlobalSecondaryIndex view container. Fluent, returns `this`. Throws `NullPointerException` if `null` is passed.
`getGlobalSecondaryIndexDefinition()`	Gets the GlobalSecondaryIndex view definition. Returns `null` if not set. Ex: {"definition":"SELECT c.email, c.name FROM c","sourceContainerId":"tc1","status":"Active","sourceContainerRid":"Z4oBANAPOuI="}
`getGlobalSecondaryIndexViews()`	Read-only. Returns the unmodifiable list of `CosmosGlobalSecondaryIndexView` entries populated by the service when reading a source container. Returns an empty list if not present. Ex: [{"id":"gsi1_tc1","_rid":"Z4oBAN4y8Mg="}, {"id":"gsi2_tc1","_rid":"Z4oBAOkB5m8="}]

Test Coverage (`GlobalSecondaryIndexViewTest.java`)

Unit tests added for the new GlobalSecondaryIndex view properties on CosmosContainerProperties:

Notes

As of now only five GlobalSecondaryIndex views are supported for a source container. Trying to create a 6th one throws the following error

Exception in thread "main" {"ClassName":"CosmosException","userAgent":"azsdk-java-cosmos/4.79.0-beta.1 Windows11/10.0 JRE/21.0.3",
"statusCode":403,"resourceAddress":"https://hamallap-test-westus2.documents.azure.com:443/dbs/testdb1/colls",
"error":"{\"code\":\"Forbidden\",\"message\":\"Message: {\\\"Errors\\\":[\\\"Limit of 5 GlobalSecondaryIndex views
 on Container 'testcontainer1' has been reached, cannot add more GlobalSecondaryIndex views\\\"]}

All the GlobalSecondaryIndexViews on that container have to be deleted before deleting a source container. You would see below error otherwise

Exception in thread "main" {"ClassName":"CosmosException","userAgent":"azsdk-java-cosmos/4.79.0-beta.1 Windows11/10.0 JRE/21.0.3",
"statusCode":400,"resourceAddress":"https://hamallap-test-westus2.documents.azure.com:443/dbs/testdb1/colls/testcontainer1",
"error":"{\"code\":\"BadRequest\",\"message\":\"Message: {\\\"Errors\\\":[\\\"Delete not allowed on Containers
 with GlobalSecondaryIndex views. Retry after deleting associated GlobalSecondaryIndex views\\\"]}

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

WIP : Added new pipline to run GSI tests on a fixed account with GSI enabled. Will push once credentials are set in the pipline

Copilot

Pull request overview

Adds Azure Cosmos DB Java SDK model + client support for creating and reading Global Secondary Index (GSI) / materialized view container metadata, including definition payload serialization and server-populated derived-view listings.

Changes:

Introduces new public models for GSI/materialized-view definition and derived-view entries.
Extends container properties + internal resource models to serialize/deserialize these new fields.
Updates async container creation flow to resolve the source container RID prior to create; adds unit tests for JSON round-tripping.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/ModelBridgeInternal.java	Adds internal helpers to serialize/deserialize the new definition model.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosGlobalSecondaryIndexView.java	New read-only model for derived view entries returned by the service.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosGlobalSecondaryIndexDefinition.java	New definition model backing the create-time payload and server-returned status fields.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosContainerProperties.java	Exposes new container properties accessors for definition and derived views.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/JsonSerializable.java	Registers the new definition type for internal (de)serialization pathways.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DocumentCollection.java	Stores/reads the new definition and derived views on the internal resource representation.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Constants.java	Adds wire-property constants for materialized view definition and view list fields.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncDatabase.java	Resolves source container RID during create when a source container id is provided.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/MaterializedViewTest.java	Adds unit tests validating serialization/deserialization behavior for the new fields.

xinlian12 · 2026-04-01T21:34:40Z

⏳ PR Review Agent — Starting review...

jcocchi

I left comments but might not have caught all places for naming updates. General guidance:

Remove all references to materialized views (except where needed due to the API response)
Global secondary index views --> global secondary indexes

chandugunturi

Rename all the MV / materialized view naming conventions with GSI/ GlobalSecondaryIndex. Also, once the query & sourceRid are set for the GSI, it is going to be constant througout the life time of GSI. Please make relevant changes in APIs.

…RID resolution options leak - Replace all 'materialized view' / 'view' terminology with 'global secondary index' / 'gsi' in Javadocs, variable names, comments, and test code - Rename DocumentCollection.getGlobalSecondaryIndexViews() to getGlobalSecondaryIndexes() - Rename ModelBridgeInternal.setMaterializedViewDefinitionSourceCollectionRid() to setGlobalSecondaryIndexDefinitionSourceCollectionRid() - Fix CosmosAsyncDatabase.createContainerInternal() to not leak caller's create-scoped request options to source container read (pass null instead) - Fix test JSON keys to use correct wire format (materializedViewDefinition, materializedViews) instead of incorrect keys - Update Constants.java comment from 'Materialized View' to 'Global Secondary Index' - Rename test variables from mv/view to gsi naming convention Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… support - Change GlobalSecondaryIndexContainerCrudTest groups from 'emulator' to 'gsi' - Add gsi-testng.xml TestNG suite for the gsi test group - Add -Pgsi Maven profile in azure-cosmos-tests pom.xml - Add live-gsi-platform-matrix.json for pipeline matrix config - Add Cosmos_Live_Test_GSI stage in tests.yml using pre-provisioned account variables (gsi-test-endpoint, gsi-test-key) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jcocchi

LGTM

FabianMeiswinkel

LGTM - except for the accidental public API surface change for ModelBridgexxx - please fix that either in this PR or IMMEDIATELY after to avoid releases getting stuck because that would be flagged in API review.

mbhaskar · 2026-04-13T21:46:36Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-13T21:47:04Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-15T19:10:20Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-15T19:10:47Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-15T22:32:52Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-15T22:33:17Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-16T17:46:35Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-16T17:47:04Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-16T19:01:27Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-16T19:01:53Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-17T19:56:02Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-17T19:56:31Z

Azure Pipelines successfully started running 1 pipeline(s).

mbhaskar · 2026-04-21T21:59:00Z

@copilot resolve the merge conflicts in this pull request

Keep both CosmosGlobalSecondaryIndexDefinitionHelper (from this branch) and SqlQuerySpecHelper/SqlParameterHelper (from upstream/main) in ImplementationBridgeHelpers.java. Keep all initialize() calls in ModelBridgeInternal.java. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mbhaskar · 2026-04-22T00:37:56Z

/azp run java - cosmos - tests

azure-pipelines · 2026-04-22T00:38:20Z

Azure Pipelines successfully started running 1 pipeline(s).

Replace the no-arg constructor and fluent setters on CosmosGlobalSecondaryIndexDefinition with a two-arg constructor that takes sourceContainerId and definition as required parameters. Once set, these values cannot be changed, reflecting the fact that they are constant for the lifetime of a global secondary index. - Remove setSourceContainerId() and setDefinition() public setters - Add constructor validation (null/empty throws IllegalArgumentException) - Add unit tests for constructor validation - Update all call sites in tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The service can return either materializedViewDefinition or globalSecondaryIndexDefinition, and either materializedViews or globalSecondaryIndexes. Update deserialization to accept both, with the new name taking precedence. Write both property names on serialization for backward compatibility. - DocumentCollection: read from globalSecondaryIndexDefinition first, fall back to materializedViewDefinition; same for indexes list - DocumentCollection: write both property names on set - CosmosGlobalSecondaryIndexDefinition: use GLOBAL_SECONDARY_INDEX_* constants (same underlying field names) - Constants: rename inner field constants, add new outer property names - Add unit tests for new wire format deserialization and precedence Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…the discussion

- Move GSI definition extraction inside Mono.defer in createContainerInternal to avoid a TOCTOU race between Mono construction and subscription. - Rename CosmosContainerProperties.get/setCosmosGlobalSecondaryIndexDefinition to get/setGlobalSecondaryIndexDefinition to match sibling policy accessors (getFullTextPolicy, getVectorEmbeddingPolicy, etc.). - Add explanatory comment on DocumentCollection.setGlobalSecondaryIndexDefinition documenting the transitional dual-write to both globalSecondaryIndexDefinition and materializedViewDefinition wire-format keys. - Tighten CosmosGlobalSecondaryIndexDefinition constructor validation to reject null/empty/blank sourceContainerId and definition arguments. - Introduce CosmosGlobalSecondaryIndexBuildStatus enum (ACTIVE, UNKNOWN) and return it from getStatus(); unknown/absent values map to UNKNOWN. - Add sourceContainerId assertions across GSI container CRUD tests; update status assertions to use the new enum. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

# Conflicts: # sdk/cosmos/azure-cosmos/CHANGELOG.md

Adding support to create GSI containers

7ba9119

github-actions Bot added the Cosmos label Mar 19, 2026

mbhaskar added 2 commits March 23, 2026 19:23

Refactoring to take ID instead of RID

8136ea2

Renaming fields and properties

08e1097

mbhaskar marked this pull request as ready for review March 30, 2026 18:51

mbhaskar requested review from a team and kirankumarkolli as code owners March 30, 2026 18:51

Copilot AI review requested due to automatic review settings March 30, 2026 18:51

Copilot started reviewing on behalf of mbhaskar March 30, 2026 18:53 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

updating javadoc and method names accordingly

f5b6348

xinlian12 reviewed Apr 1, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/MaterializedViewTest.java Outdated

xinlian12 reviewed Apr 1, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncDatabase.java Outdated

xinlian12 reviewed Apr 1, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncDatabase.java Outdated

xinlian12 reviewed Apr 1, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/MaterializedViewTest.java Outdated

jcocchi suggested changes Apr 2, 2026

View reviewed changes

chandugunturi reviewed Apr 2, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Constants.java

chandugunturi reviewed Apr 2, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosContainerProperties.java Outdated

chandugunturi suggested changes Apr 2, 2026

View reviewed changes

mbhaskar force-pushed the global-secondary-index branch from 22fe4ad to 1dca938 Compare April 6, 2026 23:26

mbhaskar and others added 2 commits April 8, 2026 15:27

updating correct parameters

395febf

jcocchi approved these changes Apr 8, 2026

View reviewed changes

Comment thread ...azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosGlobalSecondaryIndexDefinition.java

FabianMeiswinkel reviewed Apr 9, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/ModelBridgeInternal.java Outdated

FabianMeiswinkel approved these changes Apr 9, 2026

View reviewed changes

Retriggering tests to clear stuck pipeline

e0f5a74

Merge branch 'main' into global-secondary-index

201ba6e

mbhaskar and others added 2 commits April 22, 2026 14:21

Adding additional tests

0caa9c5

chandugunturi reviewed Apr 23, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Constants.java

chandugunturi reviewed Apr 23, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Constants.java Outdated

chandugunturi reviewed Apr 23, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Constants.java Outdated

xinlian12 reviewed Apr 28, 2026

View reviewed changes

ajparule approved these changes Apr 29, 2026

View reviewed changes

chandugunturi suggested changes Apr 29, 2026

View reviewed changes

mbhaskar and others added 3 commits May 11, 2026 12:52

Removing the GSI container list API from container properties as per …

00a0c91

…the discussion

Add CHANGELOG entry for Global Secondary Index (GSI) support

17d4a76

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mbhaskar requested a review from chandugunturi May 26, 2026 22:41

Merge remote-tracking branch 'upstream/main' into global-secondary-index

d13ee92

# Conflicts: # sdk/cosmos/azure-cosmos/CHANGELOG.md

Conversation

mbhaskar commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

GlobalSecondaryIndex View Support — Change Summary

Overview

Important Changes

CosmosGlobalSecondaryIndexViewDefinition.java

CosmosGlobalSecondaryIndexView.java

CosmosContainerProperties.java

Test Coverage (GlobalSecondaryIndexViewTest.java)

Notes

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xinlian12 commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jcocchi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chandugunturi left a comment

Choose a reason for hiding this comment

Uh oh!

jcocchi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

FabianMeiswinkel left a comment

Choose a reason for hiding this comment

Uh oh!

mbhaskar commented Apr 13, 2026

Uh oh!

azure-pipelines Bot commented Apr 13, 2026

Uh oh!

mbhaskar commented Apr 15, 2026

Uh oh!

azure-pipelines Bot commented Apr 15, 2026

Uh oh!

mbhaskar commented Apr 15, 2026

Uh oh!

azure-pipelines Bot commented Apr 15, 2026

Uh oh!

mbhaskar commented Apr 16, 2026

Uh oh!

azure-pipelines Bot commented Apr 16, 2026

Uh oh!

mbhaskar commented Apr 16, 2026

Uh oh!

mbhaskar commented Mar 19, 2026 •

edited

Loading

`CosmosGlobalSecondaryIndexViewDefinition.java`

`CosmosGlobalSecondaryIndexView.java`

`CosmosContainerProperties.java`

Test Coverage (`GlobalSecondaryIndexViewTest.java`)