Create a function triggered by Azure Cosmos DB

Learn how to create a function triggered when data is added to or changed in Azure Cosmos DB. To learn more about Azure Cosmos DB, see Azure Cosmos DB: Serverless database computing using Azure Functions.

View message in the logs.


To complete this tutorial:

  • If you don't have an Azure subscription, create a free account before you begin.

Favorite Functions in the portal

If you haven't already done so, add Function Apps to your favorites in the Azure portal. This makes it easier to find your function apps. If you have already done this, skip to the next section.

  1. Log in to the Azure portal.

  2. Click the arrow at the bottom left to expand all services, type Functions in the Filter field, and then click the star next to Function Apps.

    Create function app in the Azure portal

    This adds the Functions icon to the menu on the left of the portal.

  3. Close the menu, then scroll down to the bottom to see the Functions icon. Click this icon to see a list of all your function apps. Click your function app to work with functions in this app.

    Function Apps in Favorites

Create an Azure Function app

  1. Click the New button found on the upper left-hand corner of the Azure portal, then select Compute > Function App.

    Create a function app in the Azure portal

  2. Use the function app settings as specified in the table below the image.

    Define new function app settings

    Setting Suggested value Description
    App name Globally unique name Name that identifies your new function app. Valid characters are a-z, 0-9, and -.
    Subscription Your subscription The subscription under which this new function app will be created.
    Resource Group myResourceGroup Name for the new resource group in which to create your function app.
    OS Windows Serverless hosting is currently only available when running on Windows. For Linux hosting, see Create your first function running on Linux using the Azure CLI.
    Hosting plan Consumption plan Hosting plan that defines how resources are allocated to your function app. In the default Consumption Plan, resources are added dynamically as required by your functions. In this serverless hosting, you only pay for the time your functions run.
    Location West Europe Choose a location near you or near other services your functions will access.
    Storage account Globally unique name Name of the new storage account used by your function app. Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only. You can also use an existing account.
  3. Click Create to provision and deploy the new function app.

Next, you create a function in the new function app.

Create Azure Cosmos DB trigger

  1. Expand your function app and click the + button next to Functions. If this is the first function in your function app, select Custom function. This displays the complete set of function templates.

    Functions quickstart page in the Azure portal

  2. In the search field, type cosmos and then choose your desired language for the Azure Cosmos DB trigger template.

    Choose the Azure Cosmos DB trigger

  3. Configure the new trigger with the settings as specified in the table below the image.

    Create the Azure Cosmos DB triggered function

    Setting Suggested value Description
    Name Default Use the default function name suggested by the template.
    Collection name Items Name of collection to be monitored.
    Create lease collection if it doesn't exist Checked The collection doesn't already exist, so create it.
    Database name Tasks Name of database with the collection to be monitored.
  4. Select New next to the Azure Cosmos DB account connection label, and choose an existing Cosmos DB account or + Create new.

    Configure Azure Cosmos DB connection

  5. When creating a new Cosmos DB account, use the New account settings as specified in the table.

    Setting Suggested value Description
    ID Name of database Unique ID for the Azure Cosmos DB database
    API SQL (DocumentDB) This topic uses the document database API.
    Subscription Azure Subscription Azure Subscription
    Resource Group myResourceGroup Use the existing resource group that contains your function app.
    Location WestEurope Select a location near to either your function app or to other apps that use the stored documents.
  6. Click OK to create the database. It may take a few minutes to create the database. After the database is created, the database connection string is stored as a function app setting. The name of this app setting is inserted in Azure Cosmos DB account connection.

  7. Click Create to create your Azure Cosmos DB triggered function. After the function is created, the template-based function code is displayed.

    Cosmos DB function template in C#

    This function template writes the number of documents and the first document ID to the logs.

Next, you connect to your Azure Cosmos DB account and create the Tasks collection in the database.

Create the Items collection

  1. Open a second instance of the Azure portal in a new tab in the browser.

  2. On the left side of the portal, expand the icon bar, type cosmos in the search field, and select Azure Cosmos DB.

    Search for the Azure Cosmos DB service

  3. Choose your Azure Cosmos DB account, then select the Data Explorer.

  4. In Collections, choose taskDatabase and select New Collection.

    Create a collection

  5. In Add Collection, use the settings shown in the table below the image.

    Define the taskCollection

    Setting Suggested value Description
    Database ID Tasks The name for your new database. This must match the name defined in your function binding.
    Collection ID Items The name for the new collection. This must match the name defined in your function binding.
    Storage capacity Fixed (10 GB) Use the default value. This value is the storage capacity of the database.
    Throughput 400 RU Use the default value. If you want to reduce latency, you can scale up the throughput later.
    Partition key /category A partition key that distributes data evenly to each partition. Selecting the correct partition key is important in creating a performant collection.
  6. Click OK to create the Tasks collection. It may take a short time for the collection to get created.

After the collection specified in the function binding exists, you can test the function by adding documents to this new collection.

Test the function

  1. Expand the new taskCollection collection in Data Explorer, choose Documents, then select New Document.

    Create a document in taskCollection

  2. Replace the contents of the new document with the following content, then choose Save.

         "id": "task1",
         "category": "general",
         "description": "some task"
  3. Switch to the first browser tab that contains your function in the portal. Expand the function logs and verify that the new document has triggered the function. See that the task1 document ID value is written to the logs.

    View message in the logs.

  4. (Optional) Go back to your document, make a change, and click Update. Then, go back to the function logs and verify that the update has also triggered the function.

Clean up resources

Other quick starts in this collection build upon this quick start. If you plan to continue on to work with subsequent quick starts or with the tutorials, do not clean up the resources created in this quick start.

If you do not plan to continue, click the Resource group for the function app in the portal, and then click Delete.

Select the resource group to delete from the function app.

Next steps

You have created a function that runs when a document is added or modified in your Azure Cosmos DB.

Learn how to create functions with other kinds of triggers or how to integrate functions with other Azure services.

For more information about Azure Cosmos DB triggers, see Azure Cosmos DB bindings for Azure Functions.