MSDN Documentation

Create a Container in Azure Cosmos DB

This tutorial guides you through the process of creating a container in your Azure Cosmos DB account. Containers are the fundamental units of scalability and throughput in Azure Cosmos DB. They are schema-agnostic and can contain any number of JSON documents.

Prerequisites

• An Azure subscription.
• An existing Azure Cosmos DB account. If you don't have one, you can create one by following the "Create an Azure Cosmos DB Account" tutorial.

Steps to Create a Container

You can create a container using the Azure portal, Azure CLI, Azure PowerShell, or SDKs. Here, we'll focus on the Azure portal method.

1. Navigate to your Azure Cosmos DB Account:

   Log in to the Azure portal. In the search bar at the top, type "Azure Cosmos DB" and select it. Then, select your existing Azure Cosmos DB account from the list.

2. Access the Data Explorer:

   In your Azure Cosmos DB account's navigation menu, under the "Data Explorer" section, select "Data Explorer".

3. Create a New Container:

   In the Data Explorer, expand your existing database. You'll see an option to create a new container. Click on "New Container".

   Note: If you haven't created a database yet, you'll need to create one first. You can do this by clicking "New Database" in the Data Explorer.
4. Configure Container Settings:

   A panel will appear with the following fields:

   • Database ID: Select the database where you want to create the container.
   • Container ID: Enter a unique name for your container (e.g., MyItems). Container IDs are case-sensitive.
   • Partition Key: This is a crucial setting for performance and scalability. Choose a property from your documents that has a high cardinality (many unique values) and will distribute your data evenly. For example, if your documents have a userId property, that's often a good choice. Enter the path to your partition key property (e.g., /userId).
   • Throughput: You can provision throughput in two ways:
     • Manual: Specify a fixed Request Units per second (RU/s) (e.g., 400 RU/s).
     • Autoscale: Azure will automatically scale throughput up and down based on your workload, up to a maximum RU/s you define.
     For learning purposes, you can start with a low manual throughput.
5. Confirm and Create:

   Review your settings and click "OK" or "Create" to provision your new container. It may take a few moments for the container to be created.

Understanding Partition Keys

The partition key is essential for distributing your data and requests across logical partitions within Azure Cosmos DB. A well-chosen partition key:

• Ensures even data distribution.
• Maximizes query performance by minimizing cross-partition queries.
• Helps achieve higher throughput.

Common choices for partition keys include user IDs, tenant IDs, or timestamps.

Example: JSON Document Structure

Once your container is created, you can add JSON documents to it. Here's an example of a document that could be stored in a container partitioned by /categoryId:

{
    "id": "f8f7d20e-13b8-4e5d-8c1d-2f9a5b2c8d0e",
    "name": "Azure Cosmos DB: Getting Started",
    "description": "A comprehensive guide to Azure Cosmos DB.",
    "categoryId": "database-services",
    "tags": ["cosmosdb", "azure", "nosql"],
    "creationDate": "2023-10-27T10:00:00Z"
}

Next Steps

Now that you have created a database and a container, you can proceed to add items (documents) to your container and then query them.

• Add Items to Your Container
• Query Items in Your Container