[Cosmos] Feed range APIs

[simorenoh]

We should provide our users with the feed range APIs we have in other SDKs to allow them more options to use against our queries and change feed APIs.

[github-actions]

🎯 Agentic Issue Triage

Summary: Feature request to add feed range APIs to the Cosmos DB Rust SDK, bringing it to parity with other Azure Cosmos DB SDKs (Java, .NET, Python). Feed ranges enable partition-aware querying and change feed reading, which are critical for high-throughput distributed workloads.

📋 Analysis

Type: Feature request / SDK parity
Affected crate: azure_data_cosmos (under sdk/cosmos/)
Author association: MEMBER (team-internal tracking issue)

Feed range APIs exist in other Cosmos DB SDKs and allow users to:

• Enumerate and work with physical partition ranges in a container
• Execute per-partition (feed-range-scoped) queries
• Read change feed for a specific feed range (partition subset)
• Support fan-out patterns — distributing workloads across partitions in parallel

This is a natural follow-on to the Container Metadata Cache work (#3083, now closed) and the ongoing driver migration (#3906), since feed range computation relies on partition key range data from the metadata cache.

🔗 Related Issues & Context

• Cosmos: Switch SDK over to using the driver #3906 — Cosmos: Switch SDK over to using the driver (open) — feed range APIs will likely want to build on top of the driver architecture
• Cosmos: Build a Container Metadata Cache #3083 — Cosmos: Build a Container Metadata Cache (closed/completed) — feed range enumeration depends on the pk_ranges data stored in this cache
• [Cosmos] ThroughputControl API #3904 — [Cosmos] ThroughputControl API — another SDK-parity feature request from the same author

Reference implementations in other SDKs:

• [Java SDK FeedRange]((learn.microsoft.com/redacted)
• [.NET SDK FeedRange]((learn.microsoft.com/redacted)
• [Python SDK FeedRange]((learn.microsoft.com/redacted)

📐 Suggested API Surface (starting point)

Based on other SDKs, the feed range API in Rust might look like:

/// Represents a logical feed range (maps to a physical partition range).
pub struct FeedRange {
    // opaque range token (e.g., min/max inclusive key range)
}

impl ContainerClient {
    /// Returns all feed ranges for the container.
    pub async fn get_feed_ranges(&self) -> Result(Vec(FeedRange));
}

impl ContainerClient {
    /// Executes a query scoped to a specific feed range.
    pub fn query_items_in_range(T)(&self, query: impl Into(Query), feed_range: &FeedRange, options: Option(QueryOptions)) -> Pager(T);
}

impl ContainerClient {
    /// Reads the change feed for a specific feed range.
    pub fn read_change_feed_in_range(T)(&self, feed_range: &FeedRange, options: Option(ChangeFeedOptions)) -> Pager(T);
}

This follows the existing query_items / read_change_feed patterns already in the SDK.

✅ Suggested Sub-tasks

• Define FeedRange type in azure_data_cosmos (wrapping the physical partition key range token)
• Implement ContainerClient::get_feed_ranges() — fetches partition key ranges from service (or metadata cache) and maps them to FeedRange values
• Add feed-range-scoped query API on ContainerClient (with existing Pager infrastructure)
• Add feed-range-scoped change feed API on ContainerClient
• Ensure FeedRange is serializable/deserializable so users can persist and resume ranges across sessions
• Update CHANGELOG.md under sdk/cosmos/azure_data_cosmos/
• Add integration tests using #[recorded::test] for each new API
• Update README with feed range usage examples

💡 Nudges for the Team

• The metadata cache (from Cosmos: Build a Container Metadata Cache #3083) already stores pk_ranges — get_feed_ranges() can likely be implemented on top of cache.pk_ranges(...) rather than making a direct service call each time.
• Consider whether FeedRange should be opaque (just a token string like other SDKs) vs. exposing the min/max key range directly — the opaque form is more future-proof.
• The driver migration (Cosmos: Switch SDK over to using the driver #3906) may want to land first so feed range APIs can be built on the new transport layer from the start.
• Feed ranges are also useful for read_many_items fan-out — keep that use case in mind when designing the API surface.

Generated by Agentic Triage for issue #3908 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5