Azure Cosmos DB integration

Back to list of integrations

Use the Azure Cosmos DB integration for NoSQL to query databases and create, read, update, patch, or delete items through Action Tools.

Authentication	Actions
Cosmos DB account key or resource token	(9)

​

Supported actions

Action	Use it to
List Databases	List database IDs.
List Containers	List container IDs in a database.
Query Items	Run a SQL query against a container.
Read Item	Read an item by ID and partition key.
Create Item	Create an item.
Upsert Item	Create or replace an item.
Replace Item	Replace an item by ID and partition key.
Patch Item	Apply patch operations to an item.
Delete Item	Delete an item by ID and partition key.

​

Prerequisites

• An Azure Cosmos DB for NoSQL account and its endpoint.
• An account key or resource token with access to the databases, containers, and operations used by the tools.

​

Set up the integration

1. Prepare the Cosmos DB connection

   Have the account endpoint and account key or resource token ready. If you want actions to use profile defaults, also identify the database, container, and partition key.

2. Create the auth profile

   In Integrations, select Azure Cosmos DB > Connect. On Project Auth Profiles, select New Profile > Integration Profile > Azure Cosmos DB > Continue. Configure the endpoint and key. Select Account Key or Resource Token for the token type; Account Key is the default. You can also set default database, container, and partition key values. For a resource token, you can optionally enter its expiry as an ISO timestamp for operator visibility. Select Create Profile.

3. Create the action tool

   In Tools, select New Tool > Action > Azure Cosmos DB > Continue. Select the action and auth profile, configure its inputs, and select Create Tool. Then assign the tool to an agent.

​

Action reference

Database and container action inputs are optional when you set them in the auth profile. Read Item, Replace Item, Patch Item, and Delete Item also need a partition key from the action or profile. Create Item and Upsert Item use the partition-key field in the item.

List Databases

Parameter	Type	Required	Description
limit	number	No	Maximum databases to return per page (1–500). Defaults to 100.
continuationToken	string	No	Token from the previous result to fetch the next page.

List Containers

Parameter	Type	Required	Description
database	string	No	Database to list containers from. Uses the profile default if omitted.
limit	number	No	Maximum containers to return per page (1–500). Defaults to 100.
continuationToken	string	No	Token from the previous result to fetch the next page.

Query Items

Parameter	Type	Required	Description
database	string	No	Database to query. Uses the profile default if omitted.
container	string	No	Container to query. Uses the profile default if omitted.
query	string	Yes	Cosmos DB SQL query, for example SELECT * FROM c WHERE c.status = @status.
parameters	JSON	No	Query parameters as an array of { "name": "@param", "value": ... } objects. Defaults to [].
maxItemCount	number	No	Maximum items to return per page (1–500). Defaults to 100.
continuationToken	string	No	Token from a previous result to fetch the next page.

Read Item

Parameter	Type	Required	Description
database	string	No	Database containing the item. Uses the profile default if omitted.
container	string	No	Container containing the item. Uses the profile default if omitted.
id	string	Yes	Item ID.
partitionKey	string	No	Partition key for the item. Uses the profile default if omitted.

Create Item

Parameter	Type	Required	Description
database	string	No	Database to create the item in. Uses the profile default if omitted.
container	string	No	Container to create the item in. Uses the profile default if omitted.
item	JSON	Yes	Item to create, including the container partition-key field.

Upsert Item

Parameter	Type	Required	Description
database	string	No	Database for the item. Uses the profile default if omitted.
container	string	No	Container for the item. Uses the profile default if omitted.
item	JSON	Yes	Item to create or replace, including the container partition-key field.

Replace Item

Parameter	Type	Required	Description
database	string	No	Database containing the item. Uses the profile default if omitted.
container	string	No	Container containing the item. Uses the profile default if omitted.
id	string	Yes	Item ID.
partitionKey	string	No	Partition key for the item. Uses the profile default if omitted.
item	JSON	Yes	Replacement item.

Patch Item

Parameter	Type	Required	Description
database	string	No	Database containing the item. Uses the profile default if omitted.
container	string	No	Container containing the item. Uses the profile default if omitted.
id	string	Yes	Item ID.
partitionKey	string	No	Partition key for the item. Uses the profile default if omitted.
operations	JSON	Yes	Array of Cosmos DB patch operations, such as [{"op":"replace","path":"/status","value":"active"}].

Delete Item

Parameter	Type	Required	Description
database	string	No	Database containing the item. Uses the profile default if omitted.
container	string	No	Container containing the item. Uses the profile default if omitted.
id	string	Yes	Item ID.
partitionKey	string	No	Partition key for the item. Uses the profile default if omitted.

​

Troubleshoot common issues

Issue	Resolution
Connection fails	Verify the account endpoint, key, and token type. For a resource token, check that it is still valid.
A read, replace, patch, or delete reports a missing partition key	Supply it on the action or in the auth profile. Include the container partition-key field in items you create or upsert.
A query or patch fails	Check the Cosmos DB SQL, query parameter array, or patch operation array.
An action result exceeds the output limit	Reduce the number of returned items or fields. Connector responses larger than 2 MB are rejected.

​

Related articles

• Auth profiles
• Action Tools
• Azure Cosmos DB documentation