Timothy Smith
In Settings under our container in our Azure Cosmos DB, we see the options that we’ll use for our template

Creating Containers with PowerShell For Azure Cosmos DB

May 30, 2019 by

In many situations, we will develop, test or prove new concepts by horizontally scaling new SQL API containers in Azure Cosmos DB over possibly using existing containers. As we’ve seen in previous tips, we can create and remove Cosmos database accounts and databases by using the Azure Portal or PowerShell’s Az module along with making some updates to the configuration, such as the RUs for performance reasons. Similarly, we can create and remove a container through the Azure Portal along with creating and removing the container with PowerShell’s Az module.

We’ll first create a container through the Portal so that we have an idea of what we’ll need for our script before we create and remove a container in PowerShell using its Az module.

Creating the Database and First Container in the Portal

For automating the creation of a container in our Azure Cosmos DB, we’ll first create our SQL API database and add a container to it through the Azure Portal. Since the portal will show us some options we’ll use, we’ll create both through the portal. We’ll select the option to also provision the RU while we name our database – in this case, ScaleDB with an RU amount of 400 RUs. While we see the message about cost, we’ll only use this database to test the creation of containers so that we can create a template for automation – once we have the template, we can remove the containers and database.

We create a SQL API database in our Azure Cosmos DB

We create a SQL API database in our Azure Cosmos DB.

Once our SQL API database is created, we’ll select the option to create a container in the database. The below image shows the options when we create the container – Container id (required), partition key (required), checkboxes about the size of the partition key and dedicated provision through the container, and the option to add a unique key. Like the image shows, we’ll only fill in the required boxes for our template.

After creating our SQL API database, we create the container in our Azure Cosmos DB

After creating our SQL API database, we create the container in our Azure Cosmos DB.

As we’ll see with the options we’ve selected, these will appear in the settings when the container is created along with other settings we don’t specify, but we’ll need to note when we create our template. This is an important point because if we want a unique key, we’ll need to ensure that this unique key is included in our template and the same if we have a custom throughput that we want to use. To simplify the template creation, I suggest creating the initial container to use the standard options that you want for other containers – especially, if you use multiple containers for scale. This does assume that our initial container will match other containers and we can create differing containers for scripting different templates.

Once our container is created within our Azure Cosmos DB, let’s look at the settings of this container in the Setting options under the container itself. We’ll see the option of the last write wins as selected for conflict resolution, conflict resolver property set, time to live as off, our partition key, and Indexing Policies. Remember, that we want our second container to have the same options as this first container’s options when we script it.

In Settings under our container in our Azure Cosmos DB, we see the options that we’ll use for our template

In Settings under our container in our Azure Cosmos DB, we see the options that we’ll use for our template.

When we look at the Indexing Policy box, we see JSON that has various specifications for our container about the indexing of this container. Because we want our second container to match these specifications, we’ll use a layered hash object to specify these and other settings for the second container’s template. The final option that we see titled excludedPaths we will remove from our hash object, as we’ll see this is automatically added to our second container even when it is not specified. If in doubt about an option, add it unless you’ve confirmed that it will be added.

Now that our first container in our Azure Cosmos DB is created through the Azure Portal and we have looked at the settings, we’ll create our template to build the second container through PowerShell.

Creating the Second Container in PowerShell

We’ll create our second container using a similar format with PowerShell’s Az module. Like other scripts where we create and remove Cosmos database accounts and databases, we will need to ensure that the Az module is installed. For our container creation script, this time we’ll name some of our objects with shorter names to organize their function – object $srv for server, $db for database and $cont for container. This also helps prevent confusion in our development as our database ($db) exists within a server ($srv) and has a container ($cont); we see this when we specify the -Name parameter in our call and the order these come in – notice how the container follows database, which follows the database type (sql) which follows the server.

In the above options for our container within our Azure Cosmos DB, we see the same selections that we saw when we created our first container in the Azure Portal. There may be times that we want to specify other options and Microsoft has a useful page showing additional options that we can specify, such as the throughput and unique indexes, if both of these are required.

When we review the template – especially compared to its creation in the Azure Portal, one point we want to consider is the how question of design just like we do with other development. If we use a standard template for our containers in our SQL API databases, designing a template for re-use in automation may save us some time. However, it’s possible each container may differ in our Azure Cosmos DB and this would require that we update the template or create another template to use, if we re-use the second template or intend to. Automation should save us time, so if we have a handful of templates and find ourselves creating containers on a regular basis, we can create the base templates for re-use. On the other hand, if each container will be different and we seldom create containers, the Azure Portal may be faster for our needs.

We confirm our second container is created in our Azure Cosmos DB in the Azure Portal

We confirm our second container is created in our Azure Cosmos DB in the Azure Portal.

Remove A Container

Now that we’ve created two containers in for our SQL API database, we’ll remove the first container that we created through the Azure Portal. When we use the function Remove-AzResource, we use the same -ResourceType for creation and removal and follow the same naming convention of specifying the Azure Cosmos DB ($srv), type of Cosmos account (sql), database ($db) and container name ($cont). We specify the -Force parameter to prevent the dialog and the function call removes the container.

Following the script call, we get a true as returned output and see that scaleone has been removed when we look at the Azure Portal for confirmation.

Conclusion

In this tip, we’ve created a container within our Azure Cosmos DB through the Azure Portal and through using PowerShell’s Az module. Our first container showed us the options to use for our second container’s template and we looked at options that we could specify for these containers. In addition, we looked at removing the containers we created through our scripts. Throughout this series, we’ve looked at creating and removing Cosmos database accounts, databases within those accounts, and containers. Depending on our testing and development needs, we may scale with any of these tools and use PowerShell for the automation of this scale, or for smaller organizations, we may find the Azure Portal appropriate for the rare situations when we need to scale.

Table of contents

Creating and Removing Azure Cosmos DBs with PowerShell
Getting and Updating Connection Information for Azure Cosmos DB
Creating and Removing Databases with PowerShell In Azure Cosmos DB
Increasing or Decreasing Scale for Azure Cosmos DB
Creating Containers with PowerShell For Azure Cosmos DB
Timothy Smith
Azure, Azure Cosmos DB, PowerShell, SQL Azure

About Timothy Smith

Tim manages hundreds of SQL Server and MongoDB instances, and focuses primarily on designing the appropriate architecture for the business model. He has spent a decade working in FinTech, along with a few years in BioTech and Energy Tech. He hosts the West Texas SQL Server Users' Group, as well as teaches courses and writes articles on SQL Server, ETL, and PowerShell. In his free time, he is a contributor to the decentralized financial industry. View all posts by Timothy Smith

168 Views