Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691
Azure 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:
SDK source code | Package (PyPI) | Package (Conda) | API reference documentation | Product documentation | Samples
This SDK is used for the SQL API. For all other APIs, please check the Azure Cosmos DB documentation to evaluate the best SDK for your project.
New releases of this SDK won't support Python 2.x starting January 1st, 2022. Please check the CHANGELOG for more information.
If you need a Cosmos DB SQL API account, you can create one with this Azure CLI command:
az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>
pip install azure-cosmos
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 with venv:
python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate
Interaction with Cosmos DB starts with an instance of the CosmosClient class. You need an account, its URI, and one of its account keys to 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>
export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)
Once you've populated the ACCOUNT_URI and ACCOUNT_KEY environment variables, you can create the CosmosClient.
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
You 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:
from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential
import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']
# Using ClientSecretCredential
aad_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 has readMetadata permissions.
More information on how to set up AAD authentication: Set up RBAC for AAD authentication
More information on allowed operations for AAD authenticated clients: RBAC Permission Model
Once you've initialized a CosmosClient, 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 the DatabaseProxy object 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 the ContainerProxy object.
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 an id key with a value that uniquely identifies the item within the container.
For more information about these resources, see Working with Azure Cosmos databases, containers and items.
enable_cross_partition_queryThe keyword-argument enable_cross_partition_query accepts 2 options: None (default) or True.
When using queries that try to find items based on an id value, 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.
As 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 to Session consistency.
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:
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')
Currently, the features below are not supported. For alternatives options, check the Workarounds section below.
SELECT * FROM WHERE do support continuation tokens.Typically, you can use Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI or PowerShell for the control plane unsupported limitations.
While the SDK supports transactional batch, support for bulk requests is not yet implemented in the Python SDK. You can use the async client along with this concurrency sample we have developed as a reference for a possible workaround.
[WARNING] Using the asynchronous client for concurrent operations like shown in this sample will consume a lot of RUs very fast. We strongly recommend testing this out against the cosmos emulator first to verify your code works well and avoid incurring charges.
While the Python language uses "True" and "False" for boolean types, Cosmos DB accepts "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?
This SDK uses the query_items method to submit SQL queries to Azure Cosmos DB.
Cosmos DB SQL language allows you to get subitems by using the FROM clause, to reduce the source to a smaller subset. As an example, you can use select * from Families.children instead of select * from Families. But please note that:
query_items method, this SDK demands that you specify the partition_key or use the enable_cross_partition_query flag.partition_key, please make sure that your partition key is included in the subitems, which is not true for most of the cases.This is a parameter of the query_items method, an integer indicating the maximum number of items to be returned per page. The None value 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.
The following sections provide several code snippets covering some of the most common Cosmos DB tasks, including:
After authenticating your CosmosClient, 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 when create_database is invoked.
from azure.cosmos import CosmosClient, exceptions
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
database = client.get_database_client(DATABASE_NAME)
This example creates a container with default settings. If a container with the same name already exists in the database (generating a 409 Conflict error), the existing container is obtained instead.
from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os
URL = 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"))
except exceptions.CosmosResourceExistsError:
container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
raise
This example creates a container with Analytical Store enabled, for reporting, BI, AI, and Advanced Analytics with Azure Synapse Link.
The options for analytical_storage_ttl are:
CONTAINER_NAME = 'products'
try:
container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
raise
The preceding snippets also handle the CosmosHttpResponseError exception if the container creation failed. For more information on error handling and troubleshooting, see the Troubleshooting section.
Retrieve an existing container from the database:
from azure.cosmos import CosmosClient
import os
URL = 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)
To insert items into a container, pass a dictionary containing your data to ContainerProxy.upsert_item. Each item you add to a container must include an id key with a value that uniquely identifies the item within the container.
This example inserts several items into the container, each with a unique id:
from azure.cosmos import CosmosClient
import os
URL = 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)
for i in range(1, 10):
container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
To delete items from a container, use ContainerProxy.delete_item. The SQL API in Cosmos DB does not support the SQL DELETE statement.
from azure.cosmos import CosmosClient
import os
URL = 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)
for item in container.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 the
partitionKeyin 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.
A Cosmos DB SQL API database supports querying the items in a container with ContainerProxy.query_items using SQL-like syntax.
This example queries a container for items with a specific id:
from azure.cosmos import CosmosClient
import os
URL = 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 items
import json
for item in container.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 the
FROMclause, we recommend you use the container name for consistency.
Perform parameterized queries by passing a dictionary containing the parameters and their values to ContainerProxy.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
)
for item in discontinued_items:
print(json.dumps(item, indent=True))
For more information on querying Cosmos DB databases using the SQL API, see Query Azure Cosmos DB data with SQL queries.
Get and display the properties of a database:
from azure.cosmos import CosmosClient
import os
import json
URL = 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 and display the throughput values of a database and of a container with dedicated throughput:
from azure.cosmos import CosmosClient
import os
import json
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.get_throughput()
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 throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.get_throughput()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))
Certain 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:
from azure.cosmos import CosmosClient, PartitionKey
import os
import json
URL = 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 container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))
For more information on TTL, see Time to Live for Azure Cosmos DB data.
Response headers include metadata information from the executed operations like etag, which allows for optimistic concurrency scenarios, or x-ms-request-charge which lets you know how many RUs were consumed by the request.
This applies to all item point operations in both the sync and async clients - and can be used by referencing the get_response_headers() method of any response as such:
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'
client = CosmosClient(URL, credential=KEY)
database = client.get_database_client(DATABASE_NAME)
container = database.get_container_client(CONTAINER_NAME)
operation_response = container.create_item({"id": "test_item", "productName": "test_item"})
operation_headers = operation_response.get_response_headers()
etag_value = operation_headers['etag']
request_charge = operation_headers['x-ms-request-charge']
The 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. We don't recommend doing it this way, since it requires that you manually call aenter() before using the client.
from azure.cosmos.aio import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'
async def create_products():
client = CosmosClient(URL, credential=KEY)
await client.__aenter__() # this piece is important for the SDK to cache account information
database = client.get_database_client(DATABASE_NAME)
container = database.get_container_client(CONTAINER_NAME)
for i in range(10):
await container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
await client.close() # the async client must be closed manually if it's not initialized in a with statement
Instead of manually opening and closing the client, it is highly recommended to use the async with keywords. This creates a context manager that will initialize and later close the client once you're out of the statement, as well as cache important information the SDK needs. The example below shows how to do so.
from azure.cosmos.aio import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'
async def create_products():
async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
database = client.get_database_client(DATABASE_NAME)
container = database.get_container_client(CONTAINER_NAME)
for i in range(10):
await container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
Unlike the synchronous client, the async client does not have an enable_cross_partition flag 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:
from azure.cosmos.aio import CosmosClient
import os
URL = 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)
async def create_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 results
item_list = []
async for item in results:
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 = [item async for item in results]
await client.close()
An 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)
import azure.cosmos.cosmos_client as cosmos_client
import os
URL = 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)
def integrated_cache_snippet():
item_id = body['id']
query = 'SELECT * FROM c'
#item cache
container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)
#query cache
container.query_items(query=query,
partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)
For more information on Integrated Cache, see Azure Cosmos DB integrated cache - Overview.
Transactional batch requests allow you to send several operations to be executed at once within the same partition key. If all operations succeed in the order they're described within the transactional batch operation, the transaction will be committed. However, if any operation fails, the entire transaction is rolled back.
Transactional batches have a limit of 100 operations per batch, and a total size limit of 1.2Mb for the batch operations being passed in.
Transactional Batch operations look very similar to the singular operations apis, and are tuples containing
(operation_type_string, args_tuple, batch_operation_kwargs_dictionary), with the kwargs dictionary being optional:
batch_operations = [
("create", (item_body,), kwargs),
("replace", (item_id, item_body), kwargs),
("read", (item_id,), kwargs),
("upsert", (item_body,), kwargs),
("patch", (item_id, operations), kwargs),
("delete", (item_id,), kwargs),
]
batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key=partition_key)
The batch operation kwargs dictionary is limited, and only takes a total of three different key values.
In the case of wanting to use conditional patching within the batch, the use of filter_predicate key is available for the
patch operation, or in case of wanting to use etags with any of the operations, the use of the if_match_etag/if_none_match_etag
keys is available as well.
batch_operations = [
("replace", (item_id, item_body), {"if_match_etag": etag}),
("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
]
We also have some samples showing these transactional batch operations in action with both the sync and async clients.
If there is a failure for an operation within the batch, the SDK will raise a CosmosBatchOperationError letting you know which operation failed,
as well as containing the list of failed responses for the failed request.
For more information on Transactional Batch, see Azure Cosmos DB Transactional Batch.
We have added new capabilities to utilize vector embeddings and vector indexing for users to leverage vector search utilizing our Cosmos SDK. These two container-level configurations have to be turned on at the account-level before you can use them.
Each vector embedding should have a path to the relevant vector field in your items being stored, a supported data type (float32, int8, uint8), the vector's dimensions, and the distance function being used for that embedding. Vectors indexed with the flat index type can be at most 505 dimensions. Vectors indexed with the quantizedFlat index type can be at most 4,096 dimensions. A sample vector embedding policy would look like this:
vector_embedding_policy = {
"vectorEmbeddings": [
{
"path": "/vector1",
"dataType": "float32",
"dimensions": 256,
"distanceFunction": "euclidean"
},
{
"path": "/vector2",
"dataType": "int8",
"dimensions": 200,
"distanceFunction": "dotproduct"
},
{
"path": "/vector3",
"dataType": "uint8",
"dimensions": 400,
"distanceFunction": "cosine"
}
]
}
Separately, vector indexes have been added to the already existing indexing_policy and only require two fields per index: the path to the relevant field to be used, and the type of index from the possible options (flat or quantizedFlat). A sample indexing policy with vector indexes would look like this:
indexing_policy = {
"automatic": True,
"indexingMode": "consistent",
"compositeIndexes": [
[
{"path": "/numberField", "order": "ascending"},
{"path": "/stringField", "order": "descending"}
]
],
"spatialIndexes": [
{"path": "/location/*", "types": [
"Point",
"Polygon"]}
],
"vectorIndexes": [
{"path": "/vector1", "type": "flat"},
{"path": "/vector2", "type": "quantizedFlat"}
]
}
You would then pass in the relevant policies to your container creation method to ensure these configurations are used by it. The operation will fail if you pass new vector indexes to your indexing policy but forget to pass in an embedding policy.
database.create_container(id=container_id, partition_key=PartitionKey(path="/id"),
indexing_policy=indexing_policy, vector_embedding_policy=vector_embedding_policy)
Note: vector embeddings and vector indexes CANNOT be edited by container replace operations. They are only available directly through creation.
With the addition of the vector indexing and vector embedding capabilities, the SDK can now perform order by vector search queries.
These queries specify the VectorDistance to use as a metric within the query text. These must always use a TOP or LIMIT clause within the query though,
since vector search queries have to look through a lot of data otherwise and may become too expensive or long-running.
Since these queries are relatively expensive, the SDK sets a default limit of 50000 max items per query - if you'd like to raise that further, you
can use the AZURE_COSMOS_MAX_ITEM_BUFFER_VECTOR_SEARCH environment variable to do so. However, be advised that queries with too many vector results
may have additional latencies associated with searching in the service.
The query syntax for these operations looks like this:
VectorDistance(<embedding1>, <embedding2>, [,<exact_search>], [,<specification>])
Embeddings 1 and 2 are the arrays of values for the relevant embeddings, exact_search is an optional boolean indicating whether
to do an exact search vs. an approximate one (default value of false), and specification is an optional Json snippet with embedding
specs that can include dataType, dimensions and distanceFunction. The specifications within the query will take precedence
to any configurations previously set by a vector embedding policy.
A sample vector search query would look something like this:
query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}]) AS " \
"SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}])".format(embeddings_string, embeddings_string)
Or if you'd like to add the optional parameters to the vector distance, you could do this:
query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}], true, {{'dataType': 'float32' , 'distanceFunction': 'cosine'}}) AS " \
"SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}], true, {{'dataType': " \
"'float32', 'distanceFunction': 'cosine'}})".format(embeddings_string, embeddings_string)
The embeddings_string above would be your string made from your vector embeddings.
You can find our sync samples here and our async samples here as well to help yourself out.
Note: For a limited time, if your query operates against a region or emulator that has not yet been updated the client might run into some issues
not being able to recognize the new NonStreamingOrderBy capability that makes vector search possible.
If this happens, you can set the AZURE_COSMOS_DISABLE_NON_STREAMING_ORDER_BY environment variable to "True" to opt out of this
functionality and continue operating as usual.
When 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 DB
For example, if you try to create a container using an ID (name) that's already in use in your Cosmos DB database, a 409 error 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"))
except exceptions.CosmosResourceExistsError:
print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")
This library uses the standard logging library for logging diagnostics. 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 the logging_enable argument:
import sys
import logging
from azure.cosmos import CosmosClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)
Similarly, logging_enable can 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 the logger argument.
By default, it will use the behaviour from HttpLoggingPolicy. Passing in the enable_diagnostics_logging argument will enable the
CosmosHttpLoggingPolicy, and will have additional information in the response relevant to debugging Cosmos issues.
import logging
from azure.cosmos import CosmosClient
#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a file output
handler = 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, the enable_diagnostics_logging argument 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)
Azure 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:
pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk
For more information on this, we recommend taking a look at this document from Azure Core describing how to set it up. We have also added a sample file to show how it can be used with our SDK. This works the same way regardless of the Cosmos client you are using.
For more extensive documentation on the Cosmos DB service, see the Azure Cosmos DB documentation on docs.microsoft.com.
This 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, visit https://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 the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This version and all future versions will support Python 3.13.
query_items_change_feed. See PR 37687CosmosDict 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.create_container_if_not_exists() methods. See PR 34286.computed_properties keyword as provisional, un-marked continuation_token_limit as provisional. See PR 34207.This version and all future versions will require Python 3.8+.
response_hook thread-safe in the sync client. See PR 33790.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.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.connection_timeout and request_timeout configurations. See PR 30171.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.correlated_activity_id for query operations.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.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._set_partition_key return typehint in async client.[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.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.
This change will impact client application in terms of RUs and latency. Users relying on default Session consistency
will need to pass it explicitly if their account consistency is different than Session.
Please see Consistency Levels in Azure Cosmos DB for more details.serverScript body parameter to replace operations for trigger, sproc and udf resources.is_system_key logic in async client.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.
Bug fixes
New features
New features
Bug fixes
access_condition, if_match, if_none_match) have been deprecated in favor of separate match_condition and etag parameters.__repr__ support for Cosmos entity objects.timeout keyword 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.CosmosClientTimeoutError will be raised.ConnectionRetryPolicy to manage retry behaviour during HTTP connection errors.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.create_database_if_not_exists() and create_container_if_not_exists functionalities to CosmosClient and Database respectively.Version 4.0.0b2 is the second iteration in our efforts to build a more Pythonic client library.
Breaking changes
azure.core.pipeline.Database -> DatabaseProxyUser -> UserProxyContainer -> ContainerProxyScripts -> ScriptsProxyCosmosClient has been updated:
auth parameter has been renamed to credential and 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.connection_policy parameter 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_locationsCosmosClient to enable creation via a connection string retrieved from the Azure portal.read_all operations have been renamed to list operations:
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_permissionsrequest_options or feed_options parameters, 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.azure.core.AzureError instead of CosmosError which has been removed.
HTTPFailure has been renamed to CosmosHttpResponseErrorJSONParseFailure has been removed and replaced by azure.core.DecodeErrorCosmosResourceNotFoundError for status 404CosmosResourceExistsError for status 409CosmosAccessConditionFailedError for status 412CosmosClient can now be run in a context manager to handle closing the client connection.azure.core.paging.ItemPaged. The method fetch_next_block has been replaced by a secondary iterator, accessed by the by_page method.Version 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 visit https://aka.ms/azure-sdk-preview1-python.
Breaking changes: New API design
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.get_<child>_client method. For full details on the new API, please see the reference documentation.azure.cosmos package.RequestOptions instance.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.
FAQs
Microsoft Azure Cosmos Client Library for Python
We found that azure-cosmos demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.