Azure / Azure/azure-sdk-for-python

[Cosmos] Full Fidelity Change Feed (AllVersionsAndDeletes) — SME Signoff: APIs Already GA

Open
#46,636 0 comments 0 reactions 0 assignees View on GitHub
Client Cosmos
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

## Summary

The Full Fidelity Change Feed (AllVersionsAndDeletes) feature needs formal SME signoff confirming that the FFCF APIs are already GA-accessible in the Python SDK. Unlike the .NET SDK (which gates FFCF behind `#if PREVIEW` — see [azure-cosmos-dotnet-v3#5814](https://github.com/Azure/azure-cosmos-dotnet-v3/issues/5814)), the Python SDK exposes FFCF as regular public parameters with no preview gating.

This issue requests confirmation that the following APIs are intentionally GA and do not require additional ungating or contract changes.

## FFCF APIs Already Public in Python SDK

| # | API / Surface | Location | Notes |
|---|---|---|---|
| 1 | `mode="AllVersionsAndDeletes"` parameter on `query_items_change_feed()` | [container.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/container.py) (sync), [aio/_container.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py) (async) | Exposed as `Literal["LatestVersion", "AllVersionsAndDeletes"]` — core entry point for FFCF |
| 2 | Change feed item response structure (`current`, `previous`, `metadata` dict keys) | Returned from `query_items_change_feed()` when `mode="AllVersionsAndDeletes"` | No typed wrapper class (unlike .NET's `ChangeFeedItem`) — items are raw dicts |
| 3 | Change feed metadata (`operationType`, `lsn`, `crts`, `previousLsn`) | Embedded in response dict under `metadata` key | No typed model (unlike .NET's `ChangeFeedMetadata`) |
| 4 | Operation types: `create`, `replace`, `delete` | String values in `metadata["operationType"]` | No enum class (unlike .NET's `ChangeFeedOperationType`) |
| 5 | `change_feed_policy` parameter on `create_container()` / `replace_container()` | [database.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/database.py), [aio/_database.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py) | Passed as dict `{"retentionDuration": N}` — equivalent to .NET's `ChangeFeedPolicy` |
| 6 | `feed_range` parameter with change feed | [container.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/container.py) `query_items_change_feed(feed_range=...)` | Enables scoped FFCF reads |
| 7 | Internal state machine (`ChangeFeedStateV2` with mode handling) | [_change_feed/change_feed_state.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/change_feed_state.py) | Internal (`_` prefixed) — sets `FullFidelityFeedHeaderValue` and wire format headers |

## Validation Logic

The FFCF mode validation is in [_change_feed/change_feed_utils.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/azure/cosmos/_change_feed/change_feed_utils.py):
- `AllVersionsAndDeletes` mode cannot be used with `partition_key_range_id`
- `AllVersionsAndDeletes` mode requires `start_time="Now"` or `continuation`
- `is_start_from_beginning` must be `False` with FFCF

## When Was This Added?

- **Feed range support**: [PR #37687](https://github.com/Azure/azure-sdk-for-python/pull/37687)
- **Change feed mode (AllVersionsAndDeletes)**: [PR #38105](https://github.com/Azure/azure-sdk-for-python/pull/38105)
- **Tracking issue**: [#38759](https://github.com/Azure/azure-sdk-for-python/issues/38759) (closed)

## Action Requested

- [ ] SME signoff: Confirm FFCF APIs listed above are intentionally GA and no additional preview/beta gating is needed
- [ ] Confirm whether typed response models (`ChangeFeedItem`, `ChangeFeedMetadata`, `ChangeFeedOperationType`) should be added for parity with .NET, or if raw dicts are the intended GA contract
- [ ] Confirm whether open bugs [#43018](https://github.com/Azure/azure-sdk-for-python/issues/43018) (continuation token parsing) and [#42799](https://github.com/Azure/azure-sdk-for-python/issues/42799) (NonePartitionKeyValue) are blocking for formal GA declaration

## Related

- .NET GA tracking issue: [azure-cosmos-dotnet-v3#5814](https://github.com/Azure/azure-cosmos-dotnet-v3/issues/5814)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.