Azure Cosmos DB bindings for Azure Functions

This article explains how to work with Azure Cosmos DB bindings in Azure Functions. Azure Functions supports trigger, input, and output bindings for Azure Cosmos DB.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

Trigger

The Azure Cosmos DB Trigger uses the Azure Cosmos DB Change Feed to listen for changes across partitions. 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.

Important

Currently, if multiple functions are configured to use a Cosmos DB trigger for the same collection, each of the functions should use a dedicated lease collection. Otherwise, only one of the functions will be triggered.

Trigger - example

See the language-specific example:

Trigger - C# example

The following example shows a precompiled C# function that triggers from a specific database and collection.

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

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
            log.Info("Documents modified " + documents.Count);
            log.Info("First document Id " + documents[0].Id);
    }

Trigger - C# script example

The following example shows a Cosmos DB trigger binding in a function.json file and a C# script function that uses the binding. The function writes log messages when Cosmos DB records are modified.

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Here's the C# script code:

    #r "Microsoft.Azure.Documents.Client"

    using System;
    using Microsoft.Azure.Documents;
    using System.Collections.Generic;


    public static void Run(IReadOnlyList<Document> documents, TraceWriter log)
    {
      log.Verbose("Documents modified " + documents.Count);
      log.Verbose("First document Id " + documents[0].Id);
    }

Trigger - JavaScript example

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

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Here's the JavaScript code:

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

      context.done();
    }

Trigger - attributes

For precompiled C# functions, use the CosmosDBTrigger attribute, which is defined in NuGet package Microsoft.Azure.WebJobs.Extensions.DocumentDB.

The attribute's constructor takes the database name and collection name. For information about those settings and other properties that you can configure, see Trigger - configuration. Here's a CosmosDBTrigger attribute example in a method signature:

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

For a complete example, see Trigger - precompiled C# example.

Trigger - configuration

The following table explains the binding configuration properties that you set in the function.json file and the CosmosDBTrigger attribute.

function.json property Attribute property Description
type Must be set to cosmosDBTrigger.
direction Must be set to in. This parameter is set automatically when you create the trigger in the Azure portal.
name The variable name used in function code that represents the list of documents with changes.
connectionStringSetting ConnectionStringSetting The name of an app setting that contains the connection string used to connect to the Azure Cosmos DB account being monitored.
databaseName DatabaseName The name of the Azure Cosmos DB database with the collection being monitored.
collectionName CollectionName The name of the collection being monitored.
leaseConnectionStringSetting LeaseConnectionStringSetting (Optional) The name of an app setting that contains the connection string to the service which holds the lease collection. When not set, the connectionStringSetting value is used. This parameter is automatically set when the binding is created in the portal.
leaseDatabaseName LeaseDatabaseName (Optional) The name of the database that holds the collection used to store leases. When not set, the value of the databaseName setting is used. This parameter is automatically set when the binding is created in the portal.
leaseCollectionName LeaseCollectionName (Optional) The name of the collection used to store leases. When not set, the value leases is used.
createLeaseCollectionIfNotExists CreateLeaseCollectionIfNotExists (Optional) When set to true, the leases collection is automatically created when it doesn't already exist. The default value is false.
leasesCollectionThroughput LeasesCollectionThroughput (Optional) Defines the amount of Request Units to assign when the leases collection is created. This setting is only used When createLeaseCollectionIfNotExists is set to true. This parameter is automatically set when the binding is created using the portal.
LeaseOptions Configure lease options by setting properties in an instance of the Change​Feed​Host​Options class.

When you're developing locally, app settings go into the local.settings.json file.

Note

The connection string for the leases collection must have write permissions.

Input

The DocumentDB API input binding retrieves one or more Azure Cosmos DB documents and passes them to the input parameter of the function. The document ID or query parameters can be determined based on the trigger that invokes the function.

Input - example 1

See the language-specific example that reads a single document:

Input - C# example

The following example shows a precompiled C# function that retrieves a single document from a specific database and collection. First, Id and Maker values for a CarReview instance are passed to a queue.

   public class CarReview
   {
       public string Id { get; set; }
       public string Maker { get; set; }
       public string Description { get; set; }
       public string Model { get; set; }
       public string Image { get; set; }
       public string Review { get; set; }
   }

The Cosmos DB binding uses Id and Maker from the queue message to retrieve the document from the database.

    using Microsoft.Azure.WebJobs;
    using Microsoft.Azure.WebJobs.Host;

    namespace CosmosDB
    {
        public static class SingleEntry
        {
            [FunctionName("SingleEntry")]
            public static void Run(
                [QueueTrigger("car-reviews", Connection = "StorageConnectionString")] CarReview carReview,
                [DocumentDB("cars", "car-reviews", PartitionKey = "{maker}", Id= "{id}", ConnectionStringSetting = "CarReviewsConnectionString")] CarReview document,
                TraceWriter log)
            {
                log.Info( $"Selected Review - {document?.Review}"); 
            }
        }
    }

Input - C# script example

The following example shows a Cosmos DB input binding in a function.json file and a C# script function that uses the binding. The function reads a single document and updates the document's text value.

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

{
    "name": "inputDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "partitionKey": "{partition key value}",
    "connection": "MyAccount_COSMOSDB",     
    "direction": "in"
}

The configuration section explains these properties.

Here's the C# script code:

    using System;

    // Change input document contents using DocumentDB API input binding 
    public static void Run(string myQueueItem, dynamic inputDocument)
    {   
      inputDocument.text = "This has changed.";
    }

Input - F# example

The following example shows a Cosmos DB input binding in a function.json file and a F# function that uses the binding. The function reads a single document and updates the document's text value.

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

{
    "name": "inputDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "connection": "MyAccount_COSMOSDB",     
    "direction": "in"
}

The configuration section explains these properties.

Here's the F# code:

    (* Change input document contents using DocumentDB API input binding *)
    open FSharp.Interop.Dynamic
    let Run(myQueueItem: string, inputDocument: obj) =
    inputDocument?text <- "This has changed."

This example requires a project.json file that specifies the FSharp.Interop.Dynamic and Dynamitey NuGet dependencies:

{
    "frameworks": {
        "net46": {
            "dependencies": {
                "Dynamitey": "1.0.2",
                "FSharp.Interop.Dynamic": "3.0.0"
            }
        }
    }
}

To add a project.json file, see F# package management.

Input - JavaScript example

The following example shows a Cosmos DB input binding in a function.json file and a JavaScript function that uses the binding. The function reads a single document and updates the document's text value.

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

{
    "name": "inputDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",     
    "direction": "in"
}

The configuration section explains these properties.

Here's the JavaScript code:

    // Change input document contents using DocumentDB API input binding, using context.bindings.inputDocumentOut
    module.exports = function (context) {   
    context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
    context.bindings.inputDocumentOut.text = "This was updated!";
    context.done();
    };

Input - example 2

See the language-specific example that reads multiple documents:

Input - C# example 2

The following example shows a precompiled C# function that executes a SQL query. To use the SqlQuery parameter, you need to install the latest beta version of Microsoft.Azure.WebJobs.Extensions.DocumentDB NuGet package.

    using System.Net;
    using System.Net.Http;
    using System.Collections.Generic;
    using Microsoft.Azure.WebJobs;
    using Microsoft.Azure.WebJobs.Extensions.Http;

    [FunctionName("CosmosDBSample")]
    public static HttpResponseMessage Run(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequestMessage req,
        [DocumentDB("test", "test", ConnectionStringSetting = "CosmosDB", SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")] IEnumerable<object> documents)
    {
        return req.CreateResponse(HttpStatusCode.OK, documents);
    }

Input - C# script example 2

The following example shows a DocumentDB input binding in a function.json file and a C# script function that uses the binding. The function retrieves multiple documents specified by a SQL query, using a queue trigger to customize the query parameters.

The queue trigger provides a parameter departmentId. A queue message of { "departmentId" : "Finance" } would return all records for the finance department.

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

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}"
    "connection": "CosmosDBConnection"
}

The configuration section explains these properties.

Here's the C# script code:

    public static void Run(QueuePayload myQueueItem, IEnumerable<dynamic> documents)
    {   
        foreach (var doc in documents)
        {
            // operate on each document
        }    
    }

    public class QueuePayload
    {
        public string departmentId { get; set; }
    }

Input - JavaScript example 2

The following example shows a DocumentDB input binding in a function.json file and a JavaScript function that uses the binding. The function retrieves multiple documents specified by a SQL query, using a queue trigger to customize the query parameters.

The queue trigger provides a parameter departmentId. A queue message of { "departmentId" : "Finance" } would return all records for the finance department.

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

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}"
    "connection": "CosmosDBConnection"
}

The configuration section explains these properties.

Here's the JavaScript code:

    module.exports = function (context, input) {    
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }       
        context.done();
    };

Input - attributes

For precompiled C# functions, use the DocumentDB attribute, which is defined in NuGet package Microsoft.Azure.WebJobs.Extensions.DocumentDB.

The attribute's constructor takes the database name and collection name. For information about those settings and other properties that you can configure, see the following configuration section.

Input - configuration

The following table explains the binding configuration properties that you set in the function.json file and the DocumentDB attribute.

function.json property Attribute property Description
type Must be set to documentdb.
direction Must be set to in.
name Name of the binding parameter that represents the document in the function.
databaseName DatabaseName The database containing the document.
collectionName CollectionName The name of the collection that contains the document.
id Id The ID of the document to retrieve. This property supports bindings parameters. To learn more, see Bind to custom input properties in a binding expression. Don't set both the id and sqlQuery properties. If you don't set either one, the entire collection is retrieved.
sqlQuery SqlQuery An Azure Cosmos DB SQL query used for retrieving multiple documents. The property supports runtime bindings, as in this example: SELECT * FROM c where c.departmentId = {departmentId}. Don't set both the id and sqlQuery properties. If you don't set either one, the entire collection is retrieved.
connection ConnectionStringSetting The name of the app setting containing your Azure Cosmos DB connection string.
partitionKey PartitionKey Specifies the partition key value for the lookup. May include binding parameters.

When you're developing locally, app settings go into the local.settings.json file.

Input - usage

In C# and F# functions, when the function exits successfully, any changes made to the input document via named input parameters are automatically persisted.

In JavaScript functions, updates are not made automatically upon function exit. Instead, use context.bindings.<documentName>In and context.bindings.<documentName>Out to make updates. See the JavaScript example.

Output

The DocumentDB API output binding lets you write a new document to an Azure Cosmos DB database.

Output - example

See the language-specific example:

Output - C# example

The following example shows a precompiled C# function that adds a document to a database, using data provided in message from Queue storage.

    using System;
    using Microsoft.Azure.WebJobs;

    [FunctionName("QueueToDocDB")]        
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        document = new { Text = myQueueItem, id = Guid.NewGuid() };
    }

Output - C# script example

The following example shows a DocumentDB output binding in a function.json file and a C# script function that uses the binding. The function uses a queue input binding for a queue that receives JSON in the following format:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

The function creates Azure Cosmos DB documents in the following format for each record:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

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

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",     
    "direction": "out"
}

The configuration section explains these properties.

Here's the C# script code:

    #r "Newtonsoft.Json"

    using Microsoft.Azure.WebJobs.Host;
    using Newtonsoft.Json.Linq;

    public static void Run(string myQueueItem, out object employeeDocument, TraceWriter log)
    {
      log.Info($"C# Queue trigger function processed: {myQueueItem}");

      dynamic employee = JObject.Parse(myQueueItem);

      employeeDocument = new {
        id = employee.name + "-" + employee.employeeId,
        name = employee.name,
        employeeId = employee.employeeId,
        address = employee.address
      };
    }

To create multiple documents, you can bind to ICollector<T> or IAsyncCollector<T> where T is one of the supported types.

Output - F# example

The following example shows a DocumentDB output binding in a function.json file and an F# function that uses the binding. The function uses a queue input binding for a queue that receives JSON in the following format:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

The function creates Azure Cosmos DB documents in the following format for each record:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

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

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",     
    "direction": "out"
}

The configuration section explains these properties.

Here's the F# code:

    open FSharp.Interop.Dynamic
    open Newtonsoft.Json

    type Employee = {
      id: string
      name: string
      employeeId: string
      address: string
    }

    let Run(myQueueItem: string, employeeDocument: byref<obj>, log: TraceWriter) =
      log.Info(sprintf "F# Queue trigger function processed: %s" myQueueItem)
      let employee = JObject.Parse(myQueueItem)
      employeeDocument <-
        { id = sprintf "%s-%s" employee?name employee?employeeId
          name = employee?name
          employeeId = employee?employeeId
          address = employee?address }

This example requires a project.json file that specifies the FSharp.Interop.Dynamic and Dynamitey NuGet dependencies:

{
    "frameworks": {
        "net46": {
          "dependencies": {
            "Dynamitey": "1.0.2",
            "FSharp.Interop.Dynamic": "3.0.0"
           }
        }
    }
}

To add a project.json file, see F# package management.

Output - JavaScript example

The following example shows a DocumentDB output binding in a function.json file and a JavaScript function that uses the binding. The function uses a queue input binding for a queue that receives JSON in the following format:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

The function creates Azure Cosmos DB documents in the following format for each record:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

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

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",     
    "direction": "out"
}

The configuration section explains these properties.

Here's the JavaScript code:

    module.exports = function (context) {

      context.bindings.employeeDocument = JSON.stringify({ 
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });

      context.done();
    };

Output - attributes

For precompiled C# functions, use the DocumentDB attribute, which is defined in NuGet package Microsoft.Azure.WebJobs.Extensions.DocumentDB.

The attribute's constructor takes the database name and collection name. For information about those settings and other properties that you can configure, see Output - configuration. Here's a DocumentDB attribute example in a method signature:

    [FunctionName("QueueToDocDB")]        
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

For a complete example, see Output - precompiled C# example.

Output - configuration

The following table explains the binding configuration properties that you set in the function.json file and the DocumentDB attribute.

function.json property Attribute property Description
type Must be set to documentdb.
direction Must be set to out.
name Name of the binding parameter that represents the document in the function.
databaseName DatabaseName The database containing the collection where the document is created.
collectionName CollectionName The name of the collection where the document is created.
createIfNotExists CreateIfNotExists A boolean value to indicate whether the collection is created when it doesn't exist. The default is false because new collections are created with reserved throughput, which has cost implications. For more information, see the pricing page.
partitionKey PartitionKey When CreateIfNotExists is true, defines the partition key path for the created collection.
collectionThroughput CollectionThroughput When CreateIfNotExists is true, defines the throughput of the created collection.
connection ConnectionStringSetting The name of the app setting containing your Azure Cosmos DB connection string.

When you're developing locally, app settings go into the local.settings.json file.

Output - usage

By default, when you write to the output parameter in your function, a document is created in your database. This document has an automatically generated GUID as the document ID. You can specify the document ID of the output document by specifying the id property in the JSON object passed to the output parameter.

Note

When you specify the ID of an existing document, it gets overwritten by the new output document.

Next steps