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

• Version 1
• Version 2 and higher

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

Note

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 Azure Functions version 2.x and higher, the trigger, bindings, and package are all named Azure Cosmos DB.

Supported APIs

Azure Cosmos DB bindings are only supported for use with Azure Cosmos DB for NoSQL. Support for Azure Cosmos DB for Table 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 for MongoDB, Azure Cosmos DB for Cassandra, and Azure Cosmos DB for Apache Gremlin.

Install extension

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

In-process

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

Isolated process

Functions execute in an isolated C# worker process. To learn more, see Guide for running C# Azure Functions in an isolated worker process.

C# script

Functions run as C# script, which is supported primarily for C# portal editing. To update existing binding extensions for C# script apps running in the portal without having to republish your function app, see Update your extensions.

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

Functions 2.x+

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

Extension 4.x+

This version of the Azure Cosmos DB bindings extension introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

This version 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 NuGet package, version 4.x.

Functions 2.x+

Add the extension to your project by installing the NuGet package, version 3.x.

Extension 4.x+

This version of the Azure Cosmos DB bindings extension introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

Add the extension to your project by installing the NuGet package, version 4.x.

Functions 2.x+

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

Extension 4.x+

This extension version is available from the extension bundle v4 by adding the following lines in your host.json file:

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

Install bundle

The Azure Cosmos DB bindings extension 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.

Bundle v2.x and v3.x

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)"
    }
}

Bundle v4.x

This version of the bundle contains version 4.x of the Azure Cosmos DB bindings extension that introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

Because of schema changes in the Azure Cosmos DB SDK, version 4.x of the Azure Cosmos DB extension requires azure-functions-java-library V3.0.0 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.

---

Binding types

The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following:

In-process class library

An in-process class library is a compiled C# function runs in the same process as the Functions runtime.

Isolated process

An isolated worker process class library compiled C# function runs in a process isolated from the runtime.

C# script

C# script is used primarily when creating C# functions in the Azure portal.

Choose a version to see binding type details for the mode and version.

Extension 4.x and higher

The Azure Cosmos DB extension supports parameter types according to the table below.

Binding	Parameter types
Cosmos DB trigger	JSON serializable types1 IEnumerable<T>2
Cosmos DB input	JSON serializable types1 IEnumerable<T>2 CosmosClient
Cosmos DB output	JSON serializable types1

¹ Documents containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

² IEnumerable<T> provides a collection of documents. Here, T is a JSON serializable type. When specified for a trigger, it allows a single invocation to process a batch of documents. When used for an input binding, this allows multiple documents to be returned by the query.

Functions 2.x and higher

Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.Documents namespace. Newer types from Microsoft.Azure.Cosmos are exclusive to extension 4.x and higher.

Extension 4.x and higher

The isolated worker process supports parameter types according to the table below. Binding to JSON serializeable types is currently the only option that is generally available. Support for binding to types from Microsoft.Azure.Cosmos is in preview.

Binding	Parameter types	Preview parameter types1
Cosmos DB trigger	JSON serializable types2 IEnumerable<T>3	No preview types
Cosmos DB input	JSON serializable types2 IEnumerable<T>3	CosmosClient Database Container
Cosmos DB output	JSON serializable types2	No preview types4

¹ Preview types require use of Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.1.0-preview1 or later, Microsoft.Azure.Functions.Worker 1.12.1-preview1 or later, and Microsoft.Azure.Functions.Worker.Sdk 1.9.0-preview1 or later. When developing on your local machine, you will need Azure Functions Core Tools version 4.0.5000 or later. When using a preview type, binding expressions that rely on trigger data are not supported.

² Documents containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

³ IEnumerable<T> provides a collection of documents. Here, T is a JSON serializable type. When specified for a trigger, it allows a single invocation to process a batch of documents. When used for an input binding, this allows multiple documents to be returned by the query.

⁴ Support for SDK type bindings does not presently extend to output bindings.

Functions 2.x and higher

Earlier versions of extensions in the isolated worker process only support binding to JSON serializable types. Additional options are available to extension 4.x and higher.

Extension 4.x and higher

The Azure Cosmos DB extension supports parameter types according to the table below.

Binding	Parameter types
Cosmos DB trigger	JSON serializable types1 IEnumerable<T>2
Cosmos DB input	JSON serializable types1 IEnumerable<T>2 CosmosClient
Cosmos DB output	JSON serializable types1

¹ Documents containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

² IEnumerable<T> provides a collection of documents. Here, T is a JSON serializable type. When specified for a trigger, it allows a single invocation to process a batch of documents. When used for an input binding, this allows multiple documents to be returned by the query.

Functions 2.x and higher

Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.Documents namespace. Newer types from Microsoft.Azure.Cosmos are exclusive to extension 4.x and higher.

Exceptions and return codes

Binding	Reference
Azure Cosmos DB	HTTP status codes for Azure Cosmos DB

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.

Functions 2.x+

{
    "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.

Extension 4.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

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
userAgentSuffix	n/a	Adds the specified string value to all requests made by the trigger or binding to the service. This makes it easier for you to track the activity in Azure Monitor, based on a specific function app and filtering by User Agent.

Next steps

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