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. 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, Gremlin API, and Table API.

Add to your Functions app

Functions 2.x and higher

Working with the trigger and bindings requires that you reference the appropriate package. The NuGet package is used for .NET class libraries while the extension bundle is used for all other application types.

Language Add by... Remarks
C# Installing the NuGet package, version 3.x
C# Script, Java, JavaScript, Python, PowerShell Registering the extension bundle The Azure Tools extension is recommended to use with Visual Studio Code.
C# Script (online-only in Azure portal) Adding a binding To update existing binding extensions without having to republish your function app, see Update your extensions.

Cosmos DB extension 4.x and higher

A new version of the Cosmos DB bindings extension is available in preview. It introduces the ability to connect using an identity instead of a secret. For .NET applications, it also changes the types that you can bind to, replacing the types from the v2 SDK Microsoft.Azure.DocumentDB with newer types from the v3 SDK Microsoft.Azure.Cosmos. Learn more about how these new types are different and how to migrate to them from the SDK migration guide, trigger, input binding, and output binding examples.

This extension version is available as a preview NuGet package. To learn more, see Update your extensions.


Currently, authentication with an identity instead of a secret using the 4.x preview extension is only available for Elastic Premium plans.

Functions 1.x

Functions 1.x apps automatically have a reference the Microsoft.Azure.WebJobs NuGet package, version 2.x.

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

This setting is not available in version 4.x of the extension.
leasePrefix n/a Lease prefix to use across all functions in an app.

This setting is not available in version 4.x of the extension.

Next steps