Basics

Meet the builder 🤝

Filter Definition Builder

To create a filter query for an IMongoCollection<T> collection, you need to build a FilterDefinition<T> filter. You can do this using the Builders<T>.Filter filter definition builder which contains several filters such as the equality or element filters. This section will give you an overview on how to create and use the filter definition builder.

Builders<T>.Filter.<operator>

The `Empty` filter

Use the Empty filter when you want to get either the 1st document or all of its documents.

Crud.Read.Basics.cs

// empty filter
var emptyFilter = Builders<User>.Filter.Empty;

// first user
var firstUser = await collection.Find(emptyFilter)
    .FirstOrDefaultAsync();

// all users
var allUsers = await collection.Find(emptyFilter)
    .ToListAsync();

var bsonEmptyDocument = Builders<BsonDocument>.Filter.Empty;

var bsonFirstUser = await bsonCollection
    .Find(new BsonDocument()).FirstOrDefaultAsync();
    
var bsonAllUsers = await bsonCollection
    .Find(bsonEmptyDocument).ToListAsync();

When querying a IMongoCollection<BsonDocument> collection, you can use an empty BsonDocument as an empty filter definition

Equality filter on a top level field

The equality filter is one of the most used filters you are gonna use when querying MongoDB. The following examples filter user documents on top level string fields, profession and email.

Builders<T>.Filter.Eq(doc => doc.<field>, <value>)

Crud.Read.Basics.cs

var collection = database
    .GetCollection<User>(Constants.UsersCollection);

// create the equality filter
var doctorsFilter = Builders<User>.Filter
    .Eq(u => u.Profession, "Doctor");
    
var doctors = await collection.Find(doctorsFilter).ToListAsync();

var bsonCollection = database
    .GetCollection<BsonDocument>(Constants.UsersCollection);

var sampleBsonUserFilter = Builders<BsonDocument>.Filter
    .Eq("email", sampleUser.Email);
    
var dbBsonSampleUser = await bsonCollection
    .Find(sampleBsonUserFilter).FirstOrDefaultAsync();

public class User
{
    [BsonId]
    [BsonIgnoreIfDefault] // required for replace documents 
    public ObjectId Id { get; set; }
    public Gender Gender { get; set; }
    public string FirstName {get; set; }
    public string LastName {get; set; }
    public string UserName {get; set; }
    public string Avatar {get; set; }
    public string Email {get; set; }
    public DateTime DateOfBirth {get; set; }
    public AddressCard Address {get; set; }
    public string Phone {get; set; }
    
    [BsonIgnoreIfDefault]
    public string Website {get; set; }
    public CompanyCard Company {get; set; }
    public decimal Salary { get; set; }
    public int MonthlyExpenses { get; set; }
    public List<string> FavoriteSports { get; set; }
    public string Profession { get; set; }
}

Equality filter is case sensitive, so always make sure to use it properly!

Equality filter on a nested field

You can use the equality filter to match your documents based on an embedded document field. In the following example the address field is an embedded field on the user document and contains a city string field. The sample show how to filter documents based on the city field.

Builders<T>.Filter
.Eq(doc => doc.<field1>..<fieldN>.<embedded-field>, 
    <value>)

The hierarchy from <field1> to the <embedded-field> cannot contain an array field

Crud.Read.Basics.cs

var collection = database
    .GetCollection<User>(Constants.UsersCollection);

// create the filter on the address.city field
var athensCityFilter = Builders<User>
    .Filter.Eq(u => u.Address.City, "Athens");
    
var athensUsers = await collection
    .Find(athensCityFilter).ToListAsync();

var bsonCollection = database
    .GetCollection<BsonDocument>(Constants.UsersCollection);

var bsonAthensCityFilter = Builders<BsonDocument>
    .Filter.Eq("address.city", "Athens");
    
var bsonAthensUsers = await bsonCollection
    .Find(bsonAthensCityFilter).ToListAsync();

db.users.find({"address.city": { $eq: "Athens"}})
db.users.find({"address.city": "Athens"})

-------------------------

// sample result

{
	"_id" : ObjectId("5e919356139fe1568028900d"),
	"gender" : 1,
	"firstName" : "Lana",
	"lastName" : "Price",
	"userName" : "Lana_Price",
	"avatar" : "https://s3.amazonaws.com/uifaces/faces/twitter/adhiardana/128.jpg",
	"email" : "Lana.Price@hotmail.com",
	"dateOfBirth" : ISODate("1951-11-17T06:47:46.404+02:00"),
	"address" : {
		"street" : "8901 Korbin Fords",
		"suite" : "Apt. 810",
		"city" : "Athens", // matched document
		"state" : "Maine",
		"zipCode" : "28939-3112",
		"geo" : {
			"lat" : 62.7547,
			"lng" : -171.0489
		}
	},
	"phone" : "351.573.6992 x6949",
	"website" : "sabryna.com",
	"company" : {
		"name" : "O'Connell Group",
		"catchPhrase" : "Profound value-added hardware",
		"bs" : "reinvent back-end channels"
	},
	"salary" : 4879,
	"monthlyExpenses" : 4378,
	"favoriteSports" : [
		"Tennis",
		"Water Polo",
		"Baseball",
		"Cricket",
		"MMA",
		"Cycling",
		"Snooker",
		"Beach Volleyball",
		"Darts",
		"Motor Sport",
		"Table Tennis"
	],
	"profession" : "Model"
},

public class User
{
    [BsonId]
    [BsonIgnoreIfDefault] // required for replace documents 
    public ObjectId Id { get; set; }
    public Gender Gender { get; set; }
    public string FirstName {get; set; }
    public string LastName {get; set; }
    public string UserName {get; set; }
    public string Avatar {get; set; }
    public string Email {get; set; }
    public DateTime DateOfBirth {get; set; }
    public AddressCard Address {get; set; }
    public string Phone {get; set; }
    
    [BsonIgnoreIfDefault]
    public string Website {get; set; }
    public CompanyCard Company {get; set; }
    public decimal Salary { get; set; }
    public int MonthlyExpenses { get; set; }
    public List<string> FavoriteSports { get; set; }
    public string Profession { get; set; }
}

public class AddressCard
{
    public string Street {get; set; }
    public string Suite {get; set; }
    public string City {get; set; }
    public string State {get; set; }
    public string ZipCode {get; set; }
    public AppCardGeo Geo {get; set; }

    public class AppCardGeo
    {
        public double Lat {get; set; }
        public double Lng {get; set; }
    }
}

Remember, the filter might be on an embedded document field, but the result will be always the entire document(s) that matched the criteria

Equality filter on a array field

Assuming your document contains an array field with string values, you want to get all documents that their array field contains a specific value. The sample that follows works for other types as well (e.g. bool, int, decimal, float).

Builders<T>.Filter
    .Eq(doc => doc.<array-field>, <value>)

The example retrieves all user documents that their FavoriteSports array field contains a specific sport. It does that by using an equality filter for an array field called AnyEq.

Crud.Read.Basics.cs

var collection = database
    .GetCollection<User>(Constants.UsersCollection);

// create an equality filter on an array field
// find all user documents that contains 'Basketball' on their sports array
var basketballFilter = Builders<User>.Filter
    .AnyEq(u => u.FavoriteSports, "Basketball");

// the matched documents might have other sports
// in the favoriteSports array
var usersHaveBasketball = await collection
    .Find(basketballFilter).ToListAsync();

var bsonCollection = database
    .GetCollection<BsonDocument>(Constants.UsersCollection);

var bsonBasketballFilter = Builders<BsonDocument>.Filter
    .AnyEq("favoriteSports", "Basketball");
    
var bsonUsersHaveBasketball = await bsonCollection
    .Find(bsonBasketballFilter).ToListAsync();

// MongoDB understands that favoriteSports field is an array
// and makes the right search on it
db.users.find({"favoriteSports": "Basketball"})

-------------------------------

// sample result
{
	"_id" : ObjectId("5e91e3ba3c1ba62570a67b98"),
	"gender" : 0,
	"firstName" : "Spencer",
	"lastName" : "Swift",
	"userName" : "Spencer.Swift",
	"avatar" : "https://s3.amazonaws.com/uifaces/faces/twitter/daykiine/128.jpg",
	"email" : "Spencer61@hotmail.com",
	"dateOfBirth" : ISODate("1955-01-08T04:19:35.543+02:00"),
	"address" : {
		"street" : "9336 Walker Crest",
		"suite" : "Suite 144",
		"city" : "South Tate",
		"state" : "South Carolina",
		"zipCode" : "46603",
		"geo" : {
			"lat" : 39.9979,
			"lng" : -117.9544
		}
	},
	"phone" : "1-377-659-2465 x7862",
	"website" : "barbara.com",
	"company" : {
		"name" : "Wisoky, Lynch and Torphy",
		"catchPhrase" : "Diverse dedicated customer loyalty",
		"bs" : "scale sexy technologies"
	},
	"salary" : 4325,
	"monthlyExpenses" : 3023,
	"favoriteSports" : [
		"Basketball", // matched document
		"Table Tennis",
		"Moto GP",
		"Tennis",
		"Boxing",
		"Motor Sport",
		"Ice Hockey",
		"Baseball",
		"American Football",
		"Water Polo",
		"Volleyball",
		"Golf",
		"Cycling",
		"Formula 1",
		"Cricket"
	],
	"profession" : "Pilot"
},

public class User
{
    [BsonId]
    [BsonIgnoreIfDefault] // required for replace documents 
    public ObjectId Id { get; set; }
    public Gender Gender { get; set; }
    public string FirstName {get; set; }
    public string LastName {get; set; }
    public string UserName {get; set; }
    public string Avatar {get; set; }
    public string Email {get; set; }
    public DateTime DateOfBirth {get; set; }
    public AddressCard Address {get; set; }
    public string Phone {get; set; }
    
    [BsonIgnoreIfDefault]
    public string Website {get; set; }
    public CompanyCard Company {get; set; }
    public decimal Salary { get; set; }
    public int MonthlyExpenses { get; set; }
    public List<string> FavoriteSports { get; set; }
    public string Profession { get; set; }
}

When the search term used in AnyEq is a simple value, then you are running a search for that term in the array field, meaning that there might be other values contained as well

Equality filter on a array field - Exact match

In case you want to run an exact match on the array field then you must use an array argument in the AnyEq filter. This will try match the entire array field rather than just searching inside the array.

Builders<T>.Filter
    .Eq(doc => doc.<array-field>, <array-values>)

The following example finds the documents that their FavoriteSports array field contains only the Soccer term.

Crud.Read.Basics.cs

var collection = database
    .GetCollection<User>(Constants.UsersCollection);

// create an equality filter on an array field
// find all user documents that have only 'Soccer' on their sports array
var onlySoccerFilter = Builders<User>.Filter
    .Eq(u => u.FavoriteSports, new List<string> { "Soccer" });

// the matched documents contain only Soccer in the favoriteSports
var soccerUsers = await collection
    .Find(onlySoccerFilter).ToListAsync();

var bsonCollection = database
            .GetCollection<BsonDocument>(Constants.UsersCollection);

var bsonOnlySoccerFilter = Builders<BsonDocument>.Filter
            .Eq("favoriteSports", new List<string>() { "Soccer" });

var bsonSoccerUsers = await bsonCollection
            .Find(bsonOnlySoccerFilter).ToListAsync();

// sample result
{
	"_id" : ObjectId("5e91e3ba3c1ba62570a67e08"),
	"gender" : 1,
	"firstName" : "June",
	"lastName" : "Dach",
	"userName" : "June.Dach23",
	"avatar" : "https://s3.amazonaws.com/uifaces/faces/twitter/d33pthought/128.jpg",
	"email" : "June64@gmail.com",
	"dateOfBirth" : ISODate("1970-02-26T04:13:22.471+02:00"),
	"address" : {
		"street" : "0942 Prosacco Extension",
		"suite" : "Apt. 518",
		"city" : "Aubreytown",
		"state" : "Louisiana",
		"zipCode" : "39912",
		"geo" : {
			"lat" : 43.4411,
			"lng" : -73.1164
		}
	},
	"phone" : "1-832-666-1307 x6427",
	"website" : "wilfrid.biz",
	"company" : {
		"name" : "Feest LLC",
		"catchPhrase" : "Reduced national project",
		"bs" : "incentivize plug-and-play action-items"
	},
	"salary" : 3871,
	"monthlyExpenses" : 2241,
	"favoriteSports" : [
		"Soccer" // matched document
	],
	"profession" : "Engineer"
}

PreviousRead NextComparison Operators

Last updated 5 years ago

hashtagFilter Definition Builder

hashtag The Empty filter

hashtagEquality filter on a top level field

hashtagEquality filter on a nested field

hashtagEquality filter on a array field

hashtagEquality filter on a array field - Exact match

Filter Definition Builder

The `Empty` filter

Equality filter on a top level field

Equality filter on a nested field

Equality filter on a array field

Equality filter on a array field - Exact match