Cosmos DB Trigger - Azure Functions

What is a Cosmos DB Trigger?

The Cosmos DB trigger for Azure Functions allows you to execute your function code in response to changes in a Cosmos DB container. It works by listening to the Cosmos DB change feed, a continuously updated record of modifications to documents within a container.

This is ideal for scenarios like:

Real-time data processing
Data synchronization
Notifications and alerts
Data archiving or analytics

How it Works

When a document is created, updated, or deleted in your monitored Cosmos DB container, an entry is added to its change feed. The Azure Functions runtime polls this change feed. When changes are detected, the runtime invokes your function with the detected modifications as input.

Key components involved:

Cosmos DB Container: The source of changes.
Change Feed: The ordered list of modifications.
Lease Container: Used by the trigger to track its progress through the change feed, ensuring events are processed reliably and idempotently.

Configuration

The Cosmos DB trigger is configured using attributes (for .NET) or settings in your function.json file (for other languages).

Core Properties:

databaseName: The name of your Cosmos DB database.
containerName: The name of the container to monitor.
connectionStringSetting: The name of the application setting containing your Cosmos DB connection string.
leaseContainerName: (Recommended) The name of the container to use for storing leases. This container must exist and be in the same database.

Example function.json:

JSON

{
  "scriptFile": "../run.py",
  "bindings": [
    {
      "name": "documents",
      "type": "cosmosDBTrigger",
      "direction": "in",
      "databaseName": "MyDatabase",
      "containerName": "MyContainer",
      "connectionStringSetting": "CosmosDbConnectionString",
      "leaseContainerName": "MyLeaseContainer",
      "createLeaseContainerIfNotExists": true
    }
  ]
}

Sample Function (Python)

This example shows a simple Python function that triggers when documents are modified in Cosmos DB and logs the changes.

Python

import logging
import azure.functions as func

def main(documents: list[func.Document]):
    for doc in documents:
        logging.info('Cosmos DB Change Feed trigger function executed')
        logging.info(f'Detected change for document ID: {doc.id}')
        logging.info(f'Document content: {doc.to_json()}')

The documents parameter receives a list of changed documents.

Key Considerations

Idempotency: Design your function to be idempotent, meaning it can be executed multiple times with the same input without changing the result. The trigger guarantees at-least-once delivery.

Lease Container: Always use a dedicated lease container. This is crucial for distributed scaling and fault tolerance.

Scaling: The trigger scales automatically based on the number of partitions in your Cosmos DB container. Ensure your lease container is provisioned appropriately.

Partition Key: If your source container uses a partition key, the trigger will process changes in batches respecting partition boundaries.