Package: azure-cosmos
DisclaimerAzure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer tohttps://github.com/Azure/azure-sdk-for-python/issues/20691Azure Cosmos DB SQL API client library for PythonAzure Cosmos DB is a globally distributed, multi-model database service that supports document, key-value, wide-column, and graph databases.Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON documents they contain in this NoSQL database service. High level capabilities are:Create Cosmos DBdatabasesand modify their settingsCreate and modifycontainersto store collections of JSON documentsCreate, read, update, and delete theitems(JSON documents) in your containersQuery the documents in your database usingSQL-like syntaxSDK source code|Package (PyPI)|Package (Conda)|API reference documentation|Product documentation|SamplesThis SDK is used for theSQL API. For all other APIs, please check theAzure Cosmos DB documentationto evaluate the best SDK for your project.Getting startedImportant update on Python 2.x SupportNew releases of this SDK won't support Python 2.x starting January 1st, 2022. Please check theCHANGELOGfor more information.PrerequisitesAzure subscription -Create a free accountAzureCosmos DB account- SQL APIPython 3.6+If you need a Cosmos DB SQL API account, you can create one with thisAzure CLIcommand:azcosmosdbcreate--resource-group<resource-group-name>--name<cosmos-account-name>Install the packagepipinstallazure-cosmosConfigure a virtual environment (optional)Although not required, you can keep your base system and Azure SDK environments isolated from one another if you use a virtual environment. Execute the following commands to configure and then enter a virtual environment withvenv:python3-mvenvazure-cosmosdb-sdk-environmentsourceazure-cosmosdb-sdk-environment/bin/activateAuthenticate the clientInteraction with Cosmos DB starts with an instance of theCosmosClientclass. You need anaccount, itsURI, and one of itsaccount keysto instantiate the client object.Use the Azure CLI snippet below to populate two environment variables with the database account URI and its primary master key (you can also find these values in the Azure portal). The snippet is formatted for the Bash shell.RES_GROUP=<resource-group-name>ACCT_NAME=<cosmos-db-account-name>exportACCOUNT_URI=$(azcosmosdbshow--resource-group$RES_GROUP--name$ACCT_NAME--querydocumentEndpoint--outputtsv)exportACCOUNT_KEY=$(azcosmosdblist-keys--resource-group$RES_GROUP--name$ACCT_NAME--queryprimaryMasterKey--outputtsv)Create the clientOnce you've populated theACCOUNT_URIandACCOUNT_KEYenvironment variables, you can create theCosmosClient.fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)AAD AuthenticationYou can also authenticate a client utilizing your service principal's AAD credentials and the azure identity package.
You can directly pass in the credentials information to ClientSecretCredential, or use the DefaultAzureCredential:fromazure.cosmosimportCosmosClientfromazure.identityimportClientSecretCredential,DefaultAzureCredentialimportosurl=os.environ['ACCOUNT_URI']tenant_id=os.environ['TENANT_ID']client_id=os.environ['CLIENT_ID']client_secret=os.environ['CLIENT_SECRET']# Using ClientSecretCredentialaad_credentials=ClientSecretCredential(tenant_id=tenant_id,client_id=client_id,client_secret=client_secret)# Using DefaultAzureCredential (recommended)aad_credentials=DefaultAzureCredential()client=CosmosClient(url,aad_credentials)Always ensure that the managed identity you use for AAD authentication hasreadMetadatapermissions.More information on how to set up AAD authentication:Set up RBAC for AAD authenticationMore information on allowed operations for AAD authenticated clients:RBAC Permission ModelKey conceptsOnce you've initialized aCosmosClient, you can interact with the primary resource types in Cosmos DB:Database: A Cosmos DB account can contain multiple databases. When you create a database, you specify the API you'd like to use when interacting with its documents: SQL, MongoDB, Gremlin, Cassandra, or Azure Table. Use theDatabaseProxyobject to manage its containers.Container: A container is a collection of JSON documents. You create (insert), read, update, and delete items in a container by using methods on theContainerProxyobject.Item: An Item is the dictionary-like representation of a JSON document stored in a container. Each Item you add to a container must include anidkey with a value that uniquely identifies the item within the container.For more information about these resources, seeWorking with Azure Cosmos databases, containers and items.How to useenable_cross_partition_queryThe keyword-argumentenable_cross_partition_queryaccepts 2 options:None(default) orTrue.Note on using queries by idWhen using queries that try to find items based on anidvalue, always make sure you are passing in a string type variable. Azure Cosmos DB only allows string id values and if you use any other datatype, this SDK will return no results and no error messages.Note on client consistency levelsAs of release version 4.3.0b3, if a user does not pass in an explicit consistency level to their client initialization,
their client will use their database account's default level. Previously, the default was being set toSessionconsistency.
If for some reason you'd like to keep doing this, you can change your client initialization to include the explicit parameter for this like shown:fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY,consistency_level='Session')LimitationsCurrently, the features below arenot supported. For alternatives options, check theWorkaroundssection below.Data Plane Limitations:Group By queriesQueries with COUNT from a DISTINCT subquery: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)Bulk/Transactional batch processingDirect TCP Mode accessContinuation token support for aggregate cross-partition queries like sorting, counting, and distinct.
Streamable queries likeSELECT * FROM WHEREdosupport continuation tokens.Change Feed: ProcessorChange Feed: Read multiple partitions key valuesChange Feed: Read specific timeChange Feed: Read from the beginningChange Feed: Pull modelCross-partition ORDER BY for mixed typesEnabling diagnostics for async query-type methodsControl Plane Limitations:Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metricsCreate Geospatial IndexGet the connection stringGet the minimum RU/s of a containerWorkaroundsBulk processing Limitation WorkaroundIf you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alternative is to usestored proceduresto write multiple items with the same partition key.Control Plane Limitations WorkaroundTypically, you can useAzure Portal,Azure Cosmos DB Resource Provider REST API,Azure CLIorPowerShellfor the control plane unsupported limitations.Boolean Data TypeWhile the Python languageuses"True" and "False" for boolean types, Cosmos DBaccepts"true" and "false" only. In other words, the Python language uses Boolean values with the first uppercase letter and all other lowercase letters, while Cosmos DB and its SQL language use only lowercase letters for those same Boolean values. How to deal with this challenge?Your JSON documents created with Python must use "True" and "False", to pass the language validation. The SDK will convert it to "true" and "false" for you. Meaning that "true" and "false" is what will be stored in Cosmos DB.If you retrieve those documents with the Cosmos DB Portal's Data Explorer, you will see "true" and "false".If you retrieve those documents with this Python SDK, "true" and "false" values will be automatically converted to "True" and "False".SQL Queries x FROM Clause SubitemsThis SDK uses thequery_itemsmethod to submit SQL queries to Azure Cosmos DB.Cosmos DB SQL language allows you toget subitems by using the FROM clause, to reduce the source to a smaller subset. As an example, you can useselect * from Families.childreninstead ofselect * from Families. But please note that:For SQL queries using thequery_itemsmethod, this SDK demands that you specify thepartition_keyor use theenable_cross_partition_queryflag.If you are getting subitems and specifying thepartition_key, please make sure that your partition key is included in the subitems, which is not true for most of the cases.Max Item CountThis is a parameter of the query_items method, an integer indicating the maximum number of items to be returned per page. TheNonevalue can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not set.ExamplesThe following sections provide several code snippets covering some of the most common Cosmos DB tasks, including:Create a databaseCreate a containerCreate an analytical store enabled containerGet an existing containerInsert dataDelete dataQuery the databaseGet database propertiesGet database and container throughputsModify container propertiesUsing the asynchronous clientCreate a databaseAfter authenticating yourCosmosClient, you can work with any resource in the account. The code snippet below creates a SQL API database, which is the default when no API is specified whencreate_databaseis invoked.fromazure.cosmosimportCosmosClient,exceptionsimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'try:database=client.create_database(DATABASE_NAME)exceptexceptions.CosmosResourceExistsError:database=client.get_database_client(DATABASE_NAME)Create a containerThis example creates a container with default settings. If a container with the same name already exists in the database (generating a409 Conflicterror), the existing container is obtained instead.fromazure.cosmosimportCosmosClient,PartitionKey,exceptionsimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'try:container=database.create_container(id=CONTAINER_NAME,partition_key=PartitionKey(path="/productName"))exceptexceptions.CosmosResourceExistsError:container=database.get_container_client(CONTAINER_NAME)exceptexceptions.CosmosHttpResponseError:raiseCreate an analytical store enabled containerThis example creates a container withAnalytical Storeenabled, for reporting, BI, AI, and Advanced Analytics withAzure Synapse Link.The options for analytical_storage_ttl are:0 or Null or not informed: Not enabled.-1: The data will be stored infinitely.Any other number: the actual ttl, in seconds.CONTAINER_NAME='products'try:container=database.create_container(id=CONTAINER_NAME,partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)exceptexceptions.CosmosResourceExistsError:container=database.get_container_client(CONTAINER_NAME)exceptexceptions.CosmosHttpResponseError:raiseThe preceding snippets also handle theCosmosHttpResponseErrorexception if the container creation failed. For more information on error handling and troubleshooting, see theTroubleshootingsection.Get an existing containerRetrieve an existing container from the database:fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)Insert dataTo insert items into a container, pass a dictionary containing your data toContainerProxy.upsert_item. Each item you add to a container must include anidkey with a value that uniquely identifies the item within the container.This example inserts several items into the container, each with a uniqueid:fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)foriinrange(1,10):container.upsert_item({'id':'item{0}'.format(i),'productName':'Widget','productModel':'Model{0}'.format(i)})Delete dataTo delete items from a container, useContainerProxy.delete_item. The SQL API in Cosmos DB does not support the SQLDELETEstatement.fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)foritemincontainer.query_items(query='SELECT * FROM products p WHERE p.productModel = "Model 2"',enable_cross_partition_query=True):container.delete_item(item,partition_key='Widget')NOTE: If you are using partitioned collection, the value of thepartitionKeyin the example code above, should be set to the value of the partition key for this particular item, not the name of the partition key column in your collection. This holds true for both point reads and deletes.Query the databaseA Cosmos DB SQL API database supports querying the items in a container withContainerProxy.query_itemsusing SQL-like syntax.This example queries a container for items with a specificid:fromazure.cosmosimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)# Enumerate the returned itemsimportjsonforitemincontainer.query_items(query='SELECT * FROM mycontainer r WHERE r.id="item3"',enable_cross_partition_query=True):print(json.dumps(item,indent=True))NOTE: Although you can specify any value for the container name in theFROMclause, we recommend you use the container name for consistency.Perform parameterized queries by passing a dictionary containing the parameters and their values toContainerProxy.query_items:discontinued_items=container.query_items(query='SELECT * FROM products p WHERE p.productModel = @model',parameters=[dict(name='@model',value='Model 7')],enable_cross_partition_query=True)foritemindiscontinued_items:print(json.dumps(item,indent=True))For more information on querying Cosmos DB databases using the SQL API, seeQuery Azure Cosmos DB data with SQL queries.Get database propertiesGet and display the properties of a database:fromazure.cosmosimportCosmosClientimportosimportjsonURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)properties=database.read()print(json.dumps(properties))Get database and container throughputsGet and display the throughput values of a database and of a container with dedicated throughput:fromazure.cosmosimportCosmosClientimportosimportjsonURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)# DatabaseDATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)db_offer=database.read_offer()print('Found Offer\'{0}\'for Database\'{1}\'and its throughput is\'{2}\''.format(db_offer.properties['id'],database.id,db_offer.properties['content']['offerThroughput']))# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughputCONTAINER_NAME='testContainer'container=database.get_container_client(CONTAINER_NAME)container_offer=container.read_offer()print('Found Offer\'{0}\'for Container\'{1}\'and its throughput is\'{2}\''.format(container_offer.properties['id'],container.id,container_offer.properties['content']['offerThroughput']))Modify container propertiesCertain properties of an existing container can be modified. This example sets the default time to live (TTL) for items in the container to 10 seconds:fromazure.cosmosimportCosmosClient,PartitionKeyimportosimportjsonURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)database.replace_container(container,partition_key=PartitionKey(path="/productName"),default_ttl=10,)# Display the new TTL setting for the containercontainer_props=container.read()print(json.dumps(container_props['defaultTtl']))For more information on TTL, seeTime to Live for Azure Cosmos DB data.Using the asynchronous clientThe asynchronous cosmos client is a separate client that looks and works in a similar fashion to the existing synchronous client. However, the async client needs to be imported separately and its methods need to be used with the async/await keywords.
The Async client needs to be initialized and closed after usage, which can be done manually or with the use of a context manager. The example below shows how to do so manually.fromazure.cosmos.aioimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']DATABASE_NAME='testDatabase'CONTAINER_NAME='products'asyncdefcreate_products():client=CosmosClient(URL,credential=KEY)database=client.get_database_client(DATABASE_NAME)container=database.get_container_client(CONTAINER_NAME)foriinrange(10):awaitcontainer.upsert_item({'id':'item{0}'.format(i),'productName':'Widget','productModel':'Model{0}'.format(i)})awaitclient.close()# the async client must be closed manually if it's not initialized in a with statementInstead of manually opening and closing the client, it is highly recommended to use theasync withkeywords. This creates a context manager that will initialize and later close the client once you're out of the statement. The example below shows how to do so.fromazure.cosmos.aioimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']DATABASE_NAME='testDatabase'CONTAINER_NAME='products'asyncdefcreate_products():asyncwithCosmosClient(URL,credential=KEY)asclient:# the with statement will automatically initialize and close the async clientdatabase=client.get_database_client(DATABASE_NAME)container=database.get_container_client(CONTAINER_NAME)foriinrange(10):awaitcontainer.upsert_item({'id':'item{0}'.format(i),'productName':'Widget','productModel':'Model{0}'.format(i)})Queries with the asynchronous clientUnlike the synchronous client, the async client does not have anenable_cross_partitionflag in the request. Queries without a specified partition key value will attempt to do a cross partition query by default.Query results can be iterated, but the query's raw output returns an asynchronous iterator. This means that each object from the iterator is an awaitable object, and does not yet contain the true query result. In order to obtain the query results you can use an async for loop, which awaits each result as you iterate on the object, or manually await each query result as you iterate over the asynchronous iterator.Since the query results are an asynchronous iterator, they can't be cast into lists directly; instead, if you need to create lists from your results, use an async for loop or Python's list comprehension to populate a list:fromazure.cosmos.aioimportCosmosClientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='products'container=database.get_container_client(CONTAINER_NAME)asyncdefcreate_lists():results=container.query_items(query='SELECT * FROM products p WHERE p.productModel = "Model 2"')# iterates on "results" iterator to asynchronously create a complete list of the actual query resultsitem_list=[]asyncforiteminresults:item_list.append(item)# Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.item_list=[itemasyncforiteminresults]awaitclient.close()Using Integrated CacheAn integrated cache is an in-memory cache that helps you ensure manageable costs and low latency as your request volume grows. The integrated cache has two parts: an item cache for point reads and a query cache for queries. The code snippet below shows you how to use this feature with the point read and query cache methods.The benefit of using this is that the point reads and queries that hit the integrated cache won't use any RUs. This means you will have a much lower per-operation cost than reads from the backend.How to configure the Azure Cosmos DB integrated cache (Preview)importazure.cosmos.cosmos_clientascosmos_clientimportosURL=os.environ['ACCOUNT_URI']KEY=os.environ['ACCOUNT_KEY']client=cosmos_client.CosmosClient(URL,credential=KEY)DATABASE_NAME='testDatabase'database=client.get_database_client(DATABASE_NAME)CONTAINER_NAME='testContainer'container=database.get_container_client(CONTAINER_NAME)defintegrated_cache_snippet():item_id=body['id']query='SELECT * FROM c'#item cachecontainer.read_item(item=item_id,partition_key=item_id,max_integrated_cache_staleness_in_ms=30000)#query cachecontainer.query_items(query=query,partition_key=item_id,max_integrated_cache_staleness_in_ms=30000)For more information on Integrated Cache, seeAzure Cosmos DB integrated cache - Overview.TroubleshootingGeneralWhen you interact with Cosmos DB using the Python SDK, exceptions returned by the service correspond to the same HTTP status codes returned for REST API requests:HTTP Status Codes for Azure Cosmos DBFor example, if you try to create a container using an ID (name) that's already in use in your Cosmos DB database, a409error is returned, indicating the conflict. In the following snippet, the error is handled gracefully by catching the exception and displaying additional information about the error.try:database.create_container(id=CONTAINER_NAME,partition_key=PartitionKey(path="/productName"))exceptexceptions.CosmosResourceExistsError:print("""Error creating containerHTTP status code 409: The ID (name) provided for the container is already in use.The container name must be unique within the database.""")LoggingThis library uses the standardlogginglibrary for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.Detailed DEBUG level logging, including request/response bodies and unredacted
headers, can be enabled on a client with thelogging_enableargument:importsysimportloggingfromazure.cosmosimportCosmosClient# Create a logger for the 'azure' SDKlogger=logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a console outputhandler=logging.StreamHandler(stream=sys.stdout)logger.addHandler(handler)# This client will log detailed information about its HTTP sessions, at DEBUG levelclient=CosmosClient(URL,credential=KEY,logging_enable=True)Similarly,logging_enablecan enable detailed logging for a single operation,
even when it isn't enabled for the client:database=client.create_database(DATABASE_NAME,logging_enable=True)Alternatively, you can log using the CosmosHttpLoggingPolicy, which extends from the azure core HttpLoggingPolicy, by passing in your logger to theloggerargument.
By default, it will use the behaviour from HttpLoggingPolicy. Passing in theenable_diagnostics_loggingargument will enable the
CosmosHttpLoggingPolicy, and will have additional information in the response relevant to debugging Cosmos issues.importloggingfromazure.cosmosimportCosmosClient#Create a logger for the 'azure' SDKlogger=logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a file outputhandler=logging.FileHandler(filename="azure")logger.addHandler(handler)# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.# Since we passed in the logger to the client, it will log information on every request.client=CosmosClient(URL,credential=KEY,logger=logger,enable_diagnostics_logging=True)Similarly, logging can be enabled for a single operation by passing in a logger to the singular request.
However, if you desire to use the CosmosHttpLoggingPolicy to obtain additional information, theenable_diagnostics_loggingargument needs to be passed in at the client constructor.# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.client=CosmosClient(URL,credential=KEY,enable_diagnostics_logging=True)database=client.create_database(DATABASE_NAME,logger=logger)TelemetryAzure Core provides the ability for our Python SDKs to use OpenTelemetry with them. The only packages that need to be installed
to use this functionality are the following:pipinstallazure-core-tracing-opentelemetry
pipinstallopentelemetry-sdkFor more information on this, we recommend taking a look at thisdocumentfrom Azure Core describing how to set it up. We have also added asample fileto show how it can
be used with our SDK. This works the same way regardless of the Cosmos client you are using.Next stepsFor more extensive documentation on the Cosmos DB service, see theAzure Cosmos DB documentationon docs.microsoft.com.ContributingThis project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visithttps://cla.microsoft.com.When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.Release History4.5.1 (2023-09-12)Bugs FixedFixed bug when query with DISTINCT + OFFSET/LIMIT operators returns unexpected result. SeePR 31925.Other ChangesAdded additional checks for resource creation using specific characters that cause issues. SeePR 31861.4.5.0 (2023-08-09)Features AddedAdded support for continuation tokens for streamable cross partition queries. SeePR 31189.Bugs FixedFixed bug with asynccreate_database_if_not_existsmethod not working when passingoffer_throughputas an option. SeePR 31478.Other ChangesRenamedresponse_continuation_token_limit_in_kbtocontinuation_token_limitfor GA. SeePR 31532.4.4.1b1 (2023-07-25)Features AddedAdded ability to limit continuation token size when querying for items. SeePR 30731Bugs FixedFixed bug with async patch_item method. SeePR 30804.4.4.0 (2023-06-09)Features AddedGA release of Patch API and Delete All Items By Partition Key4.4.0b2 (2023-05-22)Features AddedAdded conditional patching for Patch operations. SeePR 30455.Bugs FixedFixed bug with non english locales causing an error with the RFC 1123 Date Format. SeePR 30125.Other ChangesRefactoring of our clientconnection_timeoutandrequest_timeoutconfigurations. SeePR 30171.4.4.0b1 (2023-04-11)Features AddedAddedpreviewdelete all items by partition key functionality. SeePR 29186. For more information on Partition Key Delete, please seeAzure Cosmos DB Partition Key Delete.Addedpreviewpartial document update (Patch API) functionality and container methods for patching items with operations. SeePR 29497. For more information on Patch, please seeAzure Cosmos DB Partial Document Update.Bugs FixedFixed bug in methodcreate_container_if_not_exists()of async database client for unexpected kwargs being passed intoread()method used internally. SeePR 29136.Fixed bug with methodquery_items()of our async container class, where partition key and cross partition headers would both be set when using partition keys. SeePR 29366.Fixed bug with client not properly surfacing errors for invalid credentials and identities with insufficient permissions. Users running into 'NoneType has no attribute ConsistencyPolicy' errors when initializing their clients will now see proper authentication exceptions. SeePR 29256.Other ChangesRemoved use ofsixpackage within the SDK.4.3.1 (2023-02-23)Features AddedAddedcorrelated_activity_idfor query operations.Added cross regional retries for Service Unavailable/Request Timeouts for read/Query Plan operations.GA release of CosmosHttpLoggingPolicy and autoscale feature.Bugs FixedBug fix to address queries with VALUE MAX (or any other aggregate) that run into an issue if the query is executed on a container with at least one "empty" partition.4.3.1b1 (2022-09-19)Features AddedGA release of integrated cache functionality. For more information on integrated cache please seeAzure Cosmos DB integrated cache.Added ability to replace analytical ttl on containers. For more information on analytical ttl please seeAzure Cosmos DB analytical store.AddedCosmosHttpLoggingPolicyto replaceHttpLoggingPolicyfor logging HTTP sessions.Added the ability to create containers and databases with autoscale properties for the sync and async clients.Added the ability to update autoscale throughput properties.Bugs FixedFixed parsing of args for overloadedcontainer.read()method.Fixedvalidate_cache_staleness_value()method to allow max_integrated_cache_staleness to be an integer greater than or equal to 0.Fixed__aiter__()method by removing the async keyword.4.3.0 (2022-05-23)Features AddedGA release of Async I/O APIs, including all changes from 4.3.0b1 to 4.3.0b4.Breaking ChangesMethod signatures have been updated to use keyword arguments instead of positional arguments for most method options in the async client.Bugfix: Automatic Id generation for items was turned on forupsert_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.Other ChangesDeprecated offer-named methods in favor of their new throughput-named counterparts (read_offer->get_throughput).Marked the GetAuthorizationHeader method for deprecation since it will no longer be public in a future release.Added samples showing how to configure retry options for both the sync and async clients.Deprecated theconnection_retry_policyandretry_optionsoptions in the sync client.Added user warning to non-query methods trying to usepopulate_query_metricsoptions.4.3.0b4 (2022-04-07)Features AddedAdded support for AAD authentication for the async client.Added support for AAD authentication for the sync client.Other ChangesChanged_set_partition_keyreturn typehint in async client.4.3.0b3 (2022-03-10)[WARNING]
The defaultSessionconsistency 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 seeConsistency Levels in Azure Cosmos DBfor more details on consistency levels, or the README section on this changehere.Features AddedAdded newprovisionalmax_integrated_cache_staleness_in_msparameter to read item and query items APIs in order
to make use of thepreviewCosmosDB integrated cache functionalitySee PR #22946.
Please seeAzure Cosmos DB integrated cachefor more details.Added support for split-proof queries for the async client.Bugs fixedDefault consistency level for the sync and async clients is no longerSessionand will instead be set to the
consistency level of the user's cosmos account setting on initialization if not passed during client initialization.
This change will impact client application in terms of RUs and latency. Users relying on defaultSessionconsistency
will need to pass it explicitly if their account consistency is different thanSession.
Please seeConsistency Levels in Azure Cosmos DBfor more details.Fixed invalid request body being sent when passing inserverScriptbody parameter to replace operations for trigger, sproc and udf resources.Movedis_system_keylogic in async client.Fixed TypeErrors not being thrown when passing in invalid connection retry policies to the client.4.3.0b2 (2022-01-25)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.Features AddedAdded support for split-proof queries for the sync client.Other ChangesAdded async user agent for async client.4.3.0b1 (2021-12-14)Features AddedAdded language native async i/o client.4.2.0 (2020-10-08)Bug fixesFixed bug where continuation token is not honored when query_iterable is used to get results by page. Issue #13265.Fixed bug where resource tokens not being honored for document reads and deletes. Issue #13634.New featuresAdded support for passing partitionKey while querying changefeed. Issue #11689.4.1.0 (2020-08-10)Added deprecation warning for "lazy" indexing mode. The backend no longer allows creating containers with this mode and will set them to consistent instead.New featuresAdded the ability to set the analytical storage TTL when creating a new container.Bug fixesFixed support for dicts as inputs for get_client APIs.Fixed Python 2/3 compatibility in query iterators.Fixed type hint error. Issue #12570 - thanks @sl-sandy.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 - thank you @Rabbit994.4.0.0 (2020-05-20)Stable release.Added HttpLoggingPolicy to pipeline to enable passing in a custom logger for request and response headers.4.0.0b6Fixed bug in synchronized_request for media APIs.Removed MediaReadMode and MediaRequestTimeout from ConnectionPolicy as media requests are not supported.4.0.0b5azure.cosmos.errors module deprecated and replaced by azure.cosmos.exceptionsThe access condition parameters (access_condition,if_match,if_none_match) have been deprecated in favor of separatematch_conditionandetagparameters.Fixed bug in routing map provider.Added query Distinct, Offset and Limit support.Default document query execution context now used forChangeFeed queriessingle partition queries (partitionkey, partitionKeyRangeId is present in options)Non document queriesErrors out for aggregates on multiple partitions, with enable cross partition query set to true, but no "value" keyword presentHits query plan endpoint for other scenarios to fetch query planAdded__repr__support for Cosmos entity objects.Updated documentation.4.0.0b4Added support for atimeoutkeyword argument to all operations to specify an absolute timeout in seconds
within which the operation must be completed. If the timeout value is exceeded, aazure.cosmos.errors.CosmosClientTimeoutErrorwill be raised.Added a newConnectionRetryPolicyto manage retry behaviour 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 socket 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.4.0.0b3Addedcreate_database_if_not_exists()andcreate_container_if_not_existsfunctionalities to CosmosClient and Database respectively.4.0.0b2Version 4.0.0b2 is the second iteration in our efforts to build a more Pythonic client library.Breaking changesThe client connection has been adapted to consume the HTTP pipeline defined inazure.core.pipeline.Interactive objects have now been renamed as proxies. This includes:Database->DatabaseProxyUser->UserProxyContainer->ContainerProxyScripts->ScriptsProxyThe constructor ofCosmosClienthas been updated:Theauthparameter has been renamed tocredentialand will now take an authentication type directly. This means the master key value, a dictionary of resource tokens, or a list of permissions can be passed in. However the old dictionary format is still supported.Theconnection_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:request_timeoutmedia_request_timeoutconnection_modemedia_read_modeproxy_configenable_endpoint_discoverypreferred_locationsmultiple_write_locationsA new classmethod constructor has been added toCosmosClientto enable creation via a connection string retrieved from the Azure portal.Someread_alloperations have been renamed tolistoperations:CosmosClient.read_all_databases->CosmosClient.list_databasesContainer.read_all_conflicts->ContainerProxy.list_conflictsDatabase.read_all_containers->DatabaseProxy.list_containersDatabase.read_all_users->DatabaseProxy.list_usersUser.read_all_permissions->UserProxy.list_permissionsAll operations that takerequest_optionsorfeed_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 fromazure.core.AzureErrorinstead ofCosmosErrorwhich has been removed.HTTPFailurehas been renamed toCosmosHttpResponseErrorJSONParseFailurehas been removed and replaced byazure.core.DecodeErrorAdded additional errors for specific response codes:CosmosResourceNotFoundErrorfor status 404CosmosResourceExistsErrorfor status 409CosmosAccessConditionFailedErrorfor status 412CosmosClientcan now be run in a context manager to handle closing the client connection.Iterable responses (e.g. query responses and list responses) are now of typeazure.core.paging.ItemPaged. The methodfetch_next_blockhas been replaced by a secondary iterator, accessed by theby_pagemethod.4.0.0b1Version 4.0.0b1 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Cosmos. For more information about this, and preview releases of other Azure SDK libraries, please visithttps://aka.ms/azure-sdk-preview1-python.Breaking changes: New API designOperations 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 aCosmosClientinstance 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 theget_<child>_clientmethod. For full details on the new API, please see thereference 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 theazure.cosmospackage.Individual request properties can be provided as keyword arguments rather than constructing a separateRequestOptionsinstance.3.0.2Added Support for MultiPolygon DatatypeBug Fix in Session Read Retry PolicyBug Fix for Incorrect padding issues while decoding base 64 strings3.0.1Bug fix in LocationCacheBug fix endpoint retry logicFixed documentation3.0.0Multi-region write support addedNaming changesDocumentClient to CosmosClientCollection to ContainerDocument to ItemPackage name updated to "azure-cosmos"Namespace updated to "azure.cosmos"2.3.3Added support for proxyAdded support for reading change feedAdded support for collection quota headersBugfix for large session tokens issueBugfix for ReadMedia APIBugfix in partition key range cache2.3.2Added support for default retries on connection issues.2.3.1Updated documentation to reference Azure Cosmos DB instead of Azure DocumentDB.2.3.0This SDK version requires the latest version of Azure Cosmos DB Emulator available for download fromhttps://aka.ms/cosmosdb-emulator.2.2.1bugfix for aggregate dictbugfix for trimming slashes in the resource linktests for unicode encoding2.2.0Added support for Request Unit per Minute (RU/m) feature.Added support for a new consistency level called ConsistentPrefix.2.1.0Added 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.2.0.1Made editorial changes to documentation comments.2.0.0Added 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.1.9.0Added 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.1.8.0Added the support for geo-replicated database accounts.Test fixes to move the global host and masterKey into the individual test classes.1.7.0Added the support for Time To Live(TTL) feature for documents.1.6.1Bug fixes related to server side partitioning to allow special characters in partitionkey path.1.6.0Added the support for server side partitioned collections feature.1.5.0Added Client-side sharding framework to the SDK. Implemented HashPartionResolver and RangePartitionResolver classes.1.4.2Implement Upsert. New UpsertXXX methods added to support Upsert feature.Implement ID Based Routing. No public API changes, all changes internal.1.3.0Release skipped to bring version number in alignment with other SDKs1.2.0Supports 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.1.1.0Implements V2 indexing policy1.0.1Supports proxy connection