Azure Cosmos DB trigger node
Azure Cosmos DB Trigger Node
Start one pipeline run for each item created or updated in an Azure Cosmos DB container, read from its change feed.
- Starts on
- Item created or updated
- Deletes
- Do not start a run
- Tracked items
- 1000 by default, max 10000
- Scaling
- One replica only
Overview
The Azure Cosmos DB Trigger Node starts a pipeline for each item created or updated in a container. Unlike the Azure Cosmos DB connector nodes, which read and write within an already-running pipeline, the trigger starts new executions in response to changes.
One changed item is one pipeline run. A batch that writes three items starts three runs.
How it works
The connector reads the container's change feed, the ordered record of writes Cosmos DB keeps for every container. It asks for new changes every Poll Interval; when a read comes back full, it reads again at once instead of waiting, so a busy container does not fall behind. Each changed item becomes a pipeline execution carrying:
- the item, as it is now, at
$trigger.result - which item changed, and where it sits in the feed, at
$trigger._metadata
The change feed reports the latest version of each item that was created or updated. Two things follow from that:
- Deletes do not start a run. A deleted item is simply gone from the feed. To react to deletions, mark items deleted with a field (and a TTL to remove them later) instead of deleting them.
- Rapid updates collapse. An item written twice between two reads starts one run, carrying its latest content.
Configuration
| Field | Required | Description |
|---|---|---|
| Azure Cosmos DB Connection | yes | The connection whose database holds the container |
| Change Feed Function | yes | An azurecosmosdb.change.feed function. Its container, start point and partition key decide which changes start the pipeline |
| Trigger Mode | no | Always fires on every change; On Change fires only when the item's fields differ from the last state it delivered |
| Max Tracked Items | no | On Change only: how many items keep a last-seen state (default 1000, max 10000) |
| Enable Trigger | no | When off, the feed is not read and no change starts the pipeline |
The container, Start From, Partition Key, Poll Interval and Max Items Per Poll all live on the function, not the node; see the connection guide.
Trigger modes
Always runs the pipeline for every change the feed delivers.
On Change compares each item with the last state that item produced and suppresses a repeat. The comparison ignores _etag and _ts, which Cosmos DB rewrites on every write, so a write that stores the same fields again, such as a replayed upsert, does not start a run. Items are compared one by one: two items that happen to hold the same fields do not suppress each other.
Start From
| Start From | What fires |
|---|---|
now | Only changes made after the trigger starts, counted from the start of that second |
beginning | Every item in the container first, then every later change |
The feed position is kept in memory. When MaestroHub restarts, the trigger starts again from this setting: now skips the changes made while it was down, and beginning replays the whole container.
Output
$trigger.result
The changed item as plain JSON: the container's own fields, plus _etag and _ts. The resource-link properties _rid, _self, _attachments and _lsn are removed.
$trigger._metadata
| Key | Example | Description |
|---|---|---|
protocol | azurecosmosdb | Always azurecosmosdb |
container | readings | The container the feed belongs to |
id | r-1027 | The changed item's id |
partitionKey | press-1 | The item's partition key, written the way the Partition Key field accepts it |
etag | "0a00c2e4-…" | The item's ETag after the change, usable as If-Match |
lsn | 1027 | The change's position in its partition's feed |
modifiedAt | 2026-09-29T13:33:40Z | When the write happened (the item's _ts) |
connectionId | - | The connection that delivered it |
functionId | - | The change feed function that delivered it |
id and partitionKey together identify the item (an id is only unique inside its partition), so pass both into a Read Item or Patch Item downstream.
Scaling
An Azure Cosmos DB connection is exclusive: only one replica runs it.
The feed's position is held in memory rather than in a lease container, so a second replica would read the same feed from its own position and start every run twice.
Common Use Cases
- Process new work: follow an
orderscontainer and run the fulfilment pipeline for each new order - React to a status change: follow a machines container with Trigger Mode
On Change, and branch on the status field - Mirror writes into another system: follow a container from the beginning once, then keep forwarding each change
- Scope to one line: set Partition Key on the function to follow only one partition's changes
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The trigger never fires | The trigger or the pipeline is disabled | Both have their own switch; check each |
| The trigger never fires for deletes | The change feed does not report deletes | Soft-delete with a field and a TTL |
| A flood of runs at startup | Start From is beginning | Use now unless you want the container replayed |
| Changes made during a restart never ran | Start From now resumes from the restart, not from where it stopped | Use beginning and On Change if a gap is not acceptable |
| Fewer runs than writes | Several writes to one item between two reads collapse into one | Expected: each run carries the item's latest content |
Subscribe fails with container "…" not found | A typo in the function's container | Container names are case-sensitive |
Related
- Azure Cosmos DB connection guide: connection setup and the eight function types
- Azure Cosmos DB nodes: reading and writing items inside a pipeline