Process and create Azure Cosmos DB documents using Azure Logic Apps

Applies to: Azure Logic Apps (Consumption + Standard)

From your workflow in Azure Logic Apps, you can connect to Azure Cosmos DB and work with documents by using the Azure Cosmos DB connector. This connector provides triggers and actions that your workflow can use for Azure Cosmos DB operations. For example, actions include creating or updating, reading, querying, and deleting documents.

You can connect to Azure Cosmos DB from both Logic App (Consumption) and Logic App (Standard) resource types by using the managed connector operations. For Logic App (Standard), Azure Cosmos DB also provides built-in operations, which are currently in preview and offer different functionality, better performance, and higher throughput. For example, if you're working with the Logic App (Standard) resource type, you can use the built-in trigger to respond to changes in an Azure Cosmos DB container. You can combine Azure Cosmos DB operations with other actions and triggers in your logic app workflows to enable scenarios such as event sourcing and general data processing.

Limitations

  • Currently, only stateful workflows in a Logic App (Standard) resource can use both the managed connector operations and built-in operations. Stateless workflows can use only built-in operations.

  • The Azure Cosmos DB connector supports only Azure Cosmos DB accounts created with Azure Cosmos DB for NoSQL.

Prerequisites

Add Azure Cosmos DB trigger

In Azure Logic Apps, every workflow must start with a trigger, which fires when a specific event happens or when a specific condition is met.

If you're working with the Logic App (Standard) resource type, the built-in trigger called When an item is created or modified (preview) is available and is based on the Azure Cosmos DB change feed pattern. This trigger is unavailable for the Logic App (Consumption) resource type.

No Azure Cosmos DB triggers are available for the Logic App (Consumption) resource type.

Add Azure Cosmos DB action

In Azure Logic Apps, an action is a step in your workflow that follows a trigger or another action. The Azure Cosmos DB connector offers actions for both the Logic App (Consumption) and Logic App (Standard) resource types. The following examples for each resource type show how to use an action that creates or updates a document.

To add an Azure Cosmos DB action to a logic app workflow in multi-tenant Azure Logic Apps, use the following steps:

  1. In the Azure portal, open your workflow in the designer.

  2. If your workflow is blank, add any trigger that you want.

    This example starts with the When an HTTP request is received trigger.

  3. Under the trigger or action where you want to add the Azure Cosmos DB action, select New step or Add an action, if between steps.

  4. In the designer search box, enter Azure Cosmos DB. Select the Azure Cosmos DB action that you want to use.

    This example uses the action named Create or update document (V3).

    Screenshot showing the designer for a Consumption logic app workflow with the available Azure Cosmos DB actions.

  5. If you're prompted for connection details, create a connection to your Azure Cosmos DB account now.

  6. Provide the necessary information for the action.

    Property Required Value Description
    Azure Cosmos DB account name Yes Either select Use connection settings (<Azure-Cosmos-DB-account-name>), or manually enter the name. The account name for your Azure Cosmos DB account.
    Database ID Yes <database-ID> The database that you want to connect.
    Container ID Yes <container-ID> The container that you want to query.
    Document Yes <JSON-document> The JSON document that you want to create. This example uses the request body from the trigger output.

    Tip: If the HTTP trigger's Body token doesn't appear in the dynamic content list for you to add, next to the trigger name, select See more.

    Note: Make sure that the body is well-formed JSON, and at a minimum, contains the id property and the partition key property for your document. If a document with the specified id and partition key already exist, the document is updated. Otherwise, a new document is created.

    The following image shows an example action:

    Screenshot showing the designer for a Consumption logic app workflow with the Azure Cosmos DB 'Create or update documents (V3)' action and parameters configuration.

  7. Configure any other action settings as needed.

  8. On the designer toolbar, select Save.

  9. Test your logic app to make sure your workflow creates a document in the specified container.

Connect to Azure Cosmos DB

When you add a trigger or action that connects to a service or system, and you don't have an existing or active connection, Azure Logic Apps prompts you to provide the connection information, which varies based on the connection type, for example:

  • Your account credentials
  • A name to use for the connection
  • The name for the server or system
  • The authentication type to use
  • A connection string

Before you can configure your Azure Cosmos DB trigger or Azure Cosmos DB action, you need to connect to a database account.

In a Logic App (Consumption) workflow, an Azure Cosmos DB connection requires the following property values:

Property Required Value Description
Connection name Yes <connection-name> The name to use for your connection.
Authentication Type Yes <connection-type> The authentication type that you want to use. This example uses Access key.

- If you select Access Key, provide the remaining required property values to create the connection.

- If you select Azure AD Integrated, no other property values are required, but you have to configure your connection by following the steps for Azure AD authentication and Azure Cosmos DB connector.

Access key to your Azure Cosmos DB account Yes <access-key> The access key for the Azure Cosmos DB account to use for this connection. This value is either a read-write key or a read-only key.

Note: To find the key, go to the Azure Cosmos DB account page. In the navigation menu, under Settings, select Keys. Copy one of the available key values.

Account Id Yes <acccount-ID> The name for the Azure Cosmos DB account to use for this connection.

The following image shows an example connection:

Screenshot showing an example Azure Cosmos DB connection configuration for a Consumption logic app workflow.

Note

After you create your connection, if you have a different existing Azure Cosmos DB connection that you want to use instead, or if you want to create another new connection, select Change connection in the trigger or action details editor.

Connector reference

For reference information about the Azure Cosmos DB managed connector operations, such as triggers, actions, and limits, review the connector's reference page.

No corresponding reference page exists for Azure Cosmos DB built-in operations. Instead, review the following table for more information:

Type Name Parameters
Trigger When an item is created or modified - Database Id: Required. The name of the database with the monitored and lease containers.
- Monitored Container Id: Required. The name of the container being monitored.
- Lease Container Id: Required. The name of the container used to store leases.
- Create Lease Container: Required. If true, create the lease container if not already existing.
- Lease Container Throughput: Optional. The number of Request Units to assign when the lease container is created.
Action Create or update item - Database Id: Required. The name of the database.
- Container Id: Required. The name of the container.
- Item: Required. The item to create or update.
- Partition Key: Optional. The partition key value for the requested item.
- Is Upsert: Optional. If true, replace the item, if existing. Otherwise, create the item.
Action Create or update many items in bulk This action is optimized for high throughput scenarios and has extra processing before the action submits your items to be created in the Azure Cosmos DB container. For large numbers of items, this extra processing speeds up the total request time. For small numbers of items, this extra overhead can cause slower performance than using multiple single create item actions.

- Database Id: Required. The name of the database.
- Container Id: Required. The name of the container.
- Items: Required. An array of items to create or update.
- Is Upsert: Optional. If true, replace an item if existing. Otherwise, create the item.

Action Read an item - Database Id: Required. The name of the database.
- Container Id: Required. The name of the container.
- Item Id: Required. The id value for the requested item.
- Partition Key: Required. The partition key value for the requested item.
Action Delete an item - Database Id: Required. The name of the database.
- Container Id Required. The name of the container.
- Item Id: Required. The id value for the requested item.
- Partition Key: Required. The partition key value for the requested item.
Action Query items - Database Id: Required. The name of the database.
- Container Id: Required. The name of the container.
- Sql Query: Required. The Azure Cosmos DB SQL query text.
- Partition Key: Optional. The partition key value for the request, if any.
- Continuation Token: Optional. The continuation token for this query given by the Azure Cosmos DB service, if any.
- Max Item Count: Optional. The maximum number of items for the query to return.

Best practices for Azure Cosmos DB built-in operations

Get iterable results from the Query items action

The built-in Query items action in a Logic App (Standard) workflow has many dynamic content outputs available for use in subsequent actions. To get the query result items or item metadata as an iterable object, use the following steps:

  1. In the Azure portal, open your workflow in the designer.

  2. If your workflow is blank, add any trigger that you want.

    This example starts with the Recurrence trigger.

  3. Under the trigger or action where you want to add the Azure Cosmos DB action, select Insert a new step (+) > Add an action.

  4. On the designer, make sure that Add an operation is selected. In the Add an action pane that opens, under the Choose an operation search box, select Built-in to find the Azure Cosmos DB actions.

  5. In the search box, enter Azure Cosmos DB. Select the Query items (preview) action.

  6. If you're prompted for connection details, create a connection to your Azure Cosmos DB account.

  7. Provide the necessary information for the action.

    Properties Required Value Description
    Database Id Yes <database-ID> The database that you want to connect.
    Container Id Yes <container-ID> The container that you want to query.
    SQL Query Yes <sql-query> The SQL query for your request.

    The following image shows an example action:

    Screenshot showing the designer for a Standard logic app workflow with the Azure Cosmos DB 'Query items' action and parameters configuration.

  8. Configure any other action settings as needed.

  9. Under the action, select Insert a new step (+) > Add an action. In the Add an action pane that opens, select the action that you want to run on all of the query result items.

This example uses the Azure Cosmos DB built-in action named Delete an item (preview).

  1. In the action that you previously added, you can access data from the query action output. Click inside any of the input fields in that action so that the dynamic content list appears. Select any of the available response items or select See more for more options.

This example uses the Response Item Id in the Item Id field to populate IDs based on the query results.

Screenshot showing the designer for a Standard logic app workflow with the Azure Cosmos DB **Query items** action dynamic content outputs.

  1. After you select a response item, the For each action is automatically added to iterate through all the query results. The For each loop contains the action that you previously added. You can add any other actions that you want to the loop.

  2. On the designer toolbar, select Save.

  3. Test your logic app to make sure your workflow returns the output that you expect.

Next steps

Connectors overview for Azure Logic Apps