Azure Functions with Cosmos DB Output Binding

This document explains how to use the Azure Cosmos DB output binding for Azure Functions. This binding allows your functions to write data to a Cosmos DB container without needing to manage the Cosmos DB SDK directly.

What is the Cosmos DB Output Binding?

The Cosmos DB output binding simplifies the process of persisting data from your Azure Functions into Azure Cosmos DB. When configured as an output binding, a function can send data to a specified Cosmos DB container. The binding handles the creation of documents and ensures they are correctly stored in your database.

Configuration

To use the Cosmos DB output binding, you need to configure it in your function's function.json file (for JavaScript, C#, Python, etc.) or through attributes (for C#). You'll need to specify the connection string, database name, and collection (container) name.

Example: function.json (JavaScript)

{
  "scriptFile": "index.js",
  "bindings": [
    {
      "name": "message",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "post"
      ]
    },
    {
      "name": "outputDocument",
      "type": "cosmosDB",
      "direction": "out",
      "databaseName": "MyDatabase",
      "collectionName": "MyContainer",
      "connectionStringSetting": "CosmosDBConnectionString"
    }
  ]
}
        

Example: C# Attributes

using Microsoft.Azure.WebJobs;

public static class MyFunction
{
    [FunctionName("WriteToCosmosDB")]
    public static void Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] dynamic inputData,
        [CosmosDB(
            databaseName: "MyDatabase",
            collectionName: "MyContainer",
            ConnectionStringSetting = "CosmosDBConnectionString"
        )] out dynamic outputDocument)
    {
        // The 'outputDocument' variable will be automatically sent to Cosmos DB
        // when the function execution completes.
        outputDocument = inputData;
    }
}
        

How it Works

When your function executes, any data assigned to the output binding parameter (e.g., outputDocument in the C# example, or returned by the function in some languages) will be processed by the binding.

• The binding takes the data.
• It constructs a new document.
• It sends this document to the specified Cosmos DB container.
• If the document already exists with the same ID, it will be replaced by default, or you can configure it to upsert.

Common Scenarios

• Logging data from HTTP requests.
• Storing results of background processing.
• Persisting data generated by other triggers.

Advanced Usage

Using an ID

By default, Cosmos DB will generate a unique ID for new documents. If you need to control the ID, you can do so:

• In JavaScript: Assign an id property to the object you are sending.
• In C#: You can use the Id property if your output is a strongly-typed object or a dynamic object.

Upserting Documents

The default behavior for an output binding is to create new documents. If you want to update existing documents or create new ones if they don't exist (upsert), you can often configure this through the binding settings or by ensuring your data includes an id that matches an existing document.