AZURE COSMOS DB n8n INTEGRATION: AUTOMATE AZURE COSMOS DB WITH N8N

The Query items action lets you execute SQL-like queries against your Cosmos DB containers, giving you precise control over which documents you retrieve. This is your go-to action when you need filtered, sorted, or aggregated data rather than fetching everything.

Key parameters:

• Credential to connect with: Select your Azure Cosmos DB credentials from the dropdown. Required.
• Resource: Set to "Item" for querying documents within containers. Required.
• Container: Specify which container to query, either by selecting from available containers or entering an ID directly. Required.
• Query: Write your SQL query here (e.g., SELECT * FROM c WHERE c.status = 'active'). This text field accepts Cosmos DB SQL syntax. Required.
• Simplify: Toggle this on to receive cleaner, flattened output—useful when you don't need the full metadata envelope. Optional.
• Options: Add query parameters here to prevent SQL injection. Instead of embedding values directly in your query, use parameterized queries for security.

Use cases:

• Retrieve all orders placed in the last 24 hours for daily reporting
• Find customers matching specific criteria before sending targeted email campaigns
• Aggregate sales data by region for dashboard updates
• Search for documents containing specific keywords or tags

Use Query items when you need flexibility beyond simple ID lookups—filtering by date ranges, status fields, nested properties, or combining multiple conditions.

The Update item action modifies an existing document in your Cosmos DB container. It's essential for keeping your data current without needing to delete and recreate documents—preserving document IDs and maintaining referential integrity.

Key parameters:

• Credential to connect with: Your Azure Cosmos DB authentication credentials. Required.
• Container: The container where your target item lives. Select by ID or use an expression for dynamic selection. Required.
• Item: Identify which document to update by its ID. Required.
• Item Contents: Provide the complete updated JSON document. This replaces the existing document content, so include all fields you want to retain. Required.
• Additional Fields: Add a Partition Key if your container uses partitioning—essential for correctly locating the document. Optional.

Use cases:

• Update customer profiles when they modify their account settings
• Mark orders as "shipped" when fulfillment is confirmed
• Increment view counters or engagement metrics
• Sync updated records from external systems like Salesforce or HubSpot

💡 Pro tip: Always include the document's id field in your Item Contents JSON, and remember that updates are full replacements—any fields you omit will be removed from the document.

The Delete item action permanently removes a document from your Cosmos DB container. Use it for cleanup operations, GDPR compliance requests, or removing obsolete data from your database.

Key parameters:

• Credential to connect with: Authentication credentials for your Cosmos DB account. Required.
• Container: Specify the container containing the item to delete, selectable by ID. Required.
• Item: The document ID of the item you want to remove. Required.
• Additional Fields: Include a Partition Key if your container is partitioned—without it, the delete operation will fail. Optional but often necessary.

Use cases:

• Automatically purge expired session data on a scheduled basis
• Remove customer records upon deletion requests (GDPR/CCPA compliance)
• Clean up test data after automated testing workflows
• Delete processed queue items after successful handling

Always double-check your item selection logic in automated workflows—deletions are irreversible. Consider implementing a "soft delete" pattern (updating a status field) before permanent removal for critical data.

The Get container action retrieves metadata and configuration details about a specific container in your Cosmos DB account. It's useful for validation, monitoring, and dynamic workflow logic based on container properties.

Key parameters:

• Credential to connect with: Your Azure Cosmos DB credentials. Required.
• Resource: Fixed to "Container" for this action. Required.
• Operation: Set to "Get" to retrieve container information. Required.
• Container: Identify the container by ID or through an expression. Required.
• Simplify: Enable to receive streamlined output without extensive metadata. Optional.

Use cases:

• Verify a container exists before attempting write operations
• Retrieve container throughput settings for monitoring dashboards
• Check partition key configuration as part of data validation workflows
• Audit container properties across multiple Cosmos DB accounts

This action is particularly valuable in error-handling branches—check if a container exists before creating items, or log container configurations for debugging purposes.

The Create item action adds a new document to your specified Cosmos DB container. It's the foundation for any workflow that needs to store new data—from webhook payloads to transformed records from other systems.

Key parameters:

• Credential to connect with: Select your Azure Cosmos DB authentication credentials. Required.
• Container: The target container where the new item will be created. Required.
• Item Contents: A JSON object representing your new document. Must include an id field with a unique identifier. Accepts dynamic expressions for building documents from workflow data. Required.

Use cases:

• Store incoming webhook payloads from Stripe, GitHub, or custom applications
• Create customer records when new leads are captured in forms
• Log audit trails for compliance and debugging
• Archive processed data for historical analysis

Important: Every document requires a unique id field. If you're inserting data from external sources, generate UUIDs or use meaningful composite keys (like customerid_timestamp) to ensure uniqueness.

The Create container action provisions a new container within your Cosmos DB database. Use it for automated infrastructure setup, multi-tenant architectures, or dynamic data partitioning strategies.

Key parameters:

• Credential to connect with: Your Azure Cosmos DB account credentials. Required.
• ID: A unique identifier for the new container (e.g., "orders-2024" or "tenant-abc"). Required.
• Partition Key: A JSON object defining your partitioning strategy. Includes paths (array of partition key paths like "/customerId"), kind (typically "Hash"), and version (usually 2). Required.
• Additional Fields: Configure optional settings like indexing policies, TTL, or throughput. Optional.

Partition Key example:

{
  "paths": ["/customerId"],
  "kind": "Hash",
  "version": 2
}

Use cases:

• Automatically create containers for new tenants in multi-tenant applications
• Set up date-based containers for time-series data archival
• Provision test environments with identical container structures
• Initialize database infrastructure as part of CI/CD pipelines

Choose your partition key carefully—it determines data distribution and query efficiency. Good candidates include customer IDs, regions, or dates depending on your access patterns.

The Get item action retrieves a single document from your Cosmos DB container using its unique identifier. It's the most efficient way to fetch a known document—faster and cheaper than running a query.

Key parameters:

• Credential to connect with: Your authentication credentials. Required.
• Container: The container housing your target document. Required.
• Item: The document ID you want to retrieve. Required.
• Simplify: Toggle to return cleaner output without Cosmos DB metadata. Optional.
• Additional Fields: Specify a Partition Key for faster lookups in partitioned containers. Optional but recommended.

Use cases:

• Fetch customer details before sending personalized notifications
• Retrieve order information for status update workflows
• Load configuration documents that control workflow behavior
• Validate that a record exists before processing related data

💡 Performance tip: Always provide the Partition Key when you know it—this enables point reads, which are the fastest and most cost-effective Cosmos DB operations.

The Delete container action permanently removes a container and all its documents from your Cosmos DB account. Use with extreme caution—this operation is irreversible.

Key parameters:

• Credential to connect with: Your Azure Cosmos DB credentials. Required.
• Resource: Fixed to "Container". Required.
• Container: Identify the container to delete by ID or expression. Required.

Use cases:

• Clean up temporary containers after batch processing jobs
• Remove tenant containers when accounts are closed
• Delete test containers after automated testing completes
• Decommission deprecated data stores as part of migration workflows

⚠️ Warning: Always implement safeguards—confirmation steps, approval workflows, or at minimum, logging—before automated container deletion. Consider backing up critical data before running this action in production.

The Get many items action retrieves multiple documents from a container without requiring a specific query. It's ideal for bulk data extraction, synchronization tasks, or when you need to process all records in a container.

Key parameters:

• Credential to connect with: Your Azure Cosmos DB credentials. Required.
• Container: The container from which to retrieve items. Optional (leave empty to work with default behaviors).
• Return All: Enable this toggle to fetch every document in the container, regardless of count. Optional.
• Limit: When Return All is disabled, specify the maximum number of items to retrieve (default: 50). Optional.
• Simplify: Enable for cleaner, flattened output. Optional.

Use cases:

• Export all products to update an external catalog system
• Sync entire customer lists to email marketing platforms
• Batch process documents for data transformation or enrichment
• Generate comprehensive reports from all container data

💡 Pagination tip: For large containers, consider using the Limit parameter with multiple workflow iterations rather than Return All, which can be memory-intensive for massive datasets.

The Get many containers action lists all containers within your Cosmos DB database. It's valuable for discovery, inventory management, and building dynamic workflows that adapt to your database structure.

Key parameters:

• Credential to connect with: Authentication credentials for your Cosmos DB account. Required.
• Resource: Fixed to "Container". Required.
• Return All: Toggle to retrieve every container without limits. Optional.
• Limit: Maximum number of containers to return when Return All is off (default: 50). Optional.
• Simplify: Enable for streamlined output format. Optional.

Use cases:

• Audit all containers across your Cosmos DB accounts
• Build dynamic dropdowns in internal tools showing available containers
• Monitor container counts as part of infrastructure health checks
• Generate documentation of your database structure automatically

This action pairs well with loops in n8n—iterate through all containers to perform bulk operations like backup verification or configuration audits.