Skip to content

functions-bindings-cosmosdb-v2.md

Latest commit

 

History

History
256 lines (169 loc) · 15 KB

functions-bindings-cosmosdb-v2.md

File metadata and controls

256 lines (169 loc) · 15 KB
title Azure Cosmos DB bindings for Functions
description Understand how to use Azure Cosmos DB triggers and bindings in Azure Functions.
ms.topic reference
ms.custom
devx-track-extended-java
devx-track-js
devx-track-python
devx-track-ts
build-2025
ms.date 12/21/2025
zone_pivot_groups programming-languages-set-functions

Azure Cosmos DB trigger and bindings for Azure Functions overview

This set of articles explains how to work with Azure Cosmos DB bindings in Azure Functions. Azure Functions supports trigger, input, and output bindings for Azure Cosmos DB. For an end-to-end scenario that uses the Azure Cosmos DB extension, see Quickstart: Respond to database changes in Azure Cosmos DB using Azure Functions.

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

Important

This version of the Azure Cosmos DB binding extension supports Azure Functions version 4.x. If your app still uses version 1.x of the Functions runtime, instead see Azure Cosmos DB bindings for Azure Functions 1.x. In the Functions v1.x runtime, this binding was originally named DocumentDB.

Supported APIs

[!INCLUDE Azure Cosmos DB supported APIs note]

::: zone pivot="programming-language-csharp"

Install extension

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

Isolated worker model

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

In-process model

[!INCLUDE functions-in-process-model-retirement-note]

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

In a variation of this model, Functions can be run using C# scripting, 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:

Extension 4.x+

This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 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+

This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 2.x or 3.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.

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

If you're writing your application using F#, you must also configure this extension as part of the app's startup configuration. In the call to ConfigureFunctionsWorkerDefaults() or ConfigureFunctionsWebApplication(), add a delegate that takes an IFunctionsWorkerApplication parameter. Then within the body of that delegate, call ConfigureCosmosDBExtension() on the object:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Functions 2.x+

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

::: zone-end

::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-python,programming-language-java,programming-language-powershell"

[!INCLUDE functions-install-extension-bundle] ::: zone-end ::: zone pivot="programming-language-java"
[!INCLUDE functions-cosmosdb-extension-java-note] ::: zone-end
::: zone pivot="programming-language-csharp"

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:

Isolated worker model

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

In-process model

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

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

Extension 4.x+

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

| Binding scenario | Parameter types | |-|-|-| | Cosmos DB trigger (single document) | JSON serializable types1 | | Cosmos DB trigger (batch of documents) | IEnumerable<T>where T is a JSON serializable type1 | | Cosmos DB input (single document) | JSON serializable types1
| | Cosmos DB input (query returning multiple documents) | CosmosClient
IEnumerable<T> where T is a JSON serializable type1 | | Cosmos DB output (single document) | JSON serializable types1 | | Cosmos DB output (multiple documents) | ICollector<T> or IAsyncCollector<T> where T is a JSON serializable type1 |

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

Functions 2.x+

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+

The isolated worker process supports parameter types according to the tables below. Support for binding to types from Microsoft.Azure.Cosmosis in preview.

Cosmos DB trigger

[!INCLUDE functions-bindings-cosmosdb-v2-trigger-dotnet-isolated-types]

Cosmos DB input binding

[!INCLUDE functions-bindings-cosmosdb-v2-input-dotnet-isolated-types]

Cosmos DB output binding

[!INCLUDE functions-bindings-cosmosdb-v2-output-dotnet-isolated-types]

Functions 2.x+

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.

:::zone-end

::: zone pivot="programming-language-python"

SDK Binding Types

SDK Type support for Azure Cosmos is in Preview. Follow the Python SDK Bindings for CosmosDB Sample to get started with SDK Types for Cosmos in Python.

Important

Using SDK type bindings requires the Python v2 programming model.

Binding Parameter types Samples
CosmosDB input ContainerProxy,
CosmosClient,
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

:::zone-end

Exceptions and return codes

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

host.json settings

[!INCLUDE functions-host-json-section-intro]

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: Direct connects directly to backend replicas over TCP and can provide lower latency, and Gateway routes requests through a front-end gateway over HTTPS. For more information, see Azure Cosmos DB SDK connection modes.
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.

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: Direct connects directly to backend replicas over TCP and can provide lower latency, and Gateway routes requests through a front-end gateway over HTTPS. For more information, see Azure Cosmos DB SDK connection modes.
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