Azure Cosmos DB Python SDK for SQL API: Release notes and resources

Download SDK PyPI
API documentation Python API reference documentation
SDK installation instructions Python SDK installation instructions
Contribute to SDK GitHub
Get started Get started with the Python SDK
Current supported platform Python 2.7 and Python 3.5

Release notes


  • 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


  • Support for multi-region writes.
  • Namespace changed to azure.cosmos.
  • Collection and document concepts renamed to container and item, document_client renamed to cosmos_client.


  • 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.



  • Bug fix for aggregate dictionary.
  • Bug fix for trimming slashes in the resource link.
  • Added tests for Unicode encoding.


  • 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 Cosmos DB 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 a 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, Azure Cosmos DB 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. Azure Cosmos DB 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.
  • Cosmos DB 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 multi-region database accounts.


  • 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.



  • Add Hash & Range partition resolvers to assist with sharding applications across multiple partitions.


  • Implement Upsert. New UpsertXXX methods added to support Upsert feature.
  • Implement ID Based Routing. No public API changes, all changes internal.


  • 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.


  • GA SDK.

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 recommend that you always upgrade to the latest SDK version as early as possible.

Any request to Cosmos DB using a retired SDK are rejected by the service.


All versions of the Python SDK for SQL API prior to version 1.0.0 were retired on February 29, 2016.


All versions 1.x and 2.x of the Python SDK for SQL API will be retired on August 30, 2020.

Version Release Date Retirement Date
3.0.2 Nov 15, 2018 ---
3.0.1 Oct 04, 2018 ---
2.3.3 Sept 08, 2018 August 30, 2020
2.3.2 May 08, 2018 August 30, 2020
2.3.1 December 21, 2017 August 30, 2020
2.3.0 November 10, 2017 August 30, 2020
2.2.1 Sep 29, 2017 August 30, 2020
2.2.0 May 10, 2017 August 30, 2020
2.1.0 May 01, 2017 August 30, 2020
2.0.1 October 30, 2016 August 30, 2020
2.0.0 September 29, 2016 August 30, 2020
1.9.0 July 07, 2016 August 30, 2020
1.8.0 June 14, 2016 August 30, 2020
1.7.0 April 26, 2016 August 30, 2020
1.6.1 April 08, 2016 August 30, 2020
1.6.0 March 29, 2016 August 30, 2020
1.5.0 January 03, 2016 August 30, 2020
1.4.2 October 06, 2015 August 30, 2020
1.4.1 October 06, 2015 August 30, 2020
1.2.0 August 06, 2015 August 30, 2020
1.1.0 July 09, 2015 August 30, 2020
1.0.1 May 25, 2015 August 30, 2020
1.0.0 April 07, 2015 August 30, 2020
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


1. How will customers be notified of the retiring SDK?

Microsoft will provide 12 month advance notification to the end of support of the retiring SDK in order to facilitate a smooth transition to a supported SDK. Further, customers will be notified through various communication channels – Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

Yes, customers will have full access to author, deploy and modify applications using the "to-be" retired Azure Cosmos DB SDK during the 12 month grace period. During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

After the 12 month notification period, the SDK will be retired. Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. Further, Microsoft will not provide customer support on the retired SDK.

4. What happens to Customer’s running applications that are using unsupported Azure Cosmos DB SDK version?

Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5. Will new features and functionality be applied to all non-retired SDKs?

New features and functionality will only be added to new versions. If you are using an old, non-retired, version of the SDK your requests to Azure Cosmos DB will still function as previous but you will not have access to any new capabilities.

6. What should I do if I cannot update my application before a cut-off date?

We recommend that you upgrade to the latest SDK as early as possible. Once an SDK has been tagged for retirement you will have 12 months to update your application. If, for whatever reason, you cannot complete your application update within this timeframe then please contact the Cosmos DB Team and request their assistance before the cutoff date.

See also

To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.