Azure Cosmos DB Action Block

What it does: Perform data operations on Azure Cosmos DB containers and items directly from your workflow automation.

When to Use This

Use the Azure Cosmos DB action when you need to:

• ✅ Store workflow data in a globally distributed NoSQL database
• ✅ Query Cosmos DB collections based on workflow events
• ✅ Synchronize data between Cosmos DB and other systems
• ✅ Manage Cosmos DB containers programmatically
• ✅ Run SQL-like queries against JSON documents in your database

Example: When a user completes a multi-step form, store the submission as a JSON document in Cosmos DB and query related documents for personalization in subsequent steps.

Features

• Shared Key Authentication: Connect using your Cosmos DB account name and master key
• Item CRUD: Create, read, update, and delete individual documents
• SQL Queries: Run Cosmos DB SQL queries against containers
• Container Management: Create, retrieve, list, and delete containers
• Partition Key Support: Full support for partitioned containers
• Variable Support: Use workflow variables in queries and document fields

Setup

1. Get Your Cosmos DB Credentials

1. Go to the Azure Portal and navigate to your Cosmos DB account
2. Open Settings > Keys
3. Copy the Account Name (or URI) and Primary Key (master key)

2. Connect in Indite

1. Open the Azure Cosmos DB block settings
2. Enter your Account Name (e.g., mycosmosaccount)
3. Enter your Master Key (the Primary Key from Azure Portal)
4. Specify the Database ID you want to work with

3. Configure the Action

1. Select the desired Action from the dropdown
2. Specify the Container ID for item operations
3. Fill in action-specific fields (document body, query, partition key, etc.)

Supported Actions

Item Operations

Container Operations

Using Variables

You can use workflow variables in any Cosmos DB field:

Create Item (JSON Body):

{
  "id": "{{order.id}}",
  "customerId": "{{customer.id}}",
  "items": "{{order.items}}",
  "total": "{{order.total}}",
  "status": "pending",
  "createdAt": "{{date.now}}"
}

Query Items (SQL Query):

SELECT * FROM c WHERE c.customerId = '{{customer.id}}' AND c.status = 'active'

Partition Key:

{{customer.id}}

Container ID:

{{environment}}-orders

Response Mapping

Map results from Cosmos DB actions to workflow variables:

Available Values (Item Operations):

• Item ID: The document's unique identifier
• Document Body: Full JSON content of the document
• ETag: Version tag for optimistic concurrency
• Timestamp: Server-side timestamp
• Request Charge: RU (Request Unit) cost of the operation

Available Values (Query):

• Documents: Array of matching documents
• Count: Number of results returned
• Request Charge: Total RU cost of the query
• Continuation Token: Token for paginated results

Available Values (Container):

• Container ID: Container name
• Partition Key Path: The partition key path definition
• Indexing Policy: Current indexing configuration

Example Mapping:

Document → {{cosmos.document}}
Documents Array → {{cosmos.results}}
Customer Name → {{cosmos.results[0].customerName}}
Request Charge → {{cosmos.ruCost}}

Common Use Cases

1. Order Event Sourcing

Trigger: New order placed Cosmos DB Action: Create Item

{
  "id": "{{uuid.new}}",
  "orderId": "{{order.id}}",
  "eventType": "OrderCreated",
  "data": {
    "customerId": "{{customer.id}}",
    "items": "{{order.items}}",
    "total": "{{order.total}}"
  },
  "timestamp": "{{date.now}}"
}

2. Customer Profile Lookup

Trigger: Chatbot user identified Cosmos DB Action: Query Items

SELECT * FROM c WHERE c.email = '{{user.email}}' AND c.type = 'profile'

Then use the profile data to personalize the chatbot conversation.

3. IoT Data Ingestion

Trigger: IoT device webhook Cosmos DB Action: Create Item

{
  "id": "{{device.id}}-{{timestamp.epoch}}",
  "deviceId": "{{device.id}}",
  "temperature": "{{sensor.temperature}}",
  "humidity": "{{sensor.humidity}}",
  "recordedAt": "{{date.now}}"
}

4. Multi-Container Data Aggregation

Trigger: Schedule (Hourly) Cosmos DB Actions: Query from multiple containers

Step 1: Query orders container for recent orders
Step 2: Query inventory container for stock levels
Step 3: Combine results and write to analytics container

Best Practices

Query Optimization

• ✅ Always include the partition key in queries for efficient routing
• ✅ Use specific SELECT fields instead of SELECT * when you only need certain properties
• ✅ Add filters to reduce the number of documents scanned
• ✅ Monitor Request Unit (RU) consumption through response mapping

Data Modeling

• ✅ Design partition keys around your most common query patterns
• ✅ Keep documents under 2 MB for optimal performance
• ✅ Use meaningful, deterministic document IDs
• ✅ Include a type field to distinguish different document types in the same container

Cost Management

• ✅ Monitor RU costs through the Request Charge response value
• ✅ Avoid cross-partition queries when possible -- they consume more RUs
• ✅ Use Get Item (point read) instead of queries when you know the ID and partition key
• ✅ Clean up unused containers to reduce provisioned throughput costs

Security

• ✅ Rotate master keys periodically through Azure Portal
• ✅ Never log or expose the master key in workflow outputs
• ✅ Use separate databases or containers for different security levels
• ✅ Consider using Cosmos DB RBAC instead of master keys when supported

Troubleshooting

Authentication Failed

Check:

• The account name matches your Cosmos DB account exactly (case-sensitive)
• The master key is the full Primary or Secondary key from Azure Portal
• The key has not been regenerated since it was configured

Item Not Found

Solutions:

• Verify both the item ID and partition key value are correct
• Partition key value must match exactly (including case for string keys)
• Use Query Items to search by other fields if the ID is uncertain

Query Returns No Results

Check:

• The SQL syntax is correct for Cosmos DB (it uses a subset of SQL)
• String values in WHERE clauses are enclosed in single quotes
• The container alias matches (default is c as in SELECT * FROM c)
• The partition key filter matches existing documents

Request Rate Too Large (429)

Solutions:

• Reduce the frequency of requests to the container
• Increase the provisioned RU/s for the container in Azure Portal
• Add retry logic in the workflow using condition blocks
• Optimize queries to consume fewer RUs

Limitations

• Document Size: Maximum document size is 2 MB
• Query Complexity: Cosmos DB SQL supports a subset of SQL -- no JOINs across containers
• Transactions: Cross-partition transactions are not supported through this block
• Stored Procedures: Execution of server-side stored procedures is not available
• Change Feed: Real-time change feed listening is not supported (use scheduled polling instead)
• Throughput: Operations are subject to provisioned RU/s limits on the container

Related Blocks

• Microsoft SQL: For relational database operations
• Azure Storage: Store large files referenced by Cosmos DB documents
• Condition: Add logic based on query results
• Loop: Iterate over query result arrays
• Set Variable: Prepare JSON documents before writing to Cosmos DB