Add GlobalSecondaryIndexDefinition for GSI container support

- Create GlobalSecondaryIndexDefinition class with validation, serialization,
  and dual-write pattern (globalSecondaryIndexDefinition + materializedViewDefinition)
- Add global_secondary_index_definition keyword to create_container,
  create_container_if_not_exists, and replace_container (sync and async)
- Add unit tests (21 tests) and live test infrastructure
- Add GSI pipeline configuration (pytest mark, matrix entry, env var mapping)
- Update CHANGELOG.md and api.md

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

Author: mbhaskar

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -3,6 +3,7 @@
 ### 4.16.2 (Unreleased)
 
 #### Features Added
+* Added `GlobalSecondaryIndexDefinition` class and `global_secondary_index_definition` keyword to `create_container`, `create_container_if_not_exists`, and `replace_container` methods for creating Global Secondary Index (GSI) containers. See [PR 47468](https://github.com/Azure/azure-sdk-for-python/pull/47468).
 
 #### Breaking Changes
 

sdk/cosmos/azure-cosmos/api.md

@@ -646,6 +646,7 @@ namespace azure.cosmos
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -668,6 +669,7 @@ namespace azure.cosmos
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -690,6 +692,7 @@ namespace azure.cosmos
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -712,6 +715,7 @@ namespace azure.cosmos
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -838,6 +842,7 @@ namespace azure.cosmos
                 analytical_storage_ttl: Optional[int] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -857,6 +862,7 @@ namespace azure.cosmos
                 analytical_storage_ttl: Optional[int] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -892,6 +898,19 @@ namespace azure.cosmos
             ) -> UserProxy: ...
 
 
+    class azure.cosmos.GlobalSecondaryIndexDefinition:
+        property definition: str    # Read-only
+        property source_container_id: str    # Read-only
+        property source_container_rid: Optional[str]    # Read-only
+        property status: Optional[str]    # Read-only
+
+        def __init__(
+                self, 
+                source_container_id: str, 
+                definition: str
+            ): ...
+
+
     class azure.cosmos.IndexKind:
         Hash: Literal["Hash"] = Hash
         MultiHash: Literal["MultiHash"] = MultiHash
@@ -1830,6 +1849,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 offer_throughput: Optional[Union[int, ThroughputProperties]] = ..., 
@@ -1851,6 +1871,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 offer_throughput: Optional[Union[int, ThroughputProperties]] = ..., 
@@ -1872,6 +1893,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 offer_throughput: Optional[Union[int, ThroughputProperties]] = ..., 
@@ -1893,6 +1915,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 offer_throughput: Optional[Union[int, ThroughputProperties]] = ..., 
@@ -2004,6 +2027,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
@@ -2022,6 +2046,7 @@ namespace azure.cosmos.aio
                 conflict_resolution_policy: Optional[dict[str, str]] = ..., 
                 default_ttl: Optional[int] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 indexing_policy: Optional[dict[str, str]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
@@ -2909,6 +2934,7 @@ namespace azure.cosmos.database
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -2931,6 +2957,7 @@ namespace azure.cosmos.database
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -2953,6 +2980,7 @@ namespace azure.cosmos.database
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -2975,6 +3003,7 @@ namespace azure.cosmos.database
                 change_feed_policy: Optional[dict[str, Any]] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -3101,6 +3130,7 @@ namespace azure.cosmos.database
                 analytical_storage_ttl: Optional[int] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[False] = False, 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 
@@ -3120,6 +3150,7 @@ namespace azure.cosmos.database
                 analytical_storage_ttl: Optional[int] = ..., 
                 computed_properties: Optional[list[dict[str, str]]] = ..., 
                 full_text_policy: Optional[dict[str, Any]] = ..., 
+                global_secondary_index_definition: Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] = ..., 
                 initial_headers: Optional[dict[str, str]] = ..., 
                 return_properties: Literal[True], 
                 vector_embedding_policy: Optional[dict[str, Any]] = ..., 

sdk/cosmos/azure-cosmos/api.metadata.yml

@@ -1,3 +1,3 @@
-apiMdSha256: de3b8c0f2a0405fac7152d562c982bf98bf7bb546c46f05e39164574e47f7f7a
+apiMdSha256: 2e3b8901f784591bea2745cad02d1dd4c524db0702d0f357774f896de263fdf0
 parserVersion: 0.3.28
-pythonVersion: 3.13.14
+pythonVersion: 3.10.20

sdk/cosmos/azure-cosmos/azure/cosmos/__init__.py

@@ -43,6 +43,7 @@
 )
 from .partition_key import PartitionKey
 from .permission import Permission
+from ._global_secondary_index import GlobalSecondaryIndexDefinition
 
 __all__ = (
     "CosmosClient",
@@ -66,6 +67,7 @@
     "ConnectionRetryPolicy",
     "ThroughputProperties",
     "CosmosDict",
-    "CosmosList"
+    "CosmosList",
+    "GlobalSecondaryIndexDefinition"
 )
 __version__ = VERSION

sdk/cosmos/azure-cosmos/azure/cosmos/_global_secondary_index.py

@@ -0,0 +1,123 @@
+# The MIT License (MIT)
+# Copyright (c) 2014 Microsoft Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Global Secondary Index (GSI) container definition."""
+
+from typing import Optional
+
+
+class GlobalSecondaryIndexDefinition:
+    """**provisional** Definition for a Global Secondary Index (GSI) container.
+
+    A GSI container is a derived container built from a source container
+    using a SQL-like projection query. The GSI definition is immutable after creation.
+
+    .. note::
+        A maximum of 5 GSI containers can be created per source container.
+        All GSI containers must be deleted before deleting the source container.
+
+    :param str source_container_id: The ID of the source container the GSI is derived from. Required.
+    :param str definition: The SQL-like projection query that defines the GSI. Required.
+    """
+
+    def __init__(self, source_container_id: str, definition: str):
+        if not source_container_id or not source_container_id.strip():
+            raise ValueError("source_container_id cannot be None or empty.")
+        if not definition or not definition.strip():
+            raise ValueError("definition cannot be None or empty.")
+        self._source_container_id = source_container_id
+        self._definition = definition
+        self._source_container_rid: Optional[str] = None
+        self._status: Optional[str] = None
+
+    @property
+    def source_container_id(self) -> str:
+        """The ID of the source container.
+
+        :returns: The source container ID.
+        :rtype: str
+        """
+        return self._source_container_id
+
+    @property
+    def definition(self) -> str:
+        """The SQL-like projection query that defines the GSI.
+
+        :returns: The projection query.
+        :rtype: str
+        """
+        return self._definition
+
+    @property
+    def source_container_rid(self) -> Optional[str]:
+        """The server-populated resource ID (_rid) of the source container. Read-only.
+
+        :returns: The source container resource ID, or None if not yet populated.
+        :rtype: str or None
+        """
+        return self._source_container_rid
+
+    @property
+    def status(self) -> Optional[str]:
+        """The GSI build status. Read-only, server-populated.
+
+        Possible values: "Initializing", "InitialBuildAfterCreate",
+        "InitialBuildAfterRestore", "Active", "DeleteInProgress"
+
+        :returns: The GSI status, or None if not yet populated.
+        :rtype: str or None
+        """
+        return self._status
+
+    def _to_dict(self) -> dict:
+        """Serialize to wire format dict.
+
+        :returns: A dictionary representation of the GSI definition.
+        :rtype: dict
+        """
+        result: dict = {
+            "sourceCollectionId": self._source_container_id,
+            "definition": self._definition,
+        }
+        if self._source_container_rid is not None:
+            result["sourceCollectionRid"] = self._source_container_rid
+        if self._status is not None:
+            result["status"] = self._status
+        return result
+
+    @classmethod
+    def _from_dict(cls, data: Optional[dict]) -> Optional["GlobalSecondaryIndexDefinition"]:
+        """Deserialize from wire format dict.
+
+        :param dict data: The wire format dictionary.
+        :returns: A GlobalSecondaryIndexDefinition instance, or None if data is None or invalid.
+        :rtype: ~azure.cosmos.GlobalSecondaryIndexDefinition or None
+        """
+        if data is None:
+            return None
+        source_container_id = data.get("sourceCollectionId")
+        definition_query = data.get("definition")
+        if not source_container_id or not definition_query:
+            return None
+        instance = cls(source_container_id, definition_query)
+        instance._source_container_rid = data.get("sourceCollectionRid")  # pylint: disable=protected-access
+        instance._status = data.get("status")  # pylint: disable=protected-access
+        return instance