NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #994 most downloaded on PyPI
Microsoft Azure Cosmos Client Library for Python
Last release 18 days ago
16 Sep 2026
Ships fairly regularly
a new release about every 3 weeks
Most releases are documented
notes for 28 of 35 stable releases
1 version withdrawn
withdrawn after publishing
8 years old
77 releases · first in 2018
Fixed unnecessary full routing-map refreshes in sync and async clients when incremental partition metadata updates reference ancestors that have alrea
One column per quarter.
Added the enable_compact_utf8_item_writes client option. Set it to True to reduce item write request sizes by serializing valid Unicode as compact UTF
enable_compact_utf8_item_writes client option. Set it to True to reduce item write request sizes byapplication/json-patch+jsonFixed regression with handling of v1 legacy containers when passing {} as a partition key. {} and NonePartitionKeyValue now both resolve to the Undefi
{} as a partition key. {} and NonePartitionKeyValue now both resolve to the Undefined effective partition key. See PR 48422TypeError on system key (migrated) containers, where a missing partition key value resolves to _Empty instead of Undefined. It now maps to the minimum effective partition key. See PR 48422Fixed regression introduced in 4.16.0 on 47105 for complete-partition-key queries scanning documents instead of using partition-key routing, which cau
Added GlobalSecondaryIndexDefinition class and global_secondary_index keyword to create_container, create_container_if_not_exists, and replace_contain
GlobalSecondaryIndexDefinition class and global_secondary_index keyword to create_container, create_container_if_not_exists, and replace_container methods for creating Global Secondary Index (GSI) containers. See PR 47468.KeyError: 'version' in SessionContainer.get_session_token (sync and async) when the container's partitionKey definition returned by the service does not include the optional version field. The error was silently swallowed by a broad except, causing the client to send no x-ms-session-token header on subsequent reads. Against the Dedicated Gateway, this turned every Session-consistency read into an Integrated Cache miss. partitionKey.version is now treated as optional and defaults to 1, matching how PartitionKey handles a missing version. See PR 47143Fixed a bug in the sync and async /pkranges change-feed refresh where some containers could fail to build a complete routing map. See PR 47245.
/pkranges change-feed refresh where some containers could fail to build a complete routing map. See PR 47245.Added preview support for the optional embeddingSource field on entries in vector_embedding_policy.vectorEmbeddings, which allows the service to gener
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 46870aio extras to the package, allowing users to install async dependencies with pip install azure-cosmos[aio]. See PR 47143CosmosItemPaged.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.Content-Length HTTP request header was computed from the character count of the request body instead of its UTF-8 byte count. See PR 47008AZURE_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 47008CosmosClient 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 46243preferred_locations and excluded_locations (client-level and per-request) were not matched tolerantly for differences in case, whitespace, hyphens, and underscores. See PR 46937query_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 47105SELECT VALUE AVG(...) queries spanning multiple physical partitions returned mathematically incorrect merged values from client-side aggregation. These queries now raise ValueError. See PR 47105ValueError("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 47091Fixed bug where container-focused requests using name-based addressing did not consistently populate the x-ms-cosmos-intended-collection-rid header. S
x-ms-cosmos-intended-collection-rid header. See PR 44080Added support for Query Advisor feature - See PR 45331
get_response_headers() and get_last_response_headers() methods to the CosmosItemPaged and CosmosAsyncItemPaged objects returned by query_items(), allowing access to response headers from query operations. See PR 44593full_text_score_scope parameter to query_items() for controlling BM25 statistics scope in hybrid search queries. Supports "Local" and "Global" (default) scopes. See 45686user_agent_overwrite kwarg was not cleaned up properly, causing TypeError crash on sync client construction. See PR 45653read_timeout configuration was not being automatically applied to all queries. See PR 44472GA support of Per Partition Automatic Failover and AvailabilityStrategy features.
force_refresh_on_startup was set to None, which could surface as AttributeError: 'NoneType' object has no attribute '_WritableLocations' during region discovery when database_account was None. See PR 44987availability_strategy_config introduced in 4.15.0b1 to availability_strategy for both sync and async clients. See PR 45086.availability_strategy needs to be set to False in order to disable availability strategy for that request, as opposed to setting it to None. See PR 45141.Fixed bug where sdk was not properly retrying requests in some edge cases after partition splits.See PR 44425
Added support for Per Partition Automatic Failover. To enable this feature, you must follow the guide here. See PR 41588.
query_items would cause unexpected errors. See PR 44098user_agent in headers. See PR 44189Fixed SELECT VALUE aggregation classification across partitions: booleans are no longer treated as numeric aggregates, non-aggregate numeric projectio
SELECT VALUE aggregation classification across partitions: booleans are no longer treated as numeric aggregates, non-aggregate numeric projections are no longer merged, and MIN/MAX detection is now correct. See PR 46692query_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 46692Fixed async client crash (AttributeError: 'NoneType' object has no attribute '_WritableLocations') during region discovery when database_account was N
AttributeError: 'NoneType' object has no attribute '_WritableLocations') during region discovery when database_account was None. See PR 44939Fixed bug where sdk was encountering a timeout issue caused by infinite recursion during the 410 (Gone) error.See PR 44659
Fixed bug where sdk was not properly retrying requests in some edge cases after partition splits.See PR 44425
Fixed bug where client timeout/read_timeout values were not properly enforced. See PR 42652.
Added merge support. See PR 42924.
parameters=None in query_items. See PR 43681Fixed bug where queries using feed_range and continuation options would not work as expected. See PR 43700.
feed_range and continuation options would not work as expected. See PR 43700.This version and all future versions will require Python 3.9+.
This version and all future versions will require Python 3.9+.
return_properties parameter. See PR 41742retry_write from bool to int to match other retryable options. See PR 43341.Fixed bug where client provided session token was not respected when client-side session management was disabled. See PR 42965
Added read_items API to provide an efficient method for retrieving multiple items in a single request. See PR 42167.
excluded_locations was not being honored for some metadata calls. See PR 42266.partition_key set to None was not properly handled for some operations. See PR 42747Added feed range support in query_items. See PR 41722.
query_items. See PR 41722.Adds cross region retries when no preferred locations are set. This is only a breaking change for customers using bounded staleness consistency. See P…
ThroughputProperties would not work. See PR 41564Fixed issue where key error would occur when getting properties from a container using legacy hash v1 as they may not always contain version property
Added ability to set a user agent suffix at the client level. See PR 40904
excluded_locations on metadata calls, such as getting container properties. See PR 40905AZURE_COSMOS_ENABLE_CIRCUIT_BREAKER. See PR 40302.Added ability to use weighted RRF (Reciprocal Rank Fusion) for Hybrid full text search queries. See PR 40899.
Added ability to set throughput_bucket header at the client level and for all requests. See PR 40340.
throughput_bucket header at the client level and for all requests. See PR 40340.excluded_locations on client level and document API request level. See PR 40298response_hook not getting called for aggregate queries. See PR 40696.Fixed bug introduced in 4.10.0b3 with explicitly setting etag keyword argument as None causing exceptions. See PR 40282.
etag keyword argument as None causing exceptions. See PR 40282.Fixed too many health checks happening when skipping the recommended client startup. See PR 40203.
Fixed bug preventing health check in some scenarios. See PR 39647.
Added ability to replace computed_properties through replace_container method. See PR 39543.
Improved retry logic for read requests to failover on other regions in case of timeouts and any error codes >= 500. See PR 39596.
Improved retry logic by retrying alternative endpoint for writes within a region before performing a cross region retry. See PR 39390.
Added new cross-regional retry logic for ServiceRequestError and ServiceResponseError exceptions. See PR 39396.
ServiceRequestError and ServiceResponseError exceptions. See PR 39396.KeyError being returned by location cache when most preferred location is not present in cached regions. See PR 39396.CosmosClient initialization. See PR 39396.Added change feed mode support in query_items_change_feed. See PR 38105.
Added full text policy and full text indexing policy. See PR 37891.
This version and all future versions will support Python 3.13.
This version and all future versions will support Python 3.13.
query_items_change_feed. See PR 37687.CosmosDict and CosmosList response types.
Responses will still be able to be used directly as previously, but will now have access to their response headers without need for a response hook. See PR 35791.
For more information on this, see our README section here.Adds vector embedding policy and vector indexing policy. See PR 34882.
Nothing published for this version
GA release of hierarchical partitioning, index metrics and transactional batch.
create_container_if_not_exists() methods. See PR 34286.Fixed bug with async lock not properly releasing on async global endpoint manager. see PR 34579.
This version and all future versions will require Python 3.8+.
This version and all future versions will require Python 3.8+.
Added support for capturing Index Metrics in query operations. See PR 33034.
Added support for Transactional Batch. See PR 32508.
Marked the outdated diagnostics.py file for deprecation since we now recommend the use of our CosmosHttpLoggingPolicy for diagnostics. For more on the…
offer_throughput option in the async client's create_database_if_not_exists method, which was previously misspelled as offerThroughput.
See PR 32076.diagnostics.py file for deprecation since we now recommend the use of our CosmosHttpLoggingPolicy for diagnostics.
For more on the CosmosHttpLoggingPolicy see our README.Fixed bug when query with DISTINCT + OFFSET/LIMIT operators returns unexpected result. See PR 31925.
Added support for continuation tokens for streamable cross partition queries. See PR 31189.
create_database_if_not_exists method not working when passing offer_throughput as an option. See PR 31478.response_continuation_token_limit_in_kb to continuation_token_limit for GA. See PR 31532.Added ability to limit continuation token size when querying for items. See PR 30731
GA release of Patch API and Delete All Items By Partition Key
Added conditional patching for Patch operations. See PR 30455.
Added preview delete all items by partition key functionality. See PR 29186. For more information on Partition Key Delete, please see Azure Cosmos DB
create_container_if_not_exists() of async database client for unexpected kwargs being passed into read() method used internally. See PR 29136.query_items() of our async container class, where partition key and cross partition headers would both be set when using partition keys. See PR 29366.six package within the SDK.Added correlated_activity_id for query operations.
correlated_activity_id for query operations.GA release of integrated cache functionality. For more information on integrated cache please see Azure Cosmos DB integrated cache.
CosmosHttpLoggingPolicy to replace HttpLoggingPolicy for logging HTTP sessions.container.read() method.validate_cache_staleness_value() method to allow max_integrated_cache_staleness to be an integer greater than or equal to 0.__aiter__() method by removing the async keyword.Deprecated offer-named methods in favor of their new throughput-named counterparts (read_offer -> get_throughput).
upsert_items() method when no 'id' value was present in document body.
Method call will now require an 'id' field to be present in the document body.read_offer -> get_throughput).connection_retry_policy and retry_options options in the sync client.populate_query_metrics options.Added support for AAD authentication for the async client.
_set_partition_key return typehint in async client.>The default Session consistency bugfix will impact customers whose database accounts have a Bounded Staleness or Strong
[WARNING] The default
Sessionconsistency bugfix will impact customers whose database accounts have aBounded StalenessorStrongconsistency level, and were previously not sendingSessionas a consistency_level parameter when initializing their clients. Default consistency level for the sync and async clients is no longer "Session" and will instead be set to the consistency level of the user's cosmos account setting on initialization if not passed during client initialization. Please see Consistency Levels in Azure Cosmos DB for more details on consistency levels, or the README section on this change here.
max_integrated_cache_staleness_in_ms parameter to read item and query items APIs in order
to make use of the preview CosmosDB integrated cache functionality See PR #22946.
Please see Azure Cosmos DB integrated cache for more details.This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported. We will also be removing support for Python 3.6 and
This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported. We will also be removing support for Python 3.6 and will only support Python 3.7+ starting December 2022.
Added language native async i/o client.
Fixed bug where continuation token is not honored when query_iterable is used to get results by page. Issue #13265.
Bug fixes
New features
Your coding agent can read these notes before it upgrades. Set up the MCP server →