Azure Cosmos DB

Form.io's data model it driven by MongoDB. In Azure the equivalent offering is Azure Cosmos DB for Mongo DB. Azure Cosmos DB offers globally distributed, low-latency, and scalable performance.

Setup

Before continuing please see the section for Cosmos DB Version Compatibility.

Form.io requires a MongoDB compatible database to run its platform. While you could setup a stand alone MongoDB or even use MongoDB Atlas, for Azure, it is also perfectly reasonable to use Cosmos DB for the database. Follow these instructions to setup a new database.

1. In the left-hand column, click on the menu item that says Azure Cosmos DB.

2. Click on the + Create button

3. When asked "Which API best suits your workload?" select Azure Cosmos DB for MongoDB

1. On the Basics enter these settings.

   • Under Project Details choose a Subscription

   • Under Project Details choose a Resource Group

   • Under Instance Details enter an Account Name.

   • Under Instance Details select a Region of you choice.

   • Under Instance Details select the Capacity Mode.

   • Under Instance Details uncheck Limit total account throughput.

1. You can then press Review + create button, you will then wait few moments for the database to create.

2. After the database has finished settings up on the left column you will select the Connection Strings tab.

1. Form.io does require that you use a standard connection string, so you will need to make a small change to what Azure provides you by adding your database name to the connection string.

   • This is placed right after the formio.documents.azure.com:10255/ and before the text ?ssl=true. It should look like the following.

mongodb://formio-developer-cosmos-db:[PASSWORD]@formio-developer-cosmos-db.mongo.cosmos.azure.com:10255/formio?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@formio-developer-cosmos-db@

Version Compatibility

This section will be dedicated to defining changes as they relate to Form.io between Cosmos DB versions. Currently Form.io supports the latest version of Cosmos DB (at the time of writing is 6.0).

If you run into any issues as it relates version compatibility and is not defined below please consult the Related Content section of the Azure Documentation for Upgrade the API version of your Azure Cosmos DB for MongoDB account.

If you an incompatibility is found, please provide details by contacting [e-mail].

API Version 3.6 Notes

In order to do a sort on a property, there must be an index set. This is different from how MongoDB works as MongoDB allows sorting on any property regardless of an index being set.

To resolve this, a wildcard index can be added to the following collections:

db.submissions.createIndex( {"$**": 1 } );
db.forms.createIndex( {"$**": 1 } );
db.projects.createIndex( {"$**": 1 } );
db.actions.createIndex( {"$**": 1 } );
db.roles.createIndex( {"$**": 1 } );

Partial Support for $lookup

Cosmos DB supports basic $lookup operations for equality matches but does not support advanced features like uncorrelated subqueries. For complex join operations, consider restructuring your data model or using alternative methods.

The $lookup aggregation does not yet support the uncorrelated subqueries feature that's introduced in server version 3.6. If you attempt to use the $lookup operator with the let and pipeline fields, an error message that indicates that let is not supported appears.

Cosmos Feature Support Matrix

Feature	Context	3.6	4.2	5.0	6.0
find	Query and Write Operation	Yes	Yes	Yes	Yes
insert	Query and Write Operation	Yes	Yes	Yes	Yes
update	Query and Write Operation	Yes	Yes	Yes	Yes
delete	Query and Write Operation	Yes	Yes	Yes	Yes
aggregate	Aggregation Command	Yes	Yes	Yes	Yes
count	Aggregation Command	Yes	Yes	Yes	Yes
addFields	Aggregation Stage	Yes	Yes	Yes	Yes
count	Aggregation Stage	Yes	Yes	Yes	Yes
group	Aggregation Stage	Yes	Yes	Yes	Yes
limit	Aggregation Stage	Yes	Yes	Yes	Yes
lookup	Aggregation Stage	Partial	Partial	Partial	Partial
match	Aggregation Stage	Yes	Yes	Yes	Yes
project	Aggregation Stage	Yes	Yes	Yes	Yes
skip	Aggregation Stage	Yes	Yes	Yes	Yes
sort	Aggregation Stage	Yes	Yes	Yes	Yes
unwind	Aggregation Stage	Yes	Yes	Yes	Yes
and	Boolean Expression	Yes	Yes	Yes	Yes
or	Boolean Expression	Yes	Yes	Yes	Yes
setIntersection	Set Expression	Yes	Yes	Yes	Yes
eq	Comparison Expression	Yes	Yes	Yes	Yes
gt	Comparison Expression	Yes	Yes	Yes	Yes
gte	Comparison Expression	Yes	Yes	Yes	Yes
lt	Comparison Expression	Yes	Yes	Yes	Yes
lte	Comparison Expression	Yes	Yes	Yes	Yes
ne	Comparison Expression	Yes	Yes	Yes	Yes
in	Comparison Expression	Yes	Yes	Yes	Yes
nin	Comparison Expression	Yes	Yes	Yes	Yes
concatArrays	Array Expression	Yes	Yes	Yes	Yes
filter	Array Expression	Yes	Yes	Yes	Yes
reduce	Array Expression	Yes	Yes	Yes	Yes
size	Array Expression	Yes	Yes	Yes	Yes
in	Array Expression	Yes	Yes	Yes	Yes
sum	Accumulator Expression	Yes	Yes	Yes	Yes
push	Accumulator Expression	Yes	Yes	Yes	Yes
addToSet	Accumulator Expression	Yes	Yes	Yes	Yes
String	Type	Yes	Yes	Yes	Yes
Object	Type	Yes	Yes	Yes	Yes
Array	Type	Yes	Yes	Yes	Yes
ObjectId	Type	Yes	Yes	Yes	Yes
Boolean	Type	Yes	Yes	Yes	Yes
and	Logical Operator	Yes	Yes	Yes	Yes
or	Logical Operator	Yes	Yes	Yes	Yes
exists	Element Operator	Yes	Yes	Yes	Yes
regex	Evaluation Query Operator	Yes	Yes	Yes	Yes
all	Array Operator	Yes	Yes	Yes	Yes
elemMatch	Array Operator	Yes	Yes	Yes	Yes
size	Array Operator	Yes	Yes	Yes	Yes
set	Update Operator	Yes	Yes	Yes	Yes
rename	Update Operator	Yes	Yes	Yes	Yes
unset	Update Operator	Yes	Yes	Yes	Yes
addToSet	Array Update Operator	Yes	Yes	Yes	Yes
pull	Array Update Operator	Yes	Yes	Yes	Yes
push	Array Update Operator	Yes	Yes	Yes	Yes
sort	Update Modifier	Yes	Yes	Yes	Yes
Single Field Index	Indexes	Yes	Yes	Yes	Yes
Compound Index	Indexes	Yes	Yes	Yes	Yes
Multikey Index	Indexes	Yes	Yes	Yes	Yes
Text Index	Indexes	No	No	No	No
2dsphere	Indexes	Yes	Yes	Yes	Yes
2d Index	Indexes	No	No	No	No
Hashed Index	Indexes	No	No	No	No
TTL	Index Properties	Yes	Yes	Yes	Yes
Unique	Index Properties	Yes	Yes	Yes	Yes
Partial	Index Properties	No	Only unique indexes	Only unique indexes	Only unique indexes
Case Insensitive	Index Properties	No	No	No	No
Sparse	Index Properties	No	No	No	No
Background	Index Properties	Yes	Yes	Yes	Yes