[Cosmos] Add preview support for change feed previous images

[Simon Moreno (simorenoh)]

Adds provisional support for consuming previous item images returned by AllVersionsAndDeletes change feed.

• Documents the optional previous response member for sync and async change feed APIs.
• Updates sync and async samples to consume previous images safely.
• Enables the service preview override in Cosmos emulator CI.
• Replaces test-side synthesized previous data with validation of the actual response.
• Expands sync and async coverage for create, replace, delete, TTL expiration, continuation replay, and optional previous-image pass-through.

No new SDK request option is introduced because previous-image enablement is service-side, consistent with the .NET implementation.

Closes #49054

Targeted sync and async pass-through and live-account AVAD tests pass. Cosmos mypy checks also pass.

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
7 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
7 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

Replace previous images and TTL expirations need service-backed assertions, and the required changelog entry is missing.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds provisional Azure Cosmos change-feed previous-image support documentation, samples, emulator configuration, and validation.

Changes:

• Documents and demonstrates optional previous images.
• Enables emulator preview behavior.
• Expands sync and async change-feed tests.

File summaries

File	Description
tests/test_change_feed_all_versions.py	Expands sync coverage.
tests/test_change_feed_all_versions_async.py	Expands async coverage.
samples/change_feed_management.py	Demonstrates sync consumption.
samples/change_feed_management_async.py	Demonstrates async consumption.
azure/cosmos/container.py	Documents sync response contract.
azure/cosmos/aio/_container.py	Documents async response contract.
eng/pipelines/templates/stages/cosmos-sdk-client.yml	Enables emulator preview override.

Review details

Suppressed comments (2)

sdk/cosmos/azure-cosmos/tests/test_change_feed_all_versions.py:185

• The real emulator replace response does not verify the feature being added here. assert_change_feed only checks fields present in expected_change_feeds, and this expectation omits previous, so the test still passes if replace events lose their previous image. Add the prior item body to the emulator expectation (and seed a version-1 field if the version transition should be asserted).

        expected_change_feeds = [
            {CURRENT: {ID: f'doc{i}', VERSION: 2}, METADATA: {OPERATION_TYPE: REPLACE}}
            for i in range(4)
        ]

sdk/cosmos/azure-cosmos/tests/test_change_feed_all_versions_async.py:193

• The real emulator replace response does not verify the feature being added here. assert_change_feed only checks fields present in expected_change_feeds, and this expectation omits previous, so the test still passes if replace events lose their previous image. Add the prior item body to the emulator expectation (and seed a version-1 field if the version transition should be asserted).

        expected_change_feeds = [
            {CURRENT: {ID: f'doc{i}', VERSION: 2}, METADATA: {OPERATION_TYPE: REPLACE}}
            for i in range(4)
        ]

• Files reviewed: 7/7 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

[Pilot] PR Pipeline Failure Analysis

What failed

Azure Pipeline build 6850060 (result: failed) — the Cosmos Python Emulator Tests stage failed across all 10 test-artifact combinations (Python 3.10–3.14, whl + sdist installs on windows2022), with 1,940 failed test cases (194 unique tests × 10 build variants).

Root cause 1 (dominant, ~1,900 of the failures): A shared test database's collection quota (max 25 collections per database offer) is exhausted mid-run, causing cascading CosmosHttpResponseError: (BadRequest) Collection create forbidden as collection count in database offer has exceeded 25 errors in unrelated tests (test_headers, test_partition_key, test_read_items, test_retry_policy, test_retryable_writes, test_session, test_timeout_and_failover_retry_policy, etc.). This is a leaked-collection issue, not a bug in those individual tests. The leak traces to this PR's new tests: test_query_change_feed_ttl_delete and test_query_change_feed_ttl_delete_async in sdk/cosmos/azure-cosmos/tests/test_change_feed_all_versions.py / test_change_feed_all_versions_async.py. Each test calls setup["key_db"].create_container(cid, ...) to create a new container per invocation but never deletes it afterward, so containers accumulate in the shared class-scoped database across the run until the 25-collection cap is hit and all subsequent container-creating tests fail.

Root cause 2 (40 failures): test_query_change_feed_ttl_delete / _async themselves time out with AssertionError: Timed out waiting for the TTL delete change. (250s+50s timeout) waiting for the emulator to surface a TTL-expiration delete change with timeToLiveExpired: True. This may be related to the new /overrides=enablePreviousImageForDeleteInFFCF:true emulator start parameter added by this PR in eng/pipelines/templates/stages/cosmos-sdk-client.yml, or the emulator's TTL background sweep not completing within the test's wait window in this CI environment.

Relevant pipeline output

tests/test_change_feed_all_versions.py:287: AssertionError
E       AssertionError: Timed out waiting for the TTL delete change.
E       assert None is not None

tests/test_headers.py:271: (from test_container_delete_all_items_by_partition_key_throughput_bucket)
E       azure.cosmos.exceptions.CosmosHttpResponseError: (BadRequest) Message: {"Errors":["Collection create forbidden as collection count in database offer has exceeded 25."]}
E       Code: BadRequest
E       Sub Status: 1019

tests/test_partition_key.py:253: (from test_hash_v1_partition_key_definition)
E       azure.cosmos.exceptions.CosmosHttpResponseError: (BadRequest) Message: {"Errors":["Collection create forbidden as collection count in database offer has exceeded 25."]}

Recommended next steps

• Add cleanup for the container created in test_query_change_feed_ttl_delete (sync, tests/test_change_feed_all_versions.py) and test_query_change_feed_ttl_delete_async (tests/test_change_feed_all_versions_async.py), e.g. setup["key_db"].delete_container(cid) in a finally block, so the new tests don't leak containers into the shared database across the full test run.
• If cleanup alone doesn't resolve the TTL-wait timeouts, investigate whether /overrides=enablePreviousImageForDeleteInFFCF:true in eng/pipelines/templates/stages/cosmos-sdk-client.yml affects TTL sweep timing on the emulator, or increase the TTL wait/retention window for the emulator environment.
• See https://aka.ms/ci-fix

Automated fix: Fix found, view and apply fix

Generated by Pipeline Analysis Next Steps · auto · 203.6 AIC · ⌖ 1.88 AIC · ⊞ 8.7K · ◷