Understanding Autopilot Mode in Azure Cosmos DB
Tags: azure, database, cosmosdb, tutorial
Published: 2020-01-31 04:07:09

---
title: Understanding Autopilot Mode in Azure Cosmos DB
published: true
date: 2020-01-31 02:39:55 UTC
tags: azure,database,cosmosdb,tutorial
canonical_url: 
---

[![](https://cdn-images-1.medium.com/max/600/0*OYBaF3hZ0_VtF7Wk.png)](https://towardsdatascience.com/understanding-autopilot-mode-in-azure-cosmos-db-105973083780?source=rss-47ee50278c96------2)

**UPDATE 12/01/2021: Autopilot has been renamed to Autoscale. Keep an eye out for a updated blog post on this in the future!**

Figuring out how much throughput you need to provision in Cosmos DB has now been made simpler with Autopilot mode!

In November 2019, [The Azure Cosmos DB team announced a bunch of cool features](https://devblogs.microsoft.com/cosmosdb/whats-new-in-azure-cosmos-db-nov-2019/) that makes developing and administrating [Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/) applications a lot easier.

My favorite feature by far is the new [Autopilot](https://docs.microsoft.com/en-us/azure/cosmos-db/provision-throughput-autopilot) mode. In this post, I’ll talk about the benefits of Autopilot mode, how you can provision databases and containers with Autopilot mode enabled and what the current limitations are (It is still a preview feature after all!)

**In the beginning**

In Azure Cosmos DB, you provision throughput to manage your workload. Before Autopilot, you had to set a hard maximum limit on how many **Request Units per second (RU/s)** a container or a database could have. This was difficult to do, as you would have to guesstimate how much throughput you would need and hope for the best.

Even if you didn’t reach the maximum limit, you were still charged for reserving it. So you might set the maximum throughput level to 10K RU/s, but only use that for 15 minutes out of the day.

There are tools that we can use to change the amount of throughput provisioned. We can use the portal (like a caveman) or use the [.NET SDK to update the amount programmatically](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.client.requestoptions.offerthroughput?view=azure-dotnet) (which just adds complexity to our code 😥).

![](https://miro.medium.com/max/978/0*ivLq1ZqYTMaG7KYi.png)

**Activate Autopilot Mode!**

![](https://miro.medium.com/max/681/0*1nn03MWrVGTGIAJh.jpg)

Enter Autopilot mode 😃 Instead of manually setting throughput ourselves, we can set Autopilot on our containers and databases in Cosmos DB, which will automatically and instantly scale the throughput provisioned without us needing to do anything nor affecting the availability of our application.

Autopilot currently works on a tiered system, where you set the maximum level of throughput that you don’t want to exceed on a container or database. Containers or Databases can then scale between 0.1(max) to the maximum value instantly. There are currently 4 tiers to choose from:

1. 4,000 RU/s *(50GB Max Storage)*
2. 20,000 RU/s *(200GB Max Storage)*
3. 100,000 RU/s *(1TB Max Storage)*
4. 500,000 RU/s *(5TB Max Storage)*

**What are the benefits of Autopilot?**

First off, it’s a lot more flexible! I can’t tell you how many times I’d have to crack out the old abacus and figure out many RU’s I’d have to provision for Cosmos (and for certain times as well).

It also makes your code a lot tidier as well. In order to get around the 429 errors, the .NET SDK does allow you to upgrade the throughput on your Databases or Containers if you’re reaching the max allocated throughput. But this wouldn’t avoid me having to work out how many RU’s I needed to meet the demand of my applications.

Autopilot can also save you some serious cash! I’ve been in situations where one engineer in our team would do some testing in Cosmos and wack up the provisioned RU’s to 20K. The test worked and everything was fine right up until we received that months bill……

![](https://miro.medium.com/max/1343/0*6_O697QT64HTKA9v.jpg)

With Autopilot, you only pay for the resources that your Cosmos DB account uses on a per hour basis. So using that 20K example, if we hit that level of RU’s required using Autopilot, we would have only have only been charged for the hours that we needed the RU level to be at 20K, rather than the whole week in which that engineer forgot to bring it back down again.

**When would I use Autopilot?**

![](https://miro.medium.com/max/389/0*2qet4FLRJKyEWJqb)

*If the workload that your Cosmos DB account receives is varied or unpredictable*, having Autopilot enabled ensures that you’ll have enough throughput provisioned to meet the demands that your workload requires. This removes the need from having to change the amount of throughput provisioned yourself, since Autopilot scales the amount up or down within a tier for you.

*If you’re developing a new application or you’re just doing a bit of testing*, having Autopilot enabled can help you assess how much throughput you’ll need to provision once you deploy your applications.

**Show me how to do it!**

Creating Databases and Containers with Autopilot on is really straight forward. I’m going to assume that you know how to provision a Cosmos DB account, so I’ll skip that just to save some time.

Let’s create a container with Autopilot enabled. *You can also enable Autopilot at a Database level if you want*, but I’ll just use container as an example. In your Cosmos DB account, click on New Container.

Like we would normally do when creating new containers in Cosmos, we would give the container a name, partition key value and either create a new database or assign it a pre-existing database. Click the option to provision dedicated throughput for the container and you should see two options:

1. **Autopilot (preview).**
2. **Manual.**

Since this is a tutorial on implementing Autopilot, you can go ahead and pick that option 😊

If this you’ll have to pick an autopilot tier for your container. Just pick the 4K tier for now and then click ‘Ok’.

![](https://miro.medium.com/max/659/1*C05ivDpvkxuy0wD5WlYdvA.png)

If you need to change the tier later, go into your containers ‘*Scale and Settings*’ tab and you can pick a new tier. You can go up or down a level, depending on what demands affect your container.

As you can see, it’s fairly simple to set up 😊

**What’s the catch?**

As things stand, there are a couple of catches you need to be aware of when it comes to Autopilot. Hopefully when the feature becomes generally available these issues will be resolved, but if you don’t want to wait that long…..

*The only way you can enable Autopilot onto your containers and databases in Cosmos is through the portal*. If you’re deploying these via CI/CD pipelines using CLI, Powershell or REST APIs, you currently won’t be able to do that.

One way I’ve managed to get around this is to provision the auto-piloted containers in the Portal and then test my deployment scripts to see if they revert back to manually provisioned containers. The good news is that the Autopilot feature remained. It’s a bit hack, but it works 🤷‍♂️

*You can’t enable autopilot on existing containers/databases* 😥 Much like if you want to change your partition key for a container, you’ll have to recreate the container again. I’m really hoping that when Autopilot goes GA, we can just update this (hint hint anyone on the Cosmos team who may read this 😊)

*You can turn off Autopilot and switch to manual, but you can’t go back again*. Again, bit of a limitation but when I’m pretty hopeful that when Autopilot goes GA, we’ll be able to chop and change as needed.

*Autopilot also takes into consideration how much storage your container/database is currently storing*. For example, if we create a container that has a maximum throughput level of 4,000RU/s, we will also have a maximum storage limit of 50GB. Once we have exceed 50GB of storage within that container, we will automatically be upgraded to 20,000 RU/s. If you don’t need to store this data in Cosmos and you want to keep your costs down, you may have to consider how you will archive data to keep within the storage limit for this Autopilot tier.

**Conclusion…**

Hopefully in this article you saw the benefits of using Autopilot in your Cosmos DB databases and containers. This is by far the end though, as it’s still a preview feature, so when it becomes generally available, I’m pretty sure I’ll have to write this post again! 😂

I can’t stress how much of a game changer this is when developing and administration applications for Cosmos DB. No longer do we have to spend time fiddling about with throughput provisioning ourselves!

As always, if you have any questions for me, feel free to ask in the comment section below!