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

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.

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

https://<cosmos-account-name>.documents.azure.cn/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

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

// 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.