Add 'change_feed_mode' to 'query_items_change_feed' API

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -10,6 +10,7 @@ This version and all future versions will support Python 3.13.
 * Added option to disable write payload on writes. See [PR 37365](https://github.com/Azure/azure-sdk-for-python/pull/37365)
 * Added get feed ranges API. See [PR 37687](https://github.com/Azure/azure-sdk-for-python/pull/37687)
 * Added feed range support in `query_items_change_feed`. See [PR 37687](https://github.com/Azure/azure-sdk-for-python/pull/37687)
+* Added change feed mode support in `query_items_change_feed`. See [PR 38105](https://github.com/Azure/azure-sdk-for-python/pull/38105)
 
 #### Breaking Changes
 * Item-level point operations will now return `CosmosDict` and `CosmosList` response types. 

sdk/cosmos/azure-cosmos/azure/cosmos/_base.py

@@ -61,7 +61,8 @@
     'supported_query_features': 'supportedQueryFeatures',
     'query_version': 'queryVersion',
     'priority': 'priorityLevel',
-    'no_response': 'responsePayloadOnWriteDisabled'
+    'no_response': 'responsePayloadOnWriteDisabled',
+    'max_item_count': 'maxItemCount',
 }
 
 # Cosmos resource ID validation regex breakdown:
@@ -170,6 +171,7 @@ def GetHeaders(  # pylint: disable=too-many-statements,too-many-branches
     # set consistency level. check if set via options, this will override the default
     if options.get("consistencyLevel"):
         consistency_level = options["consistencyLevel"]
+        # TODO: move this line outside of if-else cause to remove the code duplication
         headers[http_constants.HttpHeaders.ConsistencyLevel] = consistency_level
     elif default_client_consistency_level is not None:
         consistency_level = default_client_consistency_level

sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/change_feed_state.py

@@ -29,6 +29,7 @@
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Optional, Union, List, Any, Dict, Deque
+import warnings
 
 from azure.cosmos import http_constants
 from azure.cosmos._change_feed.change_feed_start_from import ChangeFeedStartFromInternal, \
@@ -48,6 +49,17 @@ class ChangeFeedStateVersion(Enum):
     V1 = "v1"
     V2 = "v2"
 
+class ChangeFeedMode(Enum):
+    LATEST_VERSION = "LatestVersion"
+    ALL_VERSIONS_AND_DELETES = "AllVersionsAndDeletes"
+
+    def __str__(self):
+        return self.value
+
+    @classmethod
+    def to_string(cls):
+        return f"[{', '.join(f"'{item.value}'" for item in cls)}]"
+
 class ChangeFeedState(ABC):
     version_property_name = "v"
 
@@ -96,7 +108,9 @@ def from_json(
                 raise ValueError("Invalid base64 encoded continuation string [Missing version]")
 
             if version == ChangeFeedStateVersion.V2.value:
-                return ChangeFeedStateV2.from_continuation(container_link, container_rid, continuation_json)
+                change_feed_mode = change_feed_state_context.get("changeFeedMode")
+                return ChangeFeedStateV2.from_continuation(
+                    container_link, container_rid, continuation_json, change_feed_mode)
 
             raise ValueError("Invalid base64 encoded continuation string [Invalid version]")
 
@@ -180,14 +194,14 @@ class ChangeFeedStateV2(ChangeFeedState):
     change_feed_start_from_property_name = "startFrom"
     continuation_property_name = "continuation"
 
-    # TODO: adding change feed mode
     def __init__(
             self,
             container_link: str,
             container_rid: str,
             feed_range: FeedRangeInternal,
             change_feed_start_from: ChangeFeedStartFromInternal,
-            continuation: Optional[FeedRangeCompositeContinuation]
+            continuation: Optional[FeedRangeCompositeContinuation],
+            change_feed_mode: ChangeFeedMode
     ) -> None:
 
         self._container_link = container_link
@@ -208,6 +222,14 @@ def __init__(
         else:
             self._continuation = continuation
 
+        if change_feed_mode is None or change_feed_mode == ChangeFeedMode.LATEST_VERSION:
+            self._change_feed_mode = http_constants.HttpHeaders.IncrementalFeedHeaderValue
+        elif change_feed_mode == ChangeFeedMode.ALL_VERSIONS_AND_DELETES:
+            self._change_feed_mode = http_constants.HttpHeaders.FullFidelityFeedHeaderValue
+        else:
+            raise ValueError(f"Invalid change_feed_mode was used: '{change_feed_mode}'."
+                             f" Supported change_feed_modes are 'LatestVersion' and 'AllVersionsAndDeletes'.")
+
         super(ChangeFeedStateV2, self).__init__(ChangeFeedStateVersion.V2)
 
     @property
@@ -218,17 +240,14 @@ def to_dict(self) -> Dict[str, Any]:
         return {
             self.version_property_name: ChangeFeedStateVersion.V2.value,
             self.container_rid_property_name: self._container_rid,
-            self.change_feed_mode_property_name: "Incremental",
+            self.change_feed_mode_property_name: self._change_feed_mode,
             self.change_feed_start_from_property_name: self._change_feed_start_from.to_dict(),
             self.continuation_property_name: self._continuation.to_dict() if self._continuation is not None else None
         }
 
-    def populate_request_headers(
+    def set_start_from_request_headers(
             self,
-            routing_provider: SmartRoutingMapProvider,
             request_headers: Dict[str, Any]) -> None:
-        request_headers[http_constants.HttpHeaders.AIM] = http_constants.HttpHeaders.IncrementalFeedHeaderValue
-
         # When a merge happens, the child partition will contain documents ordered by LSN but the _ts/creation time
         # of the documents may not be sequential.
         # So when reading the changeFeed by LSN, it is possible to encounter documents with lower _ts.
@@ -243,11 +262,10 @@ def populate_request_headers(
                     self._continuation.current_token.feed_range)
             change_feed_start_from_feed_range_and_etag.populate_request_headers(request_headers)
 
-        # based on the feed range to find the overlapping partition key range id
-        over_lapping_ranges =\
-            routing_provider.get_overlapping_ranges(
-                self._container_link,
-                [self._continuation.current_token.feed_range])
+    def set_pk_range_id_request_headers(
+            self,
+            over_lapping_ranges,
+            request_headers: Dict[str, Any]) -> None:
 
         if len(over_lapping_ranges) > 1:
             raise self.get_feed_range_gone_error(over_lapping_ranges)
@@ -260,53 +278,51 @@ def populate_request_headers(
             # the current token feed range spans less than single physical partition
             # for this case, need to set both the partition key range id and epk filter headers
             request_headers[http_constants.HttpHeaders.PartitionKeyRangeID] = over_lapping_ranges[0]["id"]
-            request_headers[
-                http_constants.HttpHeaders.StartEpkString] = self._continuation.current_token.feed_range.min
-            request_headers[
-                http_constants.HttpHeaders.EndEpkString] = self._continuation.current_token.feed_range.max
+            request_headers[http_constants.HttpHeaders.StartEpkString] = self._continuation.current_token.feed_range.min
+            request_headers[http_constants.HttpHeaders.EndEpkString] = self._continuation.current_token.feed_range.max
 
-    async def populate_request_headers_async(
+    def set_change_feed_mode_request_headers(
             self,
-            async_routing_provider: AsyncSmartRoutingMapProvider,
             request_headers: Dict[str, Any]) -> None:
+
         request_headers[http_constants.HttpHeaders.AIM] = http_constants.HttpHeaders.IncrementalFeedHeaderValue
+        if self._change_feed_mode == http_constants.HttpHeaders.FullFidelityFeedHeaderValue:
+            request_headers[http_constants.HttpHeaders.AIM] = self._change_feed_mode
+            request_headers[http_constants.HttpHeaders.ChangeFeedWireFormatVersion] =\
+                http_constants.HttpHeaders.Separate_meta_with_crts
 
-        # When a merge happens, the child partition will contain documents ordered by LSN but the _ts/creation time
-        # of the documents may not be sequential.
-        # So when reading the changeFeed by LSN, it is possible to encounter documents with lower _ts.
-        # In order to guarantee we always get the documents after customer's point start time,
-        # we will need to always pass the start time in the header.
-        self._change_feed_start_from.populate_request_headers(request_headers)
+    def populate_request_headers(
+            self,
+            routing_provider: SmartRoutingMapProvider,
+            request_headers: Dict[str, Any]) -> None:
+        self.set_start_from_request_headers(request_headers)
 
-        if self._continuation.current_token is not None and self._continuation.current_token.token is not None:
-            change_feed_start_from_feed_range_and_etag = \
-                ChangeFeedStartFromETagAndFeedRange(
-                    self._continuation.current_token.token,
-                    self._continuation.current_token.feed_range)
-            change_feed_start_from_feed_range_and_etag.populate_request_headers(request_headers)
+        # based on the feed range to find the overlapping partition key range id
+        over_lapping_ranges = \
+            routing_provider.get_overlapping_ranges(
+                self._container_link,
+                [self._continuation.current_token.feed_range])
+
+        self.set_pk_range_id_request_headers(over_lapping_ranges, request_headers)
+
+        self.set_change_feed_mode_request_headers(request_headers)
+
+
+    async def populate_request_headers_async(
+            self,
+            async_routing_provider: AsyncSmartRoutingMapProvider,
+            request_headers: Dict[str, Any]) -> None:
+        self.set_start_from_request_headers(request_headers)
 
         # based on the feed range to find the overlapping partition key range id
         over_lapping_ranges = \
             await async_routing_provider.get_overlapping_ranges(
                 self._container_link,
                 [self._continuation.current_token.feed_range])
 
-        if len(over_lapping_ranges) > 1:
-            raise self.get_feed_range_gone_error(over_lapping_ranges)
+        self.set_pk_range_id_request_headers(over_lapping_ranges, request_headers)
 
-        overlapping_feed_range = Range.PartitionKeyRangeToRange(over_lapping_ranges[0])
-        if overlapping_feed_range == self._continuation.current_token.feed_range:
-            # exactly mapping to one physical partition, only need to set the partitionKeyRangeId
-            request_headers[http_constants.HttpHeaders.PartitionKeyRangeID] = over_lapping_ranges[0]["id"]
-        else:
-            # the current token feed range spans less than single physical partition
-            # for this case, need to set both the partition key range id and epk filter headers
-            request_headers[http_constants.HttpHeaders.PartitionKeyRangeID] = \
-                over_lapping_ranges[0]["id"]
-            request_headers[http_constants.HttpHeaders.StartEpkString] = \
-                self._continuation.current_token.feed_range.min
-            request_headers[http_constants.HttpHeaders.EndEpkString] = \
-                self._continuation.current_token.feed_range.max
+        self.set_change_feed_mode_request_headers(request_headers)
 
     def populate_feed_options(self, feed_options: Dict[str, Any]) -> None:
         pass
@@ -349,7 +365,8 @@ def from_continuation(
             cls,
             container_link: str,
             container_rid: str,
-            continuation_json: Dict[str, Any]) -> 'ChangeFeedStateV2':
+            continuation_json: Dict[str, Any],
+            change_feed_mode: ChangeFeedMode) -> 'ChangeFeedStateV2':
 
         container_rid_from_continuation = continuation_json.get(ChangeFeedStateV2.container_rid_property_name)
         if container_rid_from_continuation is None:
@@ -367,12 +384,13 @@ def from_continuation(
         if continuation_data is None:
             raise ValueError(f"Invalid continuation: [Missing {ChangeFeedStateV2.continuation_property_name}]")
         continuation = FeedRangeCompositeContinuation.from_json(continuation_data)
-        return ChangeFeedStateV2(
+        return cls(
             container_link=container_link,
             container_rid=container_rid,
             feed_range=continuation.feed_range,
             change_feed_start_from=change_feed_start_from,
-            continuation=continuation)
+            continuation=continuation,
+            change_feed_mode=change_feed_mode)
 
     @classmethod
     def from_initial_state(
@@ -381,7 +399,6 @@ def from_initial_state(
             collection_rid: str,
             change_feed_state_context: Dict[str, Any]) -> 'ChangeFeedStateV2':
 
-        feed_range: Optional[FeedRangeInternal] = None
         if change_feed_state_context.get("feedRange"):
             feed_range = FeedRangeInternalEpk.from_json(change_feed_state_context["feedRange"])
         elif change_feed_state_context.get("partitionKey"):
@@ -394,6 +411,7 @@ def from_initial_state(
                 raise ValueError("partitionKey is in the changeFeedStateContext, but missing partitionKeyFeedRange")
         else:
             # default to full range
+            warnings.warn("'feed_range' empty. Use full range by default.", UserWarning)
             feed_range = FeedRangeInternalEpk(
                 Range(
                 "",
@@ -405,11 +423,12 @@ def from_initial_state(
         change_feed_start_from = (
             ChangeFeedStartFromInternal.from_start_time(change_feed_state_context.get("startTime")))
 
-        if feed_range is not None:
-            return cls(
-                container_link=container_link,
-                container_rid=collection_rid,
-                feed_range=feed_range,
-                change_feed_start_from=change_feed_start_from,
-                continuation=None)
-        raise ValueError("feed_range is empty")
+        change_feed_mode = change_feed_state_context.get("changeFeedMode")
+
+        return cls(
+            container_link=container_link,
+            container_rid=collection_rid,
+            feed_range=feed_range,
+            change_feed_start_from=change_feed_start_from,
+            continuation=None,
+            change_feed_mode=change_feed_mode)