Using Microsoft Azure CosmosDB

You can connect Firely Server to CosmosDB the same way you connect to MongoDB. There are a few limitations that we will work out later. They are listed below.


You cannot use CosmosDb for the Firely Server Administration database. Use SQLite instead.

  1. Create a CosmosDB account on Azure, see the Quickstart Tutorial

  2. Make sure you choose the MongoDB API

  3. In the Azure Portal, open your CosmosDB account and go to the ‘Connection Strings’ blade. Copy the ‘Primary Connection String’ to your clipboard.

  4. Now on your own machine, navigate to your Firely Server working directory

  5. Changing a setting means overriding it as described in Changing the settings.

  6. Find the Repository setting:

    "Repository": "Sqlite",
  7. Change the setting to CosmosDb

  8. If you have your own database in CosmosDB already, change the CosmosDbOptions to reflect your settings:

    "CosmosDbOptions": {
        "ConnectionString": "<see below>",
        "EntryCollection": "vonkentries",
        "SimulateTransactions": "false"

    Paste the ConnectionString from step 3, and add the databasename that you want to use. The connectionstring looks like this:


    You can add the databasename after the portnumber, like this:

  9. If your CosmosDB account does not have a database or collection by this name, Firely Server will create it for you.

  10. You can set SimulateTransactions to “true” if you want to experiment with FHIR transactions. Firely Server does not utilize the CosmosDB way of supporting real transactions across documents, so in case of an error already processed entries will NOT be rolled back.

CosmosDB Request Units

If you upload a lot of data in a short time (as is done on reindexing), you quickly exceed the default maximum of 1000 Request Units / second. If you encounter its limits, the Firely Server log will contain errors stating ‘Request rate is large’. This is likely to happen upon reindexing or when using Vonkloader. Solutions are:

  • Raise the limit to at least 5000 RU/s. See the Microsoft documentation for instructions.

  • Lower the load

    • on Reindexing, lower the MaxDegreeOfParallelism, see this warning

    • with Vonkloader, lower the value of the -parallel parameter.


  1. Request size for insertions to CosmosDB is limited to around 5 MB. Some bundles in the examples from the specification exceed that limit. Then you will get an error stating ‘Request size too large’. You can avoid this by limiting the size of incoming resources in the SizeLimits setting.

  2. The CosmosDB implementation of the MongoDB API is flawed on processing $not on arrays. This inhibits the use of these searches in Firely Server:

    • Using the :not modifier

    • Using :missing=true