Add feed_range in `query_items` API #41722

allenkim0129 · 2025-06-23T17:53:41Z

Description

Feed range is now available in the query_items API. Users can pass specific feed range to query items.

Like other SDKs, feed_range cannot be used with partition_key. If both are used, an error will be raised.

exmaple:

import json

for feed_range in container.read_feed_ranges():
    for queried_item in container.query_items(
        query='SELECT * FROM c',
        enable_cross_partition_query=True,
        feed_range=feed_range,
    ):
        print(json.dumps(queried_item, indent=True))

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

github-actions · 2025-06-23T22:24:15Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

azure-cosmos

allenkim0129 · 2025-06-23T22:26:11Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-23T22:26:33Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-23T22:34:56Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-23T22:35:17Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-24T20:31:50Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-24T20:32:10Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-24T21:09:00Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-24T21:09:21Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot

Pull Request Overview

This PR adds support for the new feed_range parameter in the query_items API, bringing Python in line with other SDKs, and updates several internal utilities for argument handling and exclusive-parameter validation.

Introduced feed_range support in both sync and async query_items methods
Added add_args_to_kwargs and verify_exclusive_arguments helpers and corresponding unit tests
Updated samples, tests, partition‐key logic, and overload signatures to integrate feed_range

Reviewed Changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
samples/examples.py / examples_async.py	Added code examples for `feed_range` queries (tags need fix)
azure/cosmos/container.py	Wire in `feed_range`, drop legacy overloads, use new utils
azure/cosmos/_utils.py	Added `add_args_to_kwargs` and `verify_exclusive_arguments`
tests/test_utils.py	New unit tests for the helpers
tests/test_query_feed_range*.py	End-to-end tests for sync/async feed-range queries
other partition_key and connection code	Refactored `_get_…` APIs to `get_…`, new `PartitionKeyKind/Version`

Comments suppressed due to low confidence (4)

sdk/cosmos/azure-cosmos/samples/examples_async.py:275

The end marker here should match the start marker. Change [END query_items_param] to [END query_items_feed_range] for consistency.

        # [END query_items_param]

sdk/cosmos/azure-cosmos/samples/examples.py:152

This end tag should match the corresponding start tag [START query_items_feed_range]. Rename it to [END query_items_feed_range].

# [END query_items_param]

sdk/cosmos/azure-cosmos/azure/cosmos/container.py:592

The first overload definition doesn't include feed_range in its signature, which may confuse IDE users. You could add an overload that includes feed_range in the parameter list or adjust the existing overloads for consistency.

    def query_items(

sdk/cosmos/azure-cosmos/azure/cosmos/container.py:863

The code correctly prevents using feed_range and partition_key together, but there isn't an integration test for that error path. Consider adding a test that calls query_items with both parameters and asserts a ValueError.

        utils.verify_exclusive_arguments(["feed_range", "partition_key"], **kwargs)

sdk/cosmos/azure-cosmos/azure/cosmos/container.py

allenkim0129 · 2025-06-25T00:13:15Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-25T00:13:33Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-25T19:00:43Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-25T19:01:21Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-25T20:08:16Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-25T20:08:39Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-06-26T18:26:09Z

/azp run python - cosmos - tests

azure-pipelines · 2025-06-26T18:26:30Z

Azure Pipelines successfully started running 1 pipeline(s).

sdk/cosmos/azure-cosmos/samples/examples_async.py

sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py

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

sdk/cosmos/azure-cosmos/tests/test_query_feed_range.py

sdk/cosmos/azure-cosmos/tests/test_query_feed_range_async.py

sdk/cosmos/azure-cosmos/azure/cosmos/container.py

- Doc string updates - Tests were updated to use existing helper methods - Added tests with query_items with feed_range and partition_key

allenkim0129 · 2025-07-03T21:01:04Z

/azp run python - cosmos - tests

azure-pipelines · 2025-07-03T21:01:24Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 · 2025-07-07T18:52:58Z

/azp run python - cosmos - tests

azure-pipelines · 2025-07-07T18:53:17Z

Azure Pipelines successfully started running 1 pipeline(s).

sdk/cosmos/azure-cosmos/azure/cosmos/partition_key.py

allenkim0129 · 2025-07-11T20:10:22Z

/azp run python - cosmos - tests

azure-pipelines · 2025-07-11T20:10:42Z

Azure Pipelines successfully started running 1 pipeline(s).

allenkim0129 added 4 commits June 18, 2025 09:59

Add feed_range to query_items API

c811dd4

Added overload methods for 'query_items' API

40e61dd

Added Tests

53cf357

Added feed_range to query_item for async

609274f

github-actions bot added the Cosmos label Jun 23, 2025

github-project-automation bot added this to CosmosDB Python Eco-System Jun 23, 2025

allenkim0129 added 2 commits June 23, 2025 10:59

Added samples for query_items with feed_range

9dadc7d

Merge branch 'main' into users/allekim/addFeedRangeForQuery

2a89be8

allenkim0129 added 2 commits June 23, 2025 15:33

Fix pylint error

9958b70

Updated CHANGELOG.md

c64f832

allenkim0129 added 2 commits June 23, 2025 16:29

Fix test error

de1446f

Fix test error

fed65bf

Changed to run feed_range async tests on emulator only

643b16f

allenkim0129 marked this pull request as ready for review June 24, 2025 21:45

Copilot AI review requested due to automatic review settings June 24, 2025 21:45

allenkim0129 requested a review from a team as a code owner June 24, 2025 21:45

Copilot AI reviewed Jun 24, 2025

View reviewed changes

sdk/cosmos/azure-cosmos/azure/cosmos/container.py Show resolved Hide resolved

Fix tests

5940578

Fix tests

a06526b

Fix tests

973c4a8

Fix tests with positional_args

2a71b63

tvaron3 reviewed Jul 1, 2025

View reviewed changes

Addressing comments

1b02d46

- Doc string updates - Tests were updated to use existing helper methods - Added tests with query_items with feed_range and partition_key

Fix pylint error

da8ac14

tvaron3 reviewed Jul 11, 2025

View reviewed changes

allenkim0129 added 3 commits July 11, 2025 13:04

Changed to non-public APIs for internal classes/methods

db5b0c5

Changed to non-public APIs for internal classes/methods

ba07870

Changed to non-public APIs for internal classes/methods

28f1518

Pylint error

4a4a7bc

Add feed_range in query_items API #41722

Are you sure you want to change the base?

Add feed_range in query_items API #41722

Conversation

allenkim0129 commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

github-actions bot commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

allenkim0129 commented Jun 23, 2025

Uh oh!

azure-pipelines bot commented Jun 23, 2025

Uh oh!

allenkim0129 commented Jun 23, 2025

Uh oh!

azure-pipelines bot commented Jun 23, 2025

Uh oh!

allenkim0129 commented Jun 24, 2025

Uh oh!

azure-pipelines bot commented Jun 24, 2025

Uh oh!

allenkim0129 commented Jun 24, 2025

Uh oh!

azure-pipelines bot commented Jun 24, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

allenkim0129 commented Jun 25, 2025

Uh oh!

azure-pipelines bot commented Jun 25, 2025

Uh oh!

allenkim0129 commented Jun 25, 2025

Uh oh!

azure-pipelines bot commented Jun 25, 2025

Uh oh!

allenkim0129 commented Jun 25, 2025

Uh oh!

azure-pipelines bot commented Jun 25, 2025

Uh oh!

allenkim0129 commented Jun 26, 2025

Uh oh!

azure-pipelines bot commented Jun 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

allenkim0129 commented Jul 3, 2025

Uh oh!

azure-pipelines bot commented Jul 3, 2025

Uh oh!

allenkim0129 commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

allenkim0129 commented Jul 11, 2025

Uh oh!

azure-pipelines bot commented Jul 11, 2025

Uh oh!

Uh oh!

Add feed_range in `query_items` API #41722

Add feed_range in `query_items` API #41722

allenkim0129 commented Jun 23, 2025 •

edited

Loading

github-actions bot commented Jun 23, 2025 •

edited

Loading