Overview

Azure Functions provides output bindings for Azure Cosmos DB, simplifying the process of writing data to your Cosmos DB collections. Instead of manually managing SDKs and connection strings within your function code, you can declare an output binding in your function's configuration, and the Functions runtime will handle the persistence of data to Cosmos DB.

This binding allows you to:

• Easily write documents to a specified Cosmos DB container.
• Leverage automatic retries and error handling provided by the Azure Functions runtime.
• Integrate seamlessly with other Azure services without complex dependency management.

How it Works

When you configure an output binding for Cosmos DB, you specify the target database, collection (or container), and optionally a partition key. Your function then needs to return or pass a value to this output binding, and the Functions runtime takes care of writing that value as a document to your Cosmos DB instance.

The most common way to use an output binding is by returning a value from your function. For more complex scenarios or when writing multiple items, you can use the out parameter.

Configuration

You define Cosmos DB output bindings in your function's function.json file (for JavaScript, Python, and PowerShell) or via attributes (for C#).

function.json Example (JavaScript, Python, PowerShell)

{
  "scriptFile": "../run.py",
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [ "get", "post" ],
      "authLevel": "function"
    },
    {
      "name": "doc",
      "type": "cosmosDB",
      "direction": "out",
      "databaseName": "TasksDB",
      "collectionName": "Tasks",
      "createIfNotExists": false,
      "connectionStringSetting": "CosmosDBConnection"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    }
  ]
}

Key properties in the configuration:

• name: The name of the output binding. This is the name you'll use in your code to reference the output.
• type: Must be cosmosDB for Cosmos DB output bindings.
• direction: Must be out.
• databaseName: The name of the Cosmos DB database.
• collectionName: The name of the Cosmos DB collection (container).
• createIfNotExists: (Optional) If set to true, the collection will be created if it doesn't exist. Defaults to false.
• connectionStringSetting: The name of the application setting that contains the Cosmos DB connection string.
• partitionKey: (Optional) Specifies the partition key value for new documents. If omitted and createIfNotExists is true, the collection will be created without a partition key defined.

C# Attribute Example

using Microsoft.Azure.WebJobs;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

public static class CreateItem
{
    [FunctionName("CreateItem")]
    public static IActionResult Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
        [CosmosDB(
            databaseName: "TasksDB",
            collectionName: "Tasks",
            ConnectionStringSetting = "CosmosDBConnection",
            CreateIfNotExists = false
        )] out dynamic document)
    {
        // Function logic here...
        var newItem = new { /* item properties */ };
        document = newItem; // Assign to output binding

        return new OkResult();
    }
}

Writing Data

Using the Return Value (JavaScript/TypeScript)

If your function has a single output binding and it's the default $return binding, you can simply return the object.

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const newItem = {
        id: context.invocationId,
        taskName: req.body.taskName,
        isComplete: false
    };

    context.log('Sending item to Cosmos DB output binding:', newItem);
    context.done(null, newItem); // Return the item to the $return output binding
};

Using an `out` Parameter (JavaScript)

For more explicit control or when you have multiple outputs, use an out parameter.

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const newItem = {
        id: context.invocationId,
        taskName: req.body.taskName,
        isComplete: false
    };

    context.log('Writing item to Cosmos DB output binding:', newItem);
    context.bindings.doc = newItem; // Assign to the 'doc' output binding

    context.res = {
        status: 201,
        body: "Item created successfully."
    };
    context.done();
};

Using an `out` Parameter (Python)

import logging
import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    task_name = req.get_json().get('taskName')
    if not task_name:
        return func.HttpResponse("Please provide a taskName in the request body", status_code=400)

    new_item = {
        "id": str(uuid.uuid4()), # Using uuid for unique IDs
        "taskName": task_name,
        "isComplete": False
    }

    logging.info(f"Writing item to Cosmos DB output binding: {new_item}")
    doc.set(func.Document.from_dict(new_item))

    return func.HttpResponse("Item created successfully.", status_code=201)

Partition Keys

For partitioned collections, you must specify a partition key. The Functions runtime uses this value to route the document to the correct partition.

Specifying Partition Key in function.json

{
  "scriptFile": "../run.py",
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [ "post" ],
      "authLevel": "function"
    },
    {
      "name": "doc",
      "type": "cosmosDB",
      "direction": "out",
      "databaseName": "TasksDB",
      "collectionName": "Tasks",
      "connectionStringSetting": "CosmosDBConnection",
      "partitionKey": "/userId"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    }
  ]
}

You can set the partition key value dynamically in your code.

Setting Partition Key Dynamically (JavaScript)

module.exports = async function (context, req) {
    const userId = req.body.userId;
    const taskName = req.body.taskName;

    if (!userId || !taskName) {
        context.res = { status: 400, body: "Please provide userId and taskName." };
        return;
    }

    const newItem = {
        id: context.invocationId,
        userId: userId,
        taskName: taskName,
        isComplete: false
    };

    // The partitionKey configuration in function.json uses a placeholder.
    // The runtime will use the value from the document's 'userId' property.
    // Alternatively, you can set the partition key explicitly on the output object if needed,
    // but usually the runtime infers it from the document structure based on the binding config.
    context.bindings.doc = newItem;

    context.res = {
        status: 201,
        body: "Item created successfully."
    };
};

Best Practices and Considerations

• Connection Strings: Store your Cosmos DB connection strings securely in application settings (e.g., in the Azure portal or local.settings.json).
• Idempotency: Ensure your functions are idempotent if they might be triggered multiple times with the same input. Cosmos DB's `id` field must be unique within a partition.
• Partitioning: Choose your partition keys wisely to ensure even data distribution and optimal performance.
• Error Handling: While the runtime handles some retries, implement your own error handling for critical operations.
• `createIfNotExists`: Use with caution in production environments. It's useful for development and testing, but in production, you typically want to ensure your resources are pre-provisioned.
• Throughput (RUs): Be mindful of the provisioned throughput for your Cosmos DB collection. High-volume writes can consume RUs quickly.

Troubleshooting

If you encounter issues:

• Check Logs: Review your Azure Functions logs for specific error messages.
• Verify Connection String: Ensure the CosmosDBConnection setting is correct and accessible.
• Database/Collection Names: Double-check that databaseName and collectionName match your Cosmos DB setup exactly.
• Partition Key Configuration: If using partitioning, verify the partitionKey configuration in function.json and that your document includes the corresponding property.
• Document Structure: Ensure the data you are sending to the output binding conforms to the expected schema of your Cosmos DB collection.