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

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.

Reading items using the composite key

Every item in Azure Cosmos DB for Table has a unique identifier specified by the composite of the row and partition keys. These composite keys are stored as the RowKey and PartitionKey properties respectively. Within the scope of a table, two items can't share the same unique identifier composite.

Azure Cosmos DB requires both the unique identifier and the partition key value of an item to perform a read of the item. Specifically, providing the composite key will perform a quick point read of that item with a predictable cost in request units (RUs).

Read an item

To perform a point read of an item, use one of the following strategies:

• Return a TableEntity object using GetEntityAsync<>
• Return an object of your own type using GetEntityAsync<>

Read an item using a built-in class

The following example point reads a single item asynchronously and returns the results deserialized into a dictionary using the built-in TableEntity type:

// Read existing item from server-side table
TableEntity readItem = await tableClient.GetEntityAsync<TableEntity>(
    partitionKey: "68719518388",
    rowKey: "gear-surf-surfboards"
);

The TableClient.GetEntityAsync<TableEntity> method reads an item and returns an object of type Response<TableEntity>. The Response<> type contains an implicit conversion operator to convert the object into a **TableEntity`` object.

Read an item using your own type

// 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 following example point reads a single item asynchronously and returns a deserialized item using the provided generic type:

// Read existing item from server-side table
Product readItem = await tableClient.GetEntityAsync<Product>(
    partitionKey: "68719518388",
    rowKey: "gear-surf-surfboards"
);

The TableClient.GetEntityAsync<> method reads an item and returns an object of type Response<>. The Response<> type contains an implicit conversion operator to convert the object into the generic type. To learn more about implicit operators, see user-defined conversion operators.

Next steps

Now that you've read various items, try one of our tutorials on querying Azure Cosmos DB for Table data.