Add Items to Azure Cosmos DB - Azure Documentation

This tutorial guides you through the process of adding new items (documents) to your Azure Cosmos DB container using various SDKs. We'll cover the fundamental concepts and provide code examples.

Understanding Item Operations

In Azure Cosmos DB, data is stored as JSON documents. Adding an item means creating a new JSON document within a specified container. The Azure Cosmos DB SDKs simplify this process by providing methods to serialize your data objects into JSON and send them to the database.

Adding a Single Item

The most common way to add an item is by using the `CreateItemAsync` (or equivalent) method provided by the Azure Cosmos DB SDK. This method takes your data object and optionally a partition key value as arguments.

Example using the .NET SDK

using Microsoft.Azure.Cosmos;
using System.Threading.Tasks;

// Assume 'container' is an initialized CosmosContainer object
// Assume 'newItem' is an object representing your data

// Example data item
public class Product
{
    public string id { get; set; }
    public string name { get; set; }
    public double price { get; set; }
    public string category { get; set; }
}

// Add the item
var newItem = new Product
{
    id = Guid.NewGuid().ToString(), // Unique identifier
    name = "Laptop",
    price = 1200.50,
    category = "Electronics"
};

try
{
    // For containers with partition keys, you need to specify the partition key value
    var response = await container.CreateItemAsync(newItem, new PartitionKey(newItem.category));
    Console.WriteLine($"Item created with ID: {response.Resource.id}");
}
catch (CosmosException ex)
{
    Console.WriteLine($"Error creating item: {ex.StatusCode}");
}

from azure.cosmos import CosmosClient
import uuid

# Assume 'container' is an initialized CosmosContainer object
# Assume 'new_item' is a dictionary representing your data

# Example data item
new_item = {
    'id': str(uuid.uuid4()), # Unique identifier
    'name': 'Keyboard',
    'price': 75.99,
    'category': 'Accessories'
}

try:
    # For containers with partition keys, you need to specify the partition key value
    response = container.create_item(
        body=new_item,
        partition_key=new_item['category']
    )
    print(f"Item created with ID: {response['id']}")
except Exception as e:
    print(f"Error creating item: {e}")

// Assume 'container' is an initialized CosmosContainer object
// Assume 'newItem' is an object representing your data

// Example data item
const newItem = {
    id: require('crypto').randomBytes(16).toString('hex'), // Unique identifier
    name: 'Mouse',
    price: 25.00,
    category: 'Accessories'
};

async function createItem() {
    try {
        // For containers with partition keys, you need to specify the partition key value
        const response = await container.items.create(newItem, { partitionKey: newItem.category });
        console.log(`Item created with ID: ${response.resource.id}`);
    } catch (error) {
        console.error(`Error creating item: ${error.code} - ${error.message}`);
    }
}

createItem();

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import java.util.UUID;

// Assume 'container' is an initialized CosmosContainer object
// Assume 'newItem' is an object representing your data

// Example data item (using a simple Map for demonstration)
Map<String, Object> newItem = new HashMap<>();
newItem.put("id", UUID.randomUUID().toString()); // Unique identifier
newItem.put("name", "Monitor");
newItem.put("price", 350.00);
newItem.put("category", "Electronics");

try {
    // For containers with partition keys, you need to specify the partition key value
    CosmosItemResponse<Map> response = container.createItem(
        newItem,
        new PartitionKey((String) newItem.get("category")),
        null // Request options, can be null
    );
    System.out.println("Item created with ID: " + response.getItem().get("id"));
} catch (Exception e) {
    System.err.println("Error creating item: " + e.getMessage());
}

Adding Multiple Items (Bulk Operations)

For scenarios where you need to insert a large number of items efficiently, Azure Cosmos DB offers bulk operations. This can significantly improve performance and reduce costs compared to individual item insertions.

Considerations for Partition Keys

When adding items to a container that uses a partition key, you must provide the partition key value for each item. The partition key helps Azure Cosmos DB distribute your data and requests across physical partitions. Failing to provide a partition key when required will result in an error.

Next Steps

Now that you know how to add items, you can explore other fundamental operations: