The Azure Cosmos DB Trigger uses the Azure Cosmos DB change feed to listen for inserts and updates across partitions. The change feed publishes new and updated items, not including updates from deletions.

For information on setup and configuration details, see the overview.

Cosmos DB scaling decisions for the Consumption and Premium plans are done via target-based scaling. For more information, see Target-based scaling.

::: zone pivot="programming-language-javascript,programming-language-typescript" [!INCLUDE functions-nodejs-model-tabs-description] ::: zone-end ::: zone pivot="programming-language-python" [!INCLUDE functions-bindings-python-models-intro]

::: zone-end

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

The usage of the trigger depends on the extension package version and the C# modality used in your function app, which can be one of the following:

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

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

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

The following examples depend on the extension version for the given C# mode.

Apps using Azure Cosmos DB extension version 4.x or higher have different attribute properties, which are shown here. This example refers to a simple ToDoItem type.

namespace CosmosDBSamplesV2
{
    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

using System.Collections.Generic;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "databaseName",
            containerName: "containerName",
            Connection = "CosmosDBConnectionSetting",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
        {
            if (input != null && input.Count > 0)
            {
                log.LogInformation("Documents modified " + input.Count);
                log.LogInformation("First document Id " + input[0].id);
            }
        }
    }
}

The following example shows a C# function that is invoked when there are inserts or updates in the specified database and collection.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation($"Documents modified: {documents.Count}");
                log.LogInformation($"First document Id: {documents[0].Id}");
            }
        }
    }
}

This example refers to a simple ToDoItem type:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

The following function is invoked when there are inserts or updates in the specified database and collection.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

The following code defines a MyDocument type:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/CosmosDB/CosmosDBFunction.cs" range="49-58":::

An IReadOnlyList<T> is used as the Azure Cosmos DB trigger binding parameter in the following example:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/CosmosDB/CosmosDBFunction.cs" id="docsnippet_exponential_backoff_retry_example":::

This example requires the following using statements:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/CosmosDB/CosmosDBFunction.cs" range="4-7":::

::: zone-end ::: zone pivot="programming-language-java"

This function is invoked when there are inserts or updates in the specified database and container.

[!INCLUDE functions-cosmosdb-extension-java-note]

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

In the Java functions runtime library, use the @CosmosDBTrigger annotation on parameters whose value would come from Azure Cosmos DB. This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

::: zone-end
::: zone pivot="programming-language-typescript"

The following example shows an Azure Cosmos DB trigger TypeScript function. The function writes log messages when Azure Cosmos DB records are added or modified.

:::code language="typescript" source="~/azure-functions-nodejs-v4/ts/src/functions/cosmosDBTrigger1.ts" :::

TypeScript samples aren't documented for model v3.

::: zone-end
::: zone pivot="programming-language-javascript"

The following example shows an Azure Cosmos DB trigger JavaScript function. The function writes log messages when Azure Cosmos DB records are added or modified.

:::code language="javascript" source="~/azure-functions-nodejs-v4/js/src/functions/cosmosDBTrigger1.js" :::

The following example shows an Azure Cosmos DB trigger binding in a function.json file and a JavaScript function that uses the binding. The function writes log messages when Azure Cosmos DB records are added or modified.

Here's the binding data in the function.json file:

[!INCLUDE functions-cosmosdb-trigger-attributes]

Here's the JavaScript code:

    module.exports = async function (context, documents) {
      context.log('First document Id modified : ', documents[0].id);
    }

::: zone-end
::: zone pivot="programming-language-powershell"

The following example shows how to run a function as data changes in Azure Cosmos DB.

[!INCLUDE functions-cosmosdb-trigger-attributes]

In the run.ps1 file, you have access to the document that triggers the function via the $Documents parameter.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

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

The following example shows an Azure Cosmos DB trigger binding. The example depends on whether you use the v1 or v2 Python programming model.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

The function writes log messages when Azure Cosmos DB records are modified. Here's the binding data in the function.json file:

[!INCLUDE functions-cosmosdb-trigger-attributes]

Here's the Python code:

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

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

Both in-process and isolated process C# libraries use the CosmosDBTriggerAttribute to define the function. C# script instead uses a function.json configuration file as described in the C# scripting guide.

[!INCLUDE functions-cosmosdb-attributes-v4]

[!INCLUDE functions-cosmosdb-attributes-v3]

[!INCLUDE functions-cosmosdb-attributes-v4]

[!INCLUDE functions-cosmosdb-attributes-v3]

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

Applies only to the Python v2 programming model.

For Python v2 functions defined using a decorator, the following properties on the cosmos_db_trigger:

For Python functions defined by using function.json, see the Configuration section. ::: zone-end

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

[!INCLUDE functions-cosmosdb-extension-java-note]

Use the @CosmosDBTrigger annotation on parameters that read data from Azure Cosmos DB. The annotation supports the following properties:

From the Java functions runtime library, use the @CosmosDBTrigger annotation on parameters that read data from Azure Cosmos DB. The annotation supports the following properties:

• name
• connectionStringSetting
• databaseName
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• checkpointDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

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

::: zone-end

::: zone pivot="programming-language-python" Applies only to the Python v1 programming model.

::: zone-end ::: zone pivot="programming-language-javascript,programming-language-typescript"

The following table explains the properties that you can set on the options object passed to the app.cosmosDB() method. The type, direction, and name properties don't apply to the v4 model.

The following table explains the binding configuration properties that you set in the function.json file, where properties differ by extension version:

::: zone-end ::: zone pivot="programming-language-powershell,programming-language-python"

The following table explains the binding configuration properties that you set in the function.json file, where properties differ by extension version:

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

[!INCLUDE functions-cosmosdb-settings-v4]

[!INCLUDE functions-cosmosdb-settings-v3]

::: zone-end

See the Example section for complete examples.

The trigger requires a second collection that it uses to store leases over the partitions. Both the collection being monitored and the collection that contains the leases must be available for the trigger to work.

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

The trigger doesn't indicate whether a document was updated or inserted, it just provides the document itself. If you need to handle updates and inserts differently, you could do that by implementing timestamp fields for insertion or update.

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

The parameter type supported by the Azure Cosmos DB trigger depends on the Functions runtime version, the extension package version, and the C# modality used.

See Binding types for a list of supported types.

See Binding types for a list of supported types.

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

See Binding types for a list of supported types.

::: zone-end

[!INCLUDE functions-cosmosdb-connections]

• Read an Azure Cosmos DB document (Input binding)
• Save changes to an Azure Cosmos DB document (Output binding)