Edit

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

  • Article
  • 2 minutes to read

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:

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