Find and Query Entity Data with LINQ

Sample Data

The examples in this guide use the planets collection from the sample_guides database. The documents in this collection use the following Planet class as a model:

public class Planet
{
    public ObjectId _id { get; set; }
    public string name { get; set; } = null!;
    public int orderFromSun { get; set; }
    public bool hasRings { get; set; }
}

This collection is from the sample datasets provided by Atlas. See the Quick Start guide to learn how to create a free MongoDB cluster and load this sample data.

Find a Single Entity

The FirstOrDefault() method returns the first entity it finds in your collection that matches the search criteria, and returns null if no matching entities are found.

The following code uses the FirstOrDefault() method to find a planet with the name field of "Mercury" from a DBSet called Planets and prints the planet name to the console:

var planet = db.Planets.FirstOrDefault(p => p.name == "Mercury");
Console.WriteLine(planet?.name);

Find Multiple Entities

You can use the Where() method to retrieve multiple entities from your collections. Where() returns all entities that match the search criteria.

The following code uses the Where() method to find all planets that have the hasRings field set to true and prints the planet names to the console.

var planets = db.Planets.Where(p => p.hasRings);
foreach (var p in planets)
{
    Console.WriteLine(p.name);
}

Query a Shadow Property

A shadow property is a property that isn't defined on your .NET entity class but is included in the Entity Framework model and mapped to fields in the database. You can use shadow properties to query or track data in your documents without exposing it as a property on your entity.

To reference a shadow property in a LINQ query, call the EF.Property<T>() method and pass the configured property name as an argument. The generic type argument must match the data type of the shadow property.

For example, the Planet class does not define a property for the mainAtmosphere field. To configure this field as a shadow property, call the Property<T>() method in the OnModelCreating() method of PlanetDbContext, as shown in the following example:

public class PlanetDbContext : DbContext
{
    public DbSet<Planet> Planets { get; init; } = null!;
    public static PlanetDbContext Create(IMongoDatabase database) =>
        new(new DbContextOptionsBuilder<PlanetDbContext>()
            .UseMongoDB(database.Client, database.DatabaseNamespace.DatabaseName)
            .Options);
    public PlanetDbContext(DbContextOptions options)
        : base(options)
    {
    }
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.Entity<Planet>().ToCollection("planets");
        modelBuilder.Entity<Planet>().Property<string[]>("mainAtmosphere");
    }
}

The call to modelBuilder.Entity<Planet>().Property<string[]>("mainAtmosphere") instructs the framework to include mainAtmosphere in the model and map it to a string[] field in MongoDB.

The following code uses the EF.Property<string[]>() method to find all planets that have a non-empty mainAtmosphere shadow property and prints the planet names to the console:

var planets = db.Planets.Where(
    p => EF.Property<string[]>(p, "mainAtmosphere").Length > 0);
foreach (var p in planets)
{
    Console.WriteLine(p.name);
}

Mql.Exists

The Mql.Exists() method matches documents that contain the specified field, including documents where the field value is null.

The following code uses the Mql.Exists() method to find all planets that have the hasRings field and prints the planet names to the console:

var planetNames = db.Planets
    .Where(p => Mql.Exists(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Mql.IsMissing

The Mql.IsMissing() method matches documents that do not contain the specified field.

The following code uses the Mql.IsMissing() method to find all planets that do not have the hasRings field and prints the planet names to the console:

var planetNames = db.Planets
    .Where(p => Mql.IsMissing(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Mql.IsNullOrMissing

The Mql.IsNullOrMissing() method matches documents where the specified field is either missing or has a null value.

The following code uses the Mql.IsNullOrMissing() method to find all planets where the hasRings field is missing or null and prints the planet names to the console:

var planetNames = db.Planets
    .Where(p => Mql.IsNullOrMissing(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Limit the Number of Results

Use the Take() method to specify a maximum number of entities to return from a query.

The following code uses the Take() method to return the first 3 planets from the Planets collection:

var planetList = db.Planets.Take(3);
foreach (var p in planetList)
{
    Console.WriteLine(p.name);
}

Skip Results

Use the Skip() method to specify a number of entities to skip before returning results from a query.

The following code uses the OrderBy() and Skip() methods to skip the first 5 planets (ordered by orderFromSun) and return the remaining planets:

var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5);
foreach (var p in planetList)
{
    Console.WriteLine(p.name);
}

Count

The following example uses the Count() method to count the number of elements in the Planets collection:

var planetCount = db.Planets.Count();
Console.WriteLine("Planet Count: " + planetCount);

The following example uses the Count() method to count the number of elements in the Planets collection that have a hasRings field set to true:

var planetCountWithRings = db.Planets.Count(p => p.hasRings);
Console.WriteLine("Planet Count with Rings: " + planetCountWithRings);

LongCount

The following example uses the LongCount() method to count the number of elements in the Planets collection and returns the result as a long:

var planetCountLong = db.Planets.LongCount();
Console.WriteLine("Long Planet Count: " + planetCountLong);

The following example uses the LongCount() method to count the number of elements in the Planets collection that have a hasRings field set to true and returns the result as a long:

var planetCountLongWithRings = db.Planets.LongCount(p => p.hasRings);
Console.WriteLine("Long Planet Count with Rings: " + planetCountLongWithRings);

Any

The following example uses the Any() method to check if any elements in the Planets collection have a hasRings field set to true:

var results = db.Planets.Any(p => p.hasRings);
Console.WriteLine("Planet with Rings: " + results);

Max

The following example uses the Max() method to find the maximum value of the orderFromSun field in the Planets collection:

var furthestPlanet = db.Planets.Max(p => p.orderFromSun);
Console.WriteLine("Furthest Planet: " + furthestPlanet);

Min

The following example uses the Min() method to find the minimum value of the orderFromSun field in the Planets collection:

var closestPlanet = db.Planets.Min(p => p.orderFromSun);
Console.WriteLine("Closest Planet: " + closestPlanet);

Sum

The following example uses the Sum() method to find the sum of the orderFromSun field in the Planets collection:

var totalOrderFromSun = db.Planets.Sum(p => p.orderFromSun);
Console.WriteLine("Total Order From Sun: " + totalOrderFromSun);

Average

The following example uses the Average() method to find the average value of the orderFromSun field in the Planets collection:

var averageOrderFromSun = db.Planets.Average(p => p.orderFromSun);
Console.WriteLine("Average Order From Sun: " + averageOrderFromSun);

Enable Sensitive Data Logging

The provider logs full MQL query text only when sensitive data logging is enabled. If you don't enable sensitive data logging, query logs might omit values. To enable sensitive data logging, call the EnableSensitiveDataLogging() method from your DbContextOptionsBuilder object, as shown in the following example:

var mongoClient = new MongoClient("<connection string URI>");
var dbContextOptions =
    new DbContextOptionsBuilder<MyDbContext>()
        .UseMongoDB(mongoClient, "sample_guides")
        .LogTo(Console.WriteLine)
        .EnableSensitiveDataLogging()
        .Options;
var db = new MyDbContext(dbContextOptions);

Custom Serialization Conventions

If you register custom BSON serialization conventions on the MongoClient, such as camel-case field naming, those conventions can change the field names stored in MongoDB so that they differ from the property names in your entity model. The EF Core Provider uses entity property names to generate MQL, so a mismatch can cause queries to target the wrong fields and bypass any indexes on those fields. When your stored field names differ from your entity property names, you can explicitly map a property to its stored field name in OnModelCreating() by using HasElementName(), as shown in the following example:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);
    modelBuilder.Entity<Planet>()
        .Property(p => p.name)
        .HasElementName("name");
}