azure_data_cosmos@0.34.0

0.34.0 (2026-05-29)

Features Added

• CosmosError can capture a stack backtrace on construction. Capture is opt-in (off by default; on when RUST_BACKTRACE is set or when explicit capacities are supplied) and protected against error storms by two configurable per-second limiters on the runtime builder. (#4442)
• Introduced azure_data_cosmos::CosmosError and the crate-wide azure_data_cosmos::Result<T> alias, surfacing typed CosmosStatus (with predicate accessors like is_not_found() / is_throttled() / is_transient()), the originating CosmosResponse, and the operation DiagnosticsContext on every failure. From<CosmosError> for azure_core::Error is provided so callers using ? against azure_core::Error continue to compose. (#4442)
• Added RoutingStrategy::PreferredRegions to allow specifying a fixed region preference order for failover, hedging, and retry. (#4485)
• Standardized every client-method options type with a public operation: OperationOptions field and with_operation_options(OperationOptions) -> Self setter, so any per-request OperationOptions setting can be configured via any options type. The following options types previously had no way to attach OperationOptions and now do: ReadContainerOptions, ReadDatabaseOptions, ReplaceContainerOptions, CreateContainerOptions, CreateDatabaseOptions, DeleteContainerOptions, DeleteDatabaseOptions, QueryContainersOptions, QueryDatabasesOptions, ThroughputOptions, ReadFeedRangesOptions. For CreateContainerOptions / CreateDatabaseOptions / ReplaceContainerOptions, the SDK still forces content_response_on_write = Enabled on the resolved options because control-plane mutations require the response body. ReadFeedRangesOptions::operation is currently inert (the underlying routing-map cache does not go through the operation pipeline) but is added for shape consistency with the other options types. (#4447)
• Added new() constructors and with_x consuming setters to multi-required-field model types so callers can build them declaratively without struct-literal syntax (which is now blocked by #[non_exhaustive]): VectorEmbedding::new(path, data_type, dimensions, distance_function) + with_path / with_data_type / with_dimensions / with_distance_function; ConflictResolutionPolicy::new(mode) + with_resolution_path / with_resolution_procedure; SpatialIndex::new(path) + with_type (singular pusher onto types); CompositeIndexProperty::new(path, order) + with_path / with_order; VectorIndex::new(path, index_type) + with_path / with_index_type. These types do not implement Default — their constructors require values that have no meaningful default. (#4447)
• Derived Default on VectorEmbeddingPolicy, UniqueKeyPolicy, UniqueKey, PropertyPath, and CompositeIndex, and added singular with_x pushers / setters: VectorEmbeddingPolicy::with_embedding, UniqueKeyPolicy::with_unique_key, UniqueKey::with_path, PropertyPath::with_path, and CompositeIndex::with_property. This matches the existing IndexingPolicy::with_included_path style and lets callers build these policies declaratively without constructing intermediate Vecs. (#4447)
• Added QueryFeedPage::as_feed_page() returning &FeedPage<T>, so a query page can be passed to APIs that accept the more general FeedPage type. Query-specific metadata (index/query metrics) remains accessible on the QueryFeedPage itself. (#4447)
• Added QueryOptions::with_populate_index_metrics(bool), with_populate_query_metrics(bool), and with_max_item_count(MaxItemCountHint) setters. These replace the previous pattern of passing raw x-ms-cosmos-populateindexmetrics, x-ms-documentdb-populatequerymetrics, and x-ms-max-item-count values through OperationOptions::with_custom_headers for query execution. max_item_count takes the new MaxItemCountHint enum with ServerDecides and Limit(NonZeroU32) variants, so callers don't have to traffic in the -1 wire sentinel directly. (#4401)
• Added ContainerClient::patch_item() for applying JSON-Patch-style mutations to a single item. Supports add/set/replace/remove/increment/move ops via the new PatchInstructions/PatchOperation/CosmosNumber types. Added PatchItemOptions for per-request configuration (max_attempts, session_token, etc.). PatchItemOptions intentionally does not expose a Precondition or SQL filter predicate — the driver-side PATCH handler owns the internal If-Match end-to-end, and predicate evaluation is out of scope for this preview. The method's rustdoc documents the non-idempotent-under-transport-failure caveat. (#4386)
• Support for simple cross-partition queries with SELECT projections and WHERE filters. Cross-partition queries are now done through fan-out in the client, and provide a client-generated continuation token that can be used to resume the query. See ContainerClient::query_items() and FeedScope for details. (#4440)
• Added QueryOptions::continuation_token and QueryOptions::with_continuation_token(...) for resuming queries from a continuation token. (#4440)
• Added a new FeedOptions type that wraps the paging knobs (max_item_count, continuation_token) common to feed-style operations, so future feed APIs (change feed, read-feed, etc.) can adopt the same shape without redeclaring fields. QueryOptions now embeds it as a pub feed: FeedOptions field with a with_feed_options(FeedOptions) setter. The existing QueryOptions::with_max_item_count and QueryOptions::with_continuation_token setters are retained as convenience functions that mutate the embedded feed (they're expected to be used commonly enough to warrant the shortcut). (#4447)

Breaking Changes

• All fallible public APIs now return azure_data_cosmos::Result<T> (= Result<T, CosmosError>) instead of azure_core::Result<T>, and the error type was renamed Error → CosmosError (with CosmosErrorBuilder for construction). Categorization moved from a Kind enum to predicates on CosmosStatus (is_not_found(), is_throttled(), is_transient(), …); the underlying azure_core::Error is still reachable via std::error::Error::source(). (#4442)
• Moved QueryOptions::max_item_count and QueryOptions::continuation_token into the new QueryOptions::feed: FeedOptions field. Callers that read or assign these fields directly should switch to options.feed.max_item_count / options.feed.continuation_token. The with_max_item_count / with_continuation_token convenience setters on QueryOptions continue to work unchanged. (#4447)
• ThroughputProperties is now #[non_exhaustive] and no longer derives Default. The Default impl produced a meaningless wire payload (no manual throughput and no autoscale settings, which would send an empty offer body). Callers should use ThroughputProperties::manual(throughput) or ThroughputProperties::autoscale(starting_maximum_throughput, increment_percent) instead. (#4447)
• Marked the following public model enums and response wrappers as #[non_exhaustive] to allow future variants/fields to be added without further breaking changes: VectorDataType, VectorDistanceFunction, ConflictResolutionMode, IndexingMode, SpatialType, CompositeIndexOrder, VectorIndexType, BatchResponse, ItemResponse, ResourceResponse<T>, ResponseBody, ResponseHeaders, PartitionKeyVersion and CosmosStatus. Callers must use .. wildcard arms in matches over these enums and cannot construct these structs via struct-literal syntax (the SDK already provides constructors / setters for the constructable types). (#4447)
• CosmosClientBuilder::build now takes AccountReference directly instead of impl Into<AccountReference>. Callers should construct an AccountReference explicitly via AccountReference::with_credential or AccountReference::with_authentication_key and pass it in. (#4447)
• Replaced EffectivePartitionKey::min() / EffectivePartitionKey::max() with associated constants EffectivePartitionKey::MIN / EffectivePartitionKey::MAX. The inner storage also changed from String to Cow<'static, str> so the constants can borrow static strings without allocating. Callers should rewrite EffectivePartitionKey::min() as EffectivePartitionKey::MIN.clone() (or just &EffectivePartitionKey::MIN for comparisons). (#4447)
• Removed PartitionKeyValue::undefined() (use the existing PartitionKeyValue::UNDEFINED associated constant instead) and replaced the test-only PartitionKeyValue::infinity() constructor with a publicly-available PartitionKeyValue::INFINITY associated constant. (#4447)
• Removed FeedRange::can_merge() and FeedRange::merge_with(). These are SDK-internal helpers used only by the session-token coalescing pipeline and are now implemented internally. (#4447)
• Renamed CosmosAccountEndpoint → AccountEndpoint and CosmosAccountReference → AccountReference. The Cosmos prefix is implied by the containing azure_data_cosmos crate. (#4447)
• Renamed CosmosAccountReference::with_master_key() to with_authentication_key(). (#4447)
• Renamed FeedPageIterator → QueryPageIterator and FeedItemIterator → QueryItemIterator. These iterators are only produced by query APIs today; the Feed* names are reserved for future non-query feed APIs. (#4447)
• Removed the request_charge() and session_token() convenience accessors from FeedPage and QueryFeedPage. Use page.headers().request_charge() and page.headers().session_token() instead — the parsed ResponseHeaders already exposes these values and provides full typed access to every other response header. (#4447)
• Tightened AccountReference constructors. with_credential now accepts impl Into<AccountEndpoint> instead of a concrete AccountEndpoint. The former with_master_key is renamed to with_authentication_key and now takes AccountEndpoint (which has FromStr and From<Url> impls) and impl Into<Secret> for the key. The two From<(AccountEndpoint, _)> / From<(Url, _)> tuple conversions are removed; construct a AccountReference via the named constructors instead. (#4447)
• Removed azure_data_cosmos::ConnectionString from the public API. The type was a parsing helper not consumed by any public SDK API. Users who still need support for Connection String parsing can parse the connection string themselves and construct an AccountReference via the named constructors. (#4447)
• Refactored the response surface to be SDK-owned. ItemResponse drops its type parameter (use response.into_model::<MyItem>() or response.into_body().into_single::<MyItem>()); ResourceResponse<T> keeps its parameter so .into_model()? still works without a turbofish. status() now returns CosmosStatus, headers() returns &ResponseHeaders (typed accessors only — etag(), request_charge(), session_token(), continuation(), activity_id(), substatus(), index_metrics(), query_metrics(), offer_replace_pending(), server_duration_ms(), lsn(), item_lsn(), item_count(), …), and into_body() returns the SDK-owned ResponseBody enum (NoPayload / Bytes / Items) with single(), items(), into_single::<T>(), into_items::<T>(), and is_empty() helpers. FeedPage::headers() / QueryFeedPage::headers() now return &ResponseHeaders instead of &azure_core::http::headers::Headers. The ItemResponse::etag() convenience accessor is removed (use response.headers().etag()). CosmosStatus is re-exported from the driver and implements PartialEq<StatusCode> and From<CosmosStatus> for StatusCode/u16, so existing comparisons keep working. (#4401)

Other Changes

• Removed the SDK-side FaultInjectionClientBuilder, parallel duplicate types (FaultInjectionRule, FaultInjectionCondition, FaultInjectionResult, CustomResponse, the matching builders, FaultInjectionErrorType, FaultOperationType), and the SDK-side FaultClient HTTP wrapper from azure_data_cosmos::fault_injection. The module is now a pure re-export of the driver's fault-injection types — fault-injection rules flow directly to the driver runtime and are evaluated by the driver's transport-layer fault-injection client. CosmosClientBuilder::with_fault_injection now accepts the driver's Vec<Arc<FaultInjectionRule>> directly instead of FaultInjectionClientBuilder. Callers should construct rules via the re-exported FaultInjectionRuleBuilder and pass the vector.(#4426)
• Removed the request_url() accessor (gated on the fault_injection feature) from ItemResponse/ResourceResponse/BatchResponse. Operations never populated it, so it always returned None in current usage.
• CosmosClientBuilder::with_user_agent_suffix (and CosmosClientOptions::with_user_agent_suffix) now take UserAgentSuffix instead of impl Into<String>. Callers passing a &str or String must construct the value explicitly via UserAgentSuffix::new (panics on invalid input) or UserAgentSuffix::try_new (returns Option). Validation rules (max 25 characters, HTTP-header-safe) are now enforced at the construction site instead of being applied silently inside the builder. (#4368)
• Changed how continuation tokens are returned. Instead of a continuation() accessor on QueryFeedPage and FeedPage, continuation tokens are now returned as a Option<ContinuationToken> from the FeedPageIterator::to_continuation_token(&self) method. Generating a continuation token for a cross-partition query requires computation, so this change makes it explicit that callers must opt in to generating a continuation token and allows them to choose when to pay the cost of generation. (#4440)
• ContainerClient::query_items() now takes a FeedScope (FeedScope::partition(...), FeedScope::range(...), or FeedScope::full_container()) instead of a partition key where () represented cross-partition queries. (#4440)
• Replaced CosmosDiagnostics with DiagnosticsContext (a re-export of azure_data_cosmos_driver::diagnostics::DiagnosticsContext). All response types now return Arc<DiagnosticsContext> from diagnostics() (the returned Arc derefs transparently to DiagnosticsContext for read-only inspection, and can be retained alongside a consumed response body). The previous activity_id() -> Option<&str> and server_duration_ms() -> Option<f64> accessors on CosmosDiagnostics are replaced by DiagnosticsContext::activity_id() -> &ActivityId and per-request server timing via DiagnosticsContext::requests()[i].server_duration_ms(). (#4376)
• Removed azure_data_cosmos::constants::SubStatusCode and its new/value/from_header_value/From/Display/Debug API. The SDK no longer maintains a parallel sub-status-code type.
• The User-Agent header on every outgoing Cosmos DB request now identifies the wrapping SDK in addition to the driver. The new format is azsdk-rust-cosmos/<sdk-version> azsdk-rust-cosmos-driver/<driver-version> <os>/<arch> rustc/<ver> [suffix], where <sdk-version> is this crate's version. This is wired automatically via the new CosmosDriverRuntimeBuilder::with_wrapping_sdk_identifier API in the driver, and lets telemetry distinguish callers using azure_data_cosmos from callers driving azure_data_cosmos_driver directly. No API surface in azure_data_cosmos changes. (#4465)
• The azure_data_cosmos::constants module is no longer public. It only contained internal HTTP-header-name constants used by the SDK's own pipeline plumbing; nothing from it was intended for consumer use. The one previously-exposed public item (SubStatusCode) is re-exported from the crate root — see the bullet above. (#4447)

Bugs Fixed

• Fixed CosmosClientBuilder::with_user_agent_suffix not propagating the suffix to data-plane requests. The suffix was only applied to the SDK's account-metadata pipeline; requests issued through the driver transport pipeline (the vast majority of operations) had a User-Agent header without the configured suffix. The suffix is now forwarded to CosmosDriverRuntimeBuilder so it appears on every outgoing request. (#4368)

Other Changes

• Per-partition automatic failover (PPAF) and per-partition circuit breaker (PPCB) are now driven by the azure_data_cosmos_driver crate, replacing the SDK's prior implementation. Behavior is unchanged from a configuration standpoint — the existing AZURE_COSMOS_PER_PARTITION_CIRCUIT_BREAKER_ENABLED environment variable continues to work — but routing is now per-(partition_key_range_id, region) instead of per-region. Driver-level changes are described in azure_data_cosmos_driver 0.3.0. (#4156)