Azure Cosmos DB trigger and bindings for Azure Functions 2.x and higher overview

This set of articles explains how to work with Azure Cosmos DB bindings in Azure Functions 2.x and higher. Azure Functions supports trigger, input, and output bindings for Azure Cosmos DB.

Action Type
Run a function when an Azure Cosmos DB document is created or modified Trigger
Read an Azure Cosmos DB document Input binding
Save changes to an Azure Cosmos DB document Output binding


This reference is for Azure Functions version 2.x and higher. For information about how to use these bindings in Functions 1.x, see Azure Cosmos DB bindings for Azure Functions 1.x.

This binding was originally named DocumentDB. In Functions version 2.x and higher, the trigger, bindings, and package are all named Cosmos DB.

Supported APIs

Azure Cosmos DB bindings are only supported for use with the SQL API. Support for Table API is provided by using the Table storage bindings, starting with extension 5.x. For all other Azure Cosmos DB APIs, you should access the database from your function by using the static client for your API, including Azure Cosmos DB's API for MongoDB, Cassandra API, and Gremlin API.

Install extension

The extension NuGet package you install depends on the C# mode you're using in your function app:

Functions execute in the same process as the Functions host. To learn more, see Develop C# class library functions using Azure Functions.

The process for installing the extension varies depending on the extension version:

Working with the trigger and bindings requires that you reference the appropriate NuGet package. Install the NuGet package, version 3.x.

Install bundle

The Cosmos DB is part of an extension bundle, which is specified in your host.json project file. You may need to modify this bundle to change the version of the binding, or if bundles aren't already installed. To learn more, see extension bundle.

You can install this version of the extension in your function app by registering the extension bundle, version 2.x or 3.x.

    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"

Because of schema changes in the Azure Cosmos DB SDK, version 4.x of the Azure Cosmos DB extension isn't currently supported for Java functions.

You can add this version of the extension from the preview extension bundle v4 by adding or replacing the following code in your host.json file:

  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"

To learn more, see Update your extensions.

Exceptions and return codes

Binding Reference
CosmosDB CosmosDB Error Codes

host.json settings

This section describes the configuration settings available for this binding in versions 2.x and higher. Settings in the host.json file apply to all functions in a function app instance. The example host.json file below contains only the version 2.x+ settings for this binding. For more information about function app configuration settings in versions 2.x and later versions, see host.json reference for Azure Functions.

    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
Property Default Description
connectionMode Gateway The connection mode used by the function when connecting to the Azure Cosmos DB service. Options are Direct and Gateway
protocol Https The connection protocol used by the function when connection to the Azure Cosmos DB service. Read here for an explanation of both modes.
leasePrefix n/a Lease prefix to use across all functions in an app.

Next steps