Edit

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

  • Article

APPLIES TO: Table

Items in Azure Cosmos DB represent a specific entity stored within a table. In the API for Table, an item consists of a set of key-value pairs uniquely identified by the composite of the row and partition keys.

Create a unique identifier for an item

The unique identifier, programmatically known as the **** is a distinct string that identifies an item within a table. Each item also includes a partition key value that is used to determine the logical partition for the item. Both keys are required when creating a new item within a table.

Within the scope of a table, two items can't share both the same row key and partition key.

Create an item

The TableEntity class is a generic implementation of a dictionary that is uniquely designed to make it easy to create a new item from an arbitrary dictionary of key-value pairs.

Use one of the following strategies to model items that you wish to create in a table:

Use a built-in class

The (string rowKey, string partitionKey) constructor of the TableEntity class is a quick way to create an item with just the required properties. You can then use the Add method to add extra key-value pairs to the item.

For example, you can create a new instance of the TableEntity class by first specifying the row and partition keys in the constructor and then adding new key-value pairs to the dictionary:

// Create new item using composite key constructor
TableEntity item1 = new(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);

// Add properties to item
item1.Add("Name", "Sunnox Surfboard");
item1.Add("Quantity", 8);
item1.Add("Sale", true);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item1);

The (IDictionary<string, object>) constructor of the TableEntity class converts an existing dictionary into an item ready to be added to a table.

For example, you can pass in a dictionary to a new instance of the TableEntity class:

// Create dictionary
Dictionary<string, object> properties = new()
{
    { "RowKey", "68719518388" },
    { "PartitionKey", "gear-surf-surfboards" },
    { "Name", "Sunnox Surfboard" },
    { "Quantity", 8 },
    { "Sale", true }
};

// Create new item using dictionary constructor
TableEntity item2 = new(
    values: properties
);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item2);

The TableClient.AddEntityAsync<> method takes in a parameter of type TableEntity and then creates a server-side item in the table.

Implement interface

Note

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

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

The TableClient.AddEntityAsync<> method takes in a parameter of any type that implements the ITableEntity interface. The interface already includes the required RowKey and PartitionKey properties.

For example, you can create a new object that implements at least all of the required properties in the ITableEntity interface:

// Create new item
Product item = new()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sunnox Surfboard",
    Quantity = 8,
    Sale = true
};

You can then pass this object to the AddEntityAsync<> method creating a server-side item:

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(item);

Next steps

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

Read an item