Access Data From a Cursor

On this page

Overview

Access Cursor Contents Iteratively
Retrieve All Documents
Tailable Cursors
API Documentation

Overview

In this guide, you can learn how to access data from a cursor by using the .NET/C# Driver.

A cursor is a tool that returns the results of a read operation in iterable batches. Because a cursor holds only a subset of documents at any given time, cursors reduce both memory consumption and network bandwidth usage.

You can retrieve a cursor by using the FindSync() or FindAsync() method. You can also convert the results of the Find() method to a cursor by chaining the ToCursor() or ToCursorAsync() method.

Sample Data

The examples in this guide use the restaurants collection in the sample_restaurants database provided in the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with the .NET/C# Driver tutorial.

The examples on this page use the following Restaurant object to model the documents in the restaurants collection:

[BsonIgnoreExtraElements]
public class Restaurant
{
    public ObjectId Id { get; set; }
        
    [BsonElement("name")]
    public string Name { get; set; }
}

Access Cursor Contents Iteratively

To iterate over the contents of a cursor, use a foreach loop inside a using block. The following example retrieves documents from the restaurants collection in which the value of the name field is "Starbucks", then iterates over the results. Select the Synchronous or Asynchronous tab to see the corresponding code:

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Starbucks");
using (var cursor = collection.FindSync(filter))
{
    while (cursor.MoveNext())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Starbucks");
using (var cursor = await collection.FindAsync(filter))
{
    while (await cursor.MoveNextAsync())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

The following example performs the same operation but uses the ToCursor() method. Select the Synchronous or Asynchronous tab to see the corresponding code:

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Starbucks");
using (var cursor = collection.Find(filter).ToCursor())
{
    while (cursor.MoveNext())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Starbucks");
using (var cursor = await collection.Find(filter).ToCursorAsync())
{
    while (await cursor.MoveNextAsync())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

Retrieve All Documents

Warning

If the number and size of documents returned by your query exceeds available application memory, your program might crash. If you expect a large result set, access your cursor iteratively.

To retrieve all documents from a cursor, use the ToList() method, as shown in the following example. Select the Synchronous or Asynchronous tab to see the corresponding code:

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Dunkin' Donuts");
var results = collection.FindSync(filter).ToList();

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Dunkin' Donuts");
var results = (await collection.FindAsync(filter)).ToList();

Tailable Cursors

When querying on a capped collection, you can use a tailable cursor that remains open after the client exhausts the results in a cursor. To create a tailable cursor, create a FindOptions object and set the CursorType property to CursorType.TailableAwait. Then, pass the FindOptions object to one of the find operation methods. The following example shows how to create a tailable cursor on a capped collection. Select the Synchronous or Asynchronous tab to see the corresponding code:

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Dunkin' Donuts");
var options = new FindOptions<Restaurant>
{
    CursorType = CursorType.TailableAwait
};
using (var cursor = collection.FindSync(filter, options))
{
    while (cursor.MoveNext())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

var filter = Builders<Restaurant>.Filter.Eq(r => r.Name, "Dunkin' Donuts");
var options = new FindOptions<Restaurant>
{
    CursorType = CursorType.TailableAwait
};
using (var cursor = await collection.FindAsync(filter, options))
{
    while (await cursor.MoveNext())
    {
        foreach (var restaurant in cursor.Current)
        {
            Console.WriteLine(restaurant.Name);
        }
    }
}

API Documentation

To learn more about the methods and classes used in this guide, see the following API documentation:

Back

Distinct Field Values

Update One Document