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

Straipsnis
08/14/2024

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

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.

Query Azure Cosmos DB by using the API for Table

Bendrinti naudojant