Azure/azure-sdk-for-python azure-cosmos_4.16.0

on GitHub

4.16.0 (2026-05-29)

Features Added

• Added preview support for the optional embeddingSource field on entries in vector_embedding_policy.vectorEmbeddings, which allows the service to generate vector embeddings from the specified item paths. Requires the embedding-generation service to be enabled on the account. See 46870
• Added aio extras to the package, allowing users to install async dependencies with pip install azure-cosmos[aio]. See PR 47143

Breaking Changes

• CosmosItemPaged.get_response_headers() and CosmosAsyncItemPaged.get_response_headers() now return a single CaseInsensitiveDict (the latest page) instead of List[CaseInsensitiveDict] (introduced in 4.16.0b1); get_last_response_headers() has been removed. This avoids unbounded memory growth on large queries. Migration: code that previously accessed headers[i]['x-ms-request-charge'] should switch to headers['x-ms-request-charge'] for the latest page, or pass response_hook= to the query method to receive per-page headers as they arrive. See PR 47172.

Bugs Fixed

• Fixed bug where the Content-Length HTTP request header was computed from the character count of the request body instead of its UTF-8 byte count. See PR 47008
• Added an opt-in fallback for invalid UTF-8 in response bodies. Default behavior is unchanged (strict decode). Setting AZURE_COSMOS_CHARSET_DECODER_ERROR_ACTION_ON_MALFORMED_INPUT to REPLACE or IGNORE enables a permissive decode so reads, queries, and change-feed iteration can make progress past corrupt payloads. See PR 47008
• Fixed bug where CosmosClient construction with AAD credentials would crash at startup if the semantic reranking inference endpoint environment variable was not set, even when semantic reranking was not being used. The inference service is now lazily initialized on first use. See PR 46243
• Fixed bug where region names in preferred_locations and excluded_locations (client-level and per-request) were not matched tolerantly for differences in case, whitespace, hyphens, and underscores. See PR 46937
• Fixed a bug in query_items(feed_range=...) where pagination could return incorrect results after a partition split caused the supplied feed range to overlap multiple physical partitions. See PR 47105
• Fixed bug where SELECT VALUE AVG(...) queries spanning multiple physical partitions returned mathematically incorrect merged values from client-side aggregation. These queries now raise ValueError. See PR 47105
• Fixed bug where a ValueError("Ranges overlap") or an AssertionError("code bug: returned overlapping ranges ... is empty") from the partition key range cache could escape to the caller when the /pkranges response contained a transiently inconsistent snapshot (overlap or gap). See PR 47091

Other Changes

• Reduced per-client memory overhead when partition-level circuit breaker (PPCB) is enabled by sharing the partition key range routing map cache across CosmosClient instances connected to the same endpoint, and stripping unused fields from cached partition key ranges using compact PKRange namedtuples. See PR 46297