Throughput Bucketing: Promote to GA in the .NET SDK (and track parity across all SDKs)

[kundadebdatta]

Summary

Throughput bucketing has been available in the preview package of the .NET SDK since 3.50.0-preview.0 and is still preview-only as of 3.63.0-preview.1. It has had no API-shape changes across roughly fourteen preview releases, which suggests the surface is stable and ready for GA promotion.

This issue tracks (a) promoting the feature to the GA package in the .NET SDK and (b) confirming/driving parity across the other language SDKs.

Current state (.NET)

The entire public surface is gated behind #if PREVIEW:

API	Location
RequestOptions.ThroughputBucket	Microsoft.Azure.Cosmos/src/RequestOptions/RequestOptions.cs (~L128)
CosmosClientOptions.ThroughputBucket	Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs (~L1221)
CosmosClientBuilder.WithThroughputBucket(int)	Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs (~L843)

The internal plumbing is not preview-gated and already ships in GA:

• RequestInvokerHandler.ValidateAndSetThroughputBucket — resolves request-level over client-level precedence and emits the header.
• ClientPipelineBuilder / RequestInvokerHandler — carry requestedClientThroughputBucket through the pipeline.
• DocumentClient — sets HttpConstants.HttpHeaders.ThroughputBucket for the v2-options path.

Because only the public properties are gated, promotion is largely a matter of removing the #if PREVIEW guards and regenerating contracts — there is no new behavior to implement.

Preview contract files confirming the surface: contracts/API_3.50.0-preview.0.txt … contracts/API_3.63.0-preview.1.txt. The feature appears in no GA contract file.

Proposed work (.NET)

• Confirm with the service/PM side that throughput bucketing is GA on the service and supported in all regions and API flavors the SDK targets.
• Confirm behavior on accounts where bucketing is not enabled — today the service returns ThroughputBucketingNotEnabled / InvalidThroughputBuckets. Decide whether GA needs a clearer client-side error or documentation.
• Remove the #if PREVIEW guards from the three public APIs listed above.
• Regenerate the GA API contract (UpdateContracts.ps1) and verify ThroughputBucket now appears in API_<version>.txt.
• Remove the corresponding entries from DotNetPreviewSDKAPIChanges.json.
• Review and finalize XML doc comments for a GA audience (valid bucket range, precedence rules, what happens when the account is not enabled for bucketing).
• Confirm the request-level-vs-client-level precedence and the ArgumentException thrown when ThroughputBucket is set in RequestOptions on certain paths is the intended GA contract, not a preview-era limitation.
• Promote existing preview tests to run against the GA package; add emulator/integration coverage if current coverage is preview-only.
• Add a changelog.md entry under ### Unreleased → Features Added, written in customer-facing language.
• Update public documentation and samples (Microsoft.Azure.Cosmos.Samples/) to reflect GA availability.

Cross-SDK parity

Throughput bucketing is a service-side feature surfaced through the x-ms-cosmos-throughput-bucket request header, so every SDK should expose it consistently. GA'ing only .NET would leave customers with an uneven story across languages.

Please confirm the current status and drive to GA in each:

• Java — azure-sdk-for-java (azure-cosmos)
• Python — azure-sdk-for-python (azure-cosmos)
• JavaScript/TypeScript — azure-sdk-for-js (@azure/cosmos)
• Go — azure-sdk-for-go (azcosmos)
• Spark / Kafka connectors — confirm whether bucketing is exposed as a config option
• Spring Data Cosmos, if applicable

For each SDK, capture: current status (not implemented / preview / GA), the API shape used, and the target release. Where naming differs across SDKs, flag it before GA — the API shape is much harder to change afterwards.

Parity table (to fill in)

SDK	Status	API surface	Target GA release
.NET	Preview since 3.50.0-preview.0	CosmosClientOptions.ThroughputBucket, RequestOptions.ThroughputBucket, CosmosClientBuilder.WithThroughputBucket	TBD
Java	TBD	TBD	TBD
Python	TBD	TBD	TBD
JavaScript	TBD	TBD	TBD
Go	TBD	TBD	TBD

Open questions

1. Is the service-side feature fully GA, or still gated to specific accounts/regions? GA'ing the client API ahead of the service would be a poor experience.
2. Should the valid bucket range be validated client-side at GA, or continue to rely on the service to reject invalid values?
3. Do we need a diagnostics surface showing which bucket a request was attributed to?

Related

• Preview contracts: Microsoft.Azure.Cosmos/contracts/API_3.50.0-preview.0.txt through API_3.63.0-preview.1.txt
• Header constant: HttpConstants.HttpHeaders.ThroughputBucket
• Service errors: RMResources.ThroughputBucketingNotEnabled, RMResources.InvalidThroughputBuckets