Azure Cosmos DB Python SDK for SQL API: Release notes and resources
APPLIES TO: SQL API
|API documentation||Python API reference documentation|
|SDK installation instructions||Python SDK installation instructions|
|Get started||Get started with the Python SDK|
|Current supported platform||Python 2.7 and Python 3.5.3+|
- Added deprecation warning for "lazy" indexing mode. The backend no longer allows creating containers with this mode and will set them to consistent instead.
- Added the ability to set the analytical storage TTL when creating a new container.
- Fixed support for dicts as inputs for get_client APIs.
- Fixed Python 2/3 compatibility in query iterators.
- Fixed type hint error (Issue #12570).
- Fixed bug where options headers were not added to upsert_item function. Issue #11791 - thank you @aalapatirvbd.
- Fixed error raised when a non string ID is used in an item. It now raises TypeError rather than AttributeError (Issue #11793).
- Stable release.
- Added HttpLoggingPolicy to pipeline to enable passing in a custom logger for request and response headers.
- Fixed bug in synchronized_request for media APIs.
- Removed MediaReadMode and MediaRequestTimeout from ConnectionPolicy as media requests are not supported.
azure.cosmos.errors module deprecated and replaced by azure.cosmos.exceptions
The access condition parameters (
if_none_match) have been deprecated in favor of separate
Fixed bug in routing map provider.
Added query Distinct, Offset, and Limit support.
Default document query execution context now used for
- ChangeFeed queries
- single partition queries (partitionkey, partitionKeyRangeId is present in options)
- Non-document queries
Errors out for aggregates on multiple partitions, with enable cross partition query set to true, but no "value" keyword present
Hits query plan endpoint for other scenarios to fetch query plan
__repr__support for Cosmos entity objects.
Added support for a
timeoutkeyword argument to all operations to specify an absolute timeout in seconds within which the operation must be completed. If the timeout value is exceeded, a
azure.cosmos.errors.CosmosClientTimeoutErrorwill be raised.
Added a new
ConnectionRetryPolicyto manage retry behavior during HTTP connection errors.
Added new constructor and per-operation configuration keyword arguments:
retry_total- Maximum retry attempts.
retry_backoff_max- Maximum retry wait time in seconds.
retry_fixed_interval- Fixed retry interval in milliseconds.
retry_read- Maximum number of sockets read retry attempts.
retry_connect- Maximum number of connection error retry attempts.
retry_status- Maximum number of retry attempts on error status codes.
retry_on_status_codes- A list of specific status codes to retry on.
retry_backoff_factor- Factor to calculate wait time between retry attempts.
create_container_if_not_existsfunctionalities to CosmosClient and Database respectively.
- Version 4.0.0b2 is the second iteration in our efforts to build a client library that suits the Python language best practices.
The client connection has been adapted to consume the HTTP pipeline defined in
Interactive objects have now been renamed as proxies. This includes:
The constructor of
CosmosClienthas been updated:
authparameter has been renamed to
credentialand will now take an authentication type directly. This means the primary key value, a dictionary of resource tokens, or a list of permissions can be passed in. However the old dictionary format is still supported.
connection_policyparameter has been made a keyword only parameter, and while it is still supported, each of the individual attributes of the policy can now be passed in as explicit keyword arguments:
A new constructor has been added to
CosmosClientto enable creation via a connection string retrieved from the Azure portal.
read_alloperations have been renamed to
All operations that take
feed_optionsparameters, these have been moved to keyword only parameters. In addition, while these options dictionaries are still supported, each of the individual options within the dictionary are now supported as explicit keyword arguments.
The error hierarchy is now inherited from
HTTPFailurehas been renamed to
JSONParseFailurehas been removed and replaced by
- Added additional errors for specific response codes:
CosmosResourceNotFoundErrorfor status 404
CosmosResourceExistsErrorfor status 409
CosmosAccessConditionFailedErrorfor status 412
CosmosClientcan now be run in a context manager to handle closing the client connection.
Iterable responses (for example, query responses and list responses) are now of type
azure.core.paging.ItemPaged. The method
fetch_next_blockhas been replaced by a secondary iterator, accessed by the
Version 4.0.0b1 is the first preview of our efforts to create a user-friendly client library that suits the Python language best practices. For more information about this, and preview releases of other Azure SDK libraries, please visit https://aka.ms/azure-sdk-preview1-python.
Breaking changes: New API design
Operations are now scoped to a particular client:
CosmosClient: This client handles account-level operations. This includes managing service properties and listing the databases within an account.
Database: This client handles database-level operations. This includes creating and deleting containers, users, and stored procedures. It can be accessed from a cosmosClient` instance by name.
Container: This client handles operations for a particular container. This includes querying and inserting items and managing properties.
User: This client handles operations for a particular user. This includes adding and deleting permissions and managing user properties.
These clients can be accessed by navigating down the client hierarchy using the
get_<child>_clientmethod. For full details on the new API, please see the reference documentation.
Clients are accessed by name rather than by ID. No need to concatenate strings to create links.
No more need to import types and methods from individual modules. The public API surface area is available directly in the
Individual request properties can be provided as keyword arguments rather than constructing a separate
- Added Support for MultiPolygon Datatype
- Bug Fix in Session Read Retry Policy
- Bug Fix for Incorrect padding issues while decoding base 64 strings
- Bug fix in LocationCache
- Bug fix endpoint retry logic
- Fixed documentation
- Multi-regions write support added
- Naming changes
- DocumentClient to CosmosClient
- Collection to Container
- Document to Item
- Package name updated to "azure-cosmos"
- Namespace updated to "azure.cosmos"
- Added support for proxy
- Added support for reading change feed
- Added support for collection quota headers
- Bugfix for large session tokens issue
- Bugfix for ReadMedia API
- Bugfix in partition key range cache
- Added support for default retries on connection issues.
- Updated documentation to reference Azure Cosmos DB instead of Azure DocumentDB.
- This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from https://aka.ms/cosmosdb-emulator.
- bugfix for aggregate dict
- bugfix for trimming slashes in the resource link
- tests for unicode encoding
- Added support for Request Unit per Minute (RU/m) feature.
- Added support for a new consistency level called ConsistentPrefix.
- Added support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
- Added an option for disabling SSL verification when running against DocumentDB Emulator.
- Removed the restriction of dependent requests module to be exactly 2.10.0.
- Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.
- Added support for enabling script logging during stored procedure execution.
- REST API version bumped to '2017-01-19' with this release.
- Made editorial changes to documentation comments.
- Added support for Python 3.5.
- Added support for connection pooling using the requests module.
- Added support for session consistency.
- Added support for TOP/ORDERBY queries for partitioned collections.
Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.) By default, DocumentDB retries nine times for each request when error code 429 is encountered, honoring the retryAfter time in the response header. A fixed retry interval time can now be set as part of the RetryOptions property on the ConnectionPolicy object if you want to ignore the retryAfter time returned by server between the retries. DocumentDB now waits for a maximum of 30 seconds for each request that is being throttled (irrespective of retry count) and returns the response with error code 429. This time can also be overridden in the RetryOptions property on ConnectionPolicy object.
DocumentDB now returns x-ms-throttle-retry-count and x-ms-throttle-retry-wait-time-ms as the response headers in every request to denote the throttle retry count and the cumulative time the request waited between the retries.
Removed the RetryPolicy class and the corresponding property (retry_policy) exposed on the document_client class and instead introduced a RetryOptions class exposing the RetryOptions property on ConnectionPolicy class that can be used to override some of the default retry options.
- Added the support for geo-replicated database accounts.
- Test fixes to move the global host and masterKey into the individual test classes.
- Added the support for Time To Live(TTL) feature for documents.
- Bug fixes related to server-side partitioning to allow special characters in partition key path.
- Added the support for server-side partitioned collections feature.
- Added Client-side sharding framework to the SDK. Implemented HashPartionResolver and RangePartitionResolver classes.
- Implement Upsert. New UpsertXXX methods added to support Upsert feature.
- Implement ID-Based Routing. No public API changes, all changes internal.
- Release skipped to bring version number in alignment with other SDKs
- Supports GeoSpatial index.
- Validates ID property for all resources. Ids for resources cannot contain
?, /, #, \\characters or end with a space.
- Adds new header "index transformation progress" to ResourceResponse.
- Implements V2 indexing policy
- Supports proxy connection
Release & retirement dates
Microsoft provides notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version. New features and functionality and optimizations are only added to the current SDK, as such it is recommended that you always upgrade to the latest SDK version as early as possible.
After 31 August 2022, Azure Cosmos DB will no longer make bug fixes or provide support to versions 1.x and 2.x of the Azure Cosmos DB Python SDK for SQL API. If you prefer not to upgrade, requests sent from version 1.x and 2.x of the SDK will continue to be served by the Azure Cosmos DB service.
|Version||Release Date||Retirement Date|
|4.0.0||May 20, 2020||---|
|3.0.2||Nov 15, 2018||---|
|3.0.1||Oct 04, 2018||---|
|2.3.3||Sept 08, 2018||August 31, 2022|
|2.3.2||May 08, 2018||August 31, 2022|
|2.3.1||December 21, 2017||August 31, 2022|
|2.3.0||November 10, 2017||August 31, 2022|
|2.2.1||Sep 29, 2017||August 31, 2022|
|2.2.0||May 10, 2017||August 31, 2022|
|2.1.0||May 01, 2017||August 31, 2022|
|2.0.1||October 30, 2016||August 31, 2022|
|2.0.0||September 29, 2016||August 31, 2022|
|1.9.0||July 07, 2016||August 31, 2022|
|1.8.0||June 14, 2016||August 31, 2022|
|1.7.0||April 26, 2016||August 31, 2022|
|1.6.1||April 08, 2016||August 31, 2022|
|1.6.0||March 29, 2016||August 31, 2022|
|1.5.0||January 03, 2016||August 31, 2022|
|1.4.2||October 06, 2015||August 31, 2022|
|1.4.1||October 06, 2015||August 31, 2022|
|1.2.0||August 06, 2015||August 31, 2022|
|1.1.0||July 09, 2015||August 31, 2022|
|1.0.1||May 25, 2015||August 31, 2022|
|1.0.0||April 07, 2015||August 31, 2022|
|0.9.4-prelease||January 14, 2015||February 29, 2016|
|0.9.3-prelease||December 09, 2014||February 29, 2016|
|0.9.2-prelease||November 25, 2014||February 29, 2016|
|0.9.1-prelease||September 23, 2014||February 29, 2016|
|0.9.0-prelease||August 21, 2014||February 29, 2016|
How will I be notified of the retiring SDK?
Microsoft will provide 12 month's advance notice before the end of support of the retiring SDK to facilitate a smooth transition to a supported SDK. We'll notify you through various communication channels: the Azure portal, Azure updates, and direct communication to assigned service administrators.
Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?
Yes, you'll be able to author, deploy, and modify applications by using the to-be-retired Azure Cosmos DB SDK during the 12-month notice period. We recommend that you migrate to a newer supported version of the Azure Cosmos DB SDK during the 12-month notice period, as appropriate.
After the retirement date, what happens to applications that use the unsupported Azure Cosmos DB SDK?
After the retirement date, Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions. If you prefer not to upgrade, requests sent from the retired versions of the SDK will continue to be served by the Azure Cosmos DB service.
Which SDK versions will have the latest features and updates?
New features and updates will be added only to the latest minor version of the latest supported major SDK version. We recommend that you always use the latest version to take advantage of new features, performance improvements, and bug fixes. If you're using an old, non-retired version of the SDK, your requests to Azure Cosmos DB will still function, but you won't have access to any new capabilities.
What should I do if I can't update my application before a cutoff date?
We recommend that you upgrade to the latest SDK as early as possible. After an SDK is tagged for retirement, you'll have 12 months to update your application. If you're not able to update by the retirement date, requests sent from the retired versions of the SDK will continue to be served by Azure Cosmos DB, so your running applications will continue to function. But Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions.
If you have a support plan and require technical support, contact us by filing a support ticket.
To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.