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

Reading items with unique identifiers

Every item in Azure Cosmos DB for NoSQL has a unique identifier specified by the id property. Within the scope of a container, two items can't share the same unique identifier. However, Azure Cosmos DB requires both the unique identifier and the partition key value of an item to perform a quick point read of that item. If only the unique identifier is available, you would have to perform a less efficient query to look up the item across multiple logical partitions. To learn more about point reads and queries, see optimize request cost for reading data.

Read an item

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

To perform a point read of an item, call one of the following methods:

• ReadItemAsync<>
• ReadItemStreamAsync<>
• ReadManyItemsAsync<>

Read an item asynchronously

The following example point reads a single item asynchronously and returns a deserialized item using the provided generic type:

// Read existing item from container
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

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

Alternatively, you can return the ItemResponse<> generic type and explicitly get the resource. The more general ItemResponse<> type also contains useful metadata about the underlying API operation. In this example, metadata about the request unit charge for this operation is gathered using the RequestCharge property.

// Read existing item from container
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get response metadata
double requestUnits = readResponse.RequestCharge;
HttpStatusCode statusCode = readResponse.StatusCode;

// Explicitly get item
Product readItemExplicit = readResponse.Resource;

Read an item as a stream asynchronously

This example reads an item as a data stream directly:

// Read existing item from container
using ResponseMessage readItemStreamResponse = await container.ReadItemStreamAsync(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get stream from response
using StreamReader readItemStreamReader = new(readItemStreamResponse.Content);

// (optional) Get stream content
string content = await readItemStreamReader.ReadToEndAsync();

The Container.ReadItemStreamAsync method returns the item as a Stream without deserializing the contents.

If you aren't planning to deserialize the items directly, using the stream APIs can improve performance by handing off the item as a stream directly to the next component of your application. For more tips on how to optimize the SDK for high performance scenarios, see SDK performance tips.

Read multiple items asynchronously

In this example, a list of tuples containing unique identifier and partition key pairs are used to look up and retrieve multiple items:

// Create partition key object
PartitionKey partitionKey = new("gear-surf-surfboards");

// Create list of tuples for each item
List<(string, PartitionKey)> itemsToFind = new()
{
    ("68719518388", partitionKey),
    ("68719518381", partitionKey)
};

// Read multiple items
FeedResponse<Product> feedResponse = await container.ReadManyItemsAsync<Product>(
    items: itemsToFind
);

foreach (Product item in feedResponse)
{
    Console.WriteLine($"Found item:\t{item.name}");
}

Container.ReadManyItemsAsync<> returns a list of items based on the unique identifiers and partition keys you provide. This operation is meant to perform better latency-wise than a query with IN statements to fetch a large number of independent items.

Next steps

Now that you've read various items, use the next guide to query items.