Retrieve Distinct Field Values

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Quick Start.

The examples on this page uses the following Restaurant class to model the documents in the collection:

public class Restaurant {
    public ObjectId? Id { get; set; }
    [BsonElement("name")]
    public string? Name { get; set; }
    [BsonElement("cuisine")]
    public string? Cuisine { get; set; }
    [BsonElement("borough")]
    public string? Borough { get; set; }
}

Retrieve Values Across a Collection

The following example retrieves the distinct values of the borough field in the restaurants collection. Select the Asynchronous or Synchronous tab to see the corresponding code.

var results = await collection.DistinctAsync<string>(r => r.Borough, Builders<Restaurant>.Filters.Empty);
await results.ForEachAsync(result => Console.WriteLine(result));

Bronx
Brooklyn
Manhattan
Missing
Queens
Staten Island

var results = collection.Distinct<string>(r => r.Borough, Builders<Restaurant>.Filters.Empty).ToList();
foreach (var result in results)
{
    Console.WriteLine(result);
}

Bronx
Brooklyn
Manhattan
Missing
Queens
Staten Island

The operation returns a cursor that you can iterate through to access each distinct borough field value. Although several documents have the same value in the borough field, each value appears in the results only once.

Retrieve Values Across Specified Documents

You can provide a query filter to the Distinct() and DistinctAsync() methods to find distinct field values within a subset of documents in a collection. A query filter is an expression that specifies search criteria used to match documents in an operation. For more information about creating a query filter, see the Specify a Query guide.

The following example retrieves the distinct values of the borough field for all documents that have a cuisine field value of "Italian". Select the Asynchronous or Synchronous tab to see the corresponding code.

var filter = Builders<Restaurant>.Filter.Eq(r => r.Cuisine, "Italian");
var results = await collection.DistinctAsync<string>(r => r.Borough, filter);
await results.ForEachAsync(result => Console.WriteLine(result));

Bronx
Brooklyn
Manhattan
Queens
Staten Island

var filter = Builders<Restaurant>.Filter.Eq(r => r.Cuisine, "Italian");
var results = collection.Distinct<string>(r => r.Borough, filter).ToList();
foreach (var result in results)
{
    Console.WriteLine(result);
}

Bronx
Brooklyn
Manhattan
Queens
Staten Island

Modify Distinct Behavior

You can modify the behavior of the Distinct() and DistinctAsync() methods by providing a DistinctOptions instance as an optional parameter. The following table describes the properties you can set on a DistinctOptions instance:

The following example retrieves the distinct values of the name field for all documents that have a borough field value of "Bronx" and a cuisine field value of "Pizza". Then, it adds a comment to the operation by providing a DistinctOptions instance to the Distinct() method.

Select the Asynchronous or Synchronous tab to see the corresponding code.

var cuisineFilter = Builders<Restaurant>.Filter.Eq(r => r.Cuisine, "Pizza");
var boroughFilter = Builders<Restaurant>.Filter.Eq(r => r.Borough, "Bronx");
var filter = Builders<Restaurant>.Filter.And(cuisineFilter, boroughFilter);
var options = new DistinctOptions {
    Comment = "Find all Italian restaurants in the Bronx"
};
var results = await collection.DistinctAsync<string>(r => r.Name, filter, options);
await results.ForEachAsync(result => Console.WriteLine(result));

$1.25 Pizza
18 East Gunhill Pizza
2 Bros
Aenos Pizza
Alitalia Pizza Restaurant
Amici Pizza And Pasta
Angie'S Cafe Pizza
...

var cuisineFilter = Builders<Restaurant>.Filter.Eq(r => r.Cuisine, "Pizza");
var boroughFilter = Builders<Restaurant>.Filter.Eq(r => r.Borough, "Bronx");
var filter = Builders<Restaurant>.Filter.And(cuisineFilter, boroughFilter);
var options = new DistinctOptions {
    Comment = "Find all Italian restaurants in the Bronx"
};
var results = collection.Distinct<string>(r => r.Name, filter).ToList();
foreach (var result in results)
{
    Console.WriteLine(result);
}

$1.25 Pizza
18 East Gunhill Pizza
2 Bros
Aenos Pizza
Alitalia Pizza Restaurant
Amici Pizza And Pasta
Angie'S Cafe Pizza
...