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
TableEntityobject usingGetEntityAsync<> - 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
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 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"
);
Important
The generic type you use with the TableClient.GetEntityAsync<> method must implement the ITableEntity interface.
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.