Add GlobalSecondaryIndexDefinition for GSI container support

Implement client-side support for Global Secondary Index (GSI) containers
in the Python Cosmos SDK, mirroring the Java SDK implementation.

Changes:
- Add GlobalSecondaryIndexDefinition class with serialization/deserialization
- Add global_secondary_index_definition keyword to create_container,
  create_container_if_not_exists, and replace_container (sync and async)
- Implement dual-write pattern: writes to both globalSecondaryIndexDefinition
  and materializedViewDefinition keys for backward compatibility
- Add comprehensive unit tests (20 tests)
- Update CHANGELOG

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

Author: mbhaskar

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -7,6 +7,7 @@
 * Added `get_response_headers()` and `get_last_response_headers()` methods to the `CosmosItemPaged` and `CosmosAsyncItemPaged` objects returned by `query_items()`, allowing access to response headers from query operations. See [PR 44593](https://github.com/Azure/azure-sdk-for-python/pull/44593)
 * Added InferenceRequestTimeout property for HttpTimeout Policy to Reranking API. See [45469](https://github.com/Azure/azure-sdk-for-python/pull/45469)
 * Added `full_text_score_scope` parameter to `query_items()` for controlling BM25 statistics scope in hybrid search queries. Supports "Local" and "Global" (default) scopes. See [45686](https://github.com/Azure/azure-sdk-for-python/pull/45686)
+* 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.
 
 #### Breaking Changes
 

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:
+    """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

sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py

@@ -178,6 +178,7 @@ async def create_container(
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         change_feed_policy: Optional[dict[str, Any]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[False] = False,
         **kwargs: Any
     ) -> ContainerProxy:
@@ -255,6 +256,7 @@ async def create_container( # pylint: disable=too-many-statements
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         change_feed_policy: Optional[dict[str, Any]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[True],
         **kwargs: Any
     ) -> tuple[ContainerProxy, CosmosDict]:
@@ -353,6 +355,9 @@ async def create_container( # pylint:disable=docstring-should-be-keyword, too-ma
         :keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
             Used to denote the default language to be used for all full text indexes, or to individually
             assign a language to each full text index path.
+        :keyword global_secondary_index_definition: The global secondary index definition for the container.
+            Used to create a GSI container derived from a source container via a SQL projection query.
+        :paramtype global_secondary_index_definition: ~azure.cosmos.GlobalSecondaryIndexDefinition or dict[str, Any]
         :keyword bool return_properties: Specifies whether to return either a ContainerProxy
             or a Tuple of a ContainerProxy and the container properties.
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The container creation failed.
@@ -393,6 +398,7 @@ async def create_container( # pylint:disable=docstring-should-be-keyword, too-ma
         computed_properties = kwargs.pop('computed_properties', None)
         change_feed_policy = kwargs.pop('change_feed_policy', None)
         full_text_policy = kwargs.pop('full_text_policy', None)
+        global_secondary_index_definition = kwargs.pop('global_secondary_index_definition', None)
         return_properties = kwargs.pop('return_properties', False)
 
         session_token = kwargs.get('session_token')
@@ -440,6 +446,12 @@ async def create_container( # pylint:disable=docstring-should-be-keyword, too-ma
             definition["changeFeedPolicy"] = change_feed_policy
         if full_text_policy is not None:
             definition["fullTextPolicy"] = full_text_policy
+        if global_secondary_index_definition is not None:
+            gsi_dict = (global_secondary_index_definition._to_dict()
+                        if hasattr(global_secondary_index_definition, '_to_dict')
+                        else global_secondary_index_definition)
+            definition["globalSecondaryIndexDefinition"] = gsi_dict
+            definition["materializedViewDefinition"] = gsi_dict
         request_options = _build_options(kwargs)
         _set_throughput_options(offer=offer_throughput, request_options=request_options)
 
@@ -467,6 +479,7 @@ async def create_container_if_not_exists(
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         change_feed_policy: Optional[dict[str, Any]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[False] = False,
         **kwargs: Any
     ) -> ContainerProxy:
@@ -528,6 +541,7 @@ async def create_container_if_not_exists(
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         change_feed_policy: Optional[dict[str, Any]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[True],
         **kwargs: Any
     ) -> tuple[ContainerProxy, CosmosDict]:
@@ -612,6 +626,9 @@ async def create_container_if_not_exists( # pylint:disable=docstring-should-be-k
         :keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
             Used to denote the default language to be used for all full text indexes, or to individually
             assign a language to each full text index path.
+        :keyword global_secondary_index_definition: The global secondary index definition for the container.
+            Used to create a GSI container derived from a source container via a SQL projection query.
+        :paramtype global_secondary_index_definition: ~azure.cosmos.GlobalSecondaryIndexDefinition or dict[str, Any]
         :keyword bool return_properties: Specifies whether to return either a ContainerProxy
             or a Tuple of a ContainerProxy and the container properties.
         :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: The container creation failed.
@@ -635,6 +652,7 @@ async def create_container_if_not_exists( # pylint:disable=docstring-should-be-k
         computed_properties = kwargs.pop('computed_properties', None)
         change_feed_policy = kwargs.pop('change_feed_policy', None)
         full_text_policy = kwargs.pop('full_text_policy', None)
+        global_secondary_index_definition = kwargs.pop('global_secondary_index_definition', None)
         return_properties = kwargs.pop('return_properties', False)
 
         session_token = kwargs.get('session_token')
@@ -679,6 +697,7 @@ async def create_container_if_not_exists( # pylint:disable=docstring-should-be-k
                 vector_embedding_policy=vector_embedding_policy,
                 change_feed_policy=change_feed_policy,
                 full_text_policy=full_text_policy,
+                global_secondary_index_definition=global_secondary_index_definition,
                 return_properties=return_properties,
                 **kwargs
             )
@@ -816,6 +835,7 @@ async def replace_container(
         analytical_storage_ttl: Optional[int] = None,
         computed_properties: Optional[list[dict[str, str]]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[False] = False,
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         **kwargs: Any
@@ -877,6 +897,7 @@ async def replace_container( # pylint:disable=docstring-missing-param
         analytical_storage_ttl: Optional[int] = None,
         computed_properties: Optional[list[dict[str, str]]] = None,
         full_text_policy: Optional[dict[str, Any]] = None,
+        global_secondary_index_definition: Optional[Any] = None,
         return_properties: Literal[True],
         vector_embedding_policy: Optional[dict[str, Any]] = None,
         **kwargs: Any
@@ -959,6 +980,9 @@ async def replace_container( # pylint:disable=docstring-should-be-keyword
         :keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
             Used to denote the default language to be used for all full text indexes, or to individually
             assign a language to each full text index path.
+        :keyword global_secondary_index_definition: The global secondary index definition for the container.
+            Used to create a GSI container derived from a source container via a SQL projection query.
+        :paramtype global_secondary_index_definition: ~azure.cosmos.GlobalSecondaryIndexDefinition or dict[str, Any]
         :keyword bool return_properties: Specifies whether to return either a ContainerProxy
             or a Tuple of a ContainerProxy and the container properties.
         :returns: A `ContainerProxy` instance representing the new container or a tuple of the ContainerProxy
@@ -989,6 +1013,7 @@ async def replace_container( # pylint:disable=docstring-should-be-keyword
         analytical_storage_ttl = kwargs.pop('analytical_storage_ttl', None)
         computed_properties = kwargs.pop('computed_properties', None)
         full_text_policy = kwargs.pop('full_text_policy', None)
+        global_secondary_index_definition = kwargs.pop('global_secondary_index_definition', None)
         return_properties = kwargs.pop('return_properties', False)
         vector_embedding_policy = kwargs.pop('vector_embedding_policy', None)
 
@@ -1031,6 +1056,12 @@ async def replace_container( # pylint:disable=docstring-should-be-keyword
             }.items()
             if value is not None
         }
+        if global_secondary_index_definition is not None:
+            gsi_dict = (global_secondary_index_definition._to_dict()
+                        if hasattr(global_secondary_index_definition, '_to_dict')
+                        else global_secondary_index_definition)
+            parameters["globalSecondaryIndexDefinition"] = gsi_dict
+            parameters["materializedViewDefinition"] = gsi_dict
 
         container_properties = await self.client_connection.ReplaceContainer(
             container_link, collection=parameters, options=request_options, **kwargs