Create an item in Azure Cosmos DB for NoSQL using .NET

Article
08/14/2024

APPLIES TO: NoSQL

Items in Azure Cosmos DB represent a specific entity stored within a container. In the API for NoSQL, an item consists of JSON-formatted data with a unique identifier.

Create a unique identifier for an item

The unique identifier is a distinct string that identifies an item within a container. The id property is the only required property when creating a new JSON document. For example, this JSON document is a valid item in Azure Cosmos DB:

{
  "id": "unique-string-2309509"
}

Within the scope of a container, two items can't share the same unique identifier.

Important

The id property is case-sensitive. Properties named ID, Id, iD, and _id will be treated as an arbitrary JSON property.

Once created, the URI for an item is in this format:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

When referencing the item using a URI, use the system-generated resource identifier instead of the id field. For more information about system-generated item properties in Azure Cosmos DB for NoSQL, see properties of an item

Create an item

Note

The examples in this article assume that you have already defined a C# type to represent your data named Product:

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

The examples also assume that you have already created a new object of type Product named newItem:

// Create new item and add to container
Product item = new(
    id: "68719518388",
    category: "gear-surf-surfboards",
    name: "Sunnox Surfboard",
    quantity: 8,
    sale: true
);

To create an item, call one of the following methods:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Create an item asynchronously

The following example creates a new item asynchronously:

Product createdItem = await container.CreateItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

The Container.CreateItemAsync<> method will throw an exception if there's a conflict with the unique identifier of an existing item. To learn more about potential exceptions, see CreateItemAsync<> exceptions.

Replace an item asynchronously

The following example replaces an existing item asynchronously:

Product replacedItem = await container.ReplaceItemAsync<Product>(
    item: item,
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

The Container.ReplaceItemAsync<> method requires the provided string for the id parameter to match the unique identifier of the item parameter.

Create or replace an item asynchronously

The following example will create a new item or replace an existing item if an item already exists with the same unique identifier:

Product upsertedItem = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

The Container.UpsertItemAsync<> method will use the unique identifier of the item parameter to determine if there's a conflict with an existing item and to replace the item appropriately.

Next steps

Now that you've created various items, use the next guide to read an item.

Read an item

Share via