Specify a Query

Overview

In this guide, you can learn how to specify a query in the MongoDB Java driver.

Most CRUD operations allow you to narrow the set of matched documents by specifying matching criteria in a query filter. Query filters contain one or more query operators that apply to specific fields which determine which documents to include in the result set.

In this page, we cover the following query operators with examples on how to use them:

• Comparison Operators

• Logical Operators

• Array Operators

• Element Operators

• Evaluation Operators

The examples in this guide use the following documents in the paint_purchases collection:

{ "_id": 1, "color": "red", "qty": 9, "vendor": ["A", "E"] }
{ "_id": 2, "color": "purple", "qty": 8, "vendor": ["B", "D", "F"], "rating": 5 }
{ "_id": 3, "color": "blue", "qty": 5, "vendor": ["A", "E"] }
{ "_id": 4, "color": "white", "qty": 6, "vendor": ["D"], "rating": 9 }
{ "_id": 5, "color": "yellow", "qty": 4, "vendor": ["A", "B"] }
{ "_id": 6, "color": "pink", "qty": 3, "vendor": ["C"] }
{ "_id": 7, "color": "green", "qty": 8, "vendor": ["C", "E"], "rating": 7 }
{ "_id": 8, "color": "black", "qty": 7, "vendor": ["A", "C", "D"] }

Comparison Operators

Comparison operators query data based on comparisons with values in a collection. Common comparison operators include gt() for "greater than" comparisons, lte() for "less than or equal to" comparisons, and ne() for "not equal to " comparisons.

The following example uses the Filters.gt() method to match all documents where the value of qty is greater than 7 in the paint_purchases collection:

Bson filter = Filters.gt("qty", 7);
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

 { "_id": 1, "color": "red", "qty": 9, "vendor": ["A", "E"] }
 { "_id": 2, "color": "purple", "qty": 8, "vendor": ["B", "D", "F"], "rating": 5 }
 { "_id": 7, "color": "green", "qty": 8, "vendor": ["C", "E"], "rating": 7 }

Logical Operators

Logical operators query data using logic applied to the results of field-level operators. Common logical operators include and() where all operators must be true, and or() where at least one of the operators must be true.

The following example uses the Filters.and() method to match documents where the value of qty is less than or equal to 5 and the value of color is not "pink" in the paint_purchases collection:

Bson filter = Filters.and(Filters.lte("qty", 5), Filters.ne("color", "pink"));
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

 { "_id": 3, "color": "blue", "qty": 5, "vendor": ["A", "E"] }
 { "_id": 5, "color": "yellow", "qty": 4, "vendor": ["A", "B"] }

Array Operators

Array operators query data based on the value or quantity of elements in an array field.

The following example uses the Filters.size() method to match documents where the size of the vendor list is 3 in the paint_purchases collection:

Bson filter = Filters.size("vendor", 3);
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

 { "_id": 2, "color": "purple", "qty": 8, "vendor": ["B", "D", "F"], "rating": 5 }
 { "_id": 8, "color": "black", "qty": 7, "vendor": ["A", "C", "D"] }

Element Operators

Element operators query data based on the presence or type of a field.

The following example uses the Filters.exists() method to match documents that have a rating in the paint_purchases collection:

Bson filter = Filters.exists("rating");
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

 { "_id": 2, "color": "purple", "qty": 8, "vendor": ["B", "D", "F"], "rating": 5 }
 { "_id": 4, "color": "white", "qty": 6, "vendor": ["D"], "rating": 9 }
 { "_id": 7, "color": "green", "qty": 8, "vendor": ["C", "E"], "rating": 7 }

Evaluation Operators

Evaluation operators query data on higher level logic, like regex and text searches.

The following example uses the Filters.regex() method to match documents that have a color ending with the letter "k" in the paint_purchases collection:

Bson filter = Filters.regex("color", "k$");
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

 { "_id": 6, "color": "pink", "qty": 3, "vendor": ["C"] }
 { "_id": 8, "color": "black", "qty": 7, "vendor": ["A", "C", "D"] }

For more information about the operators mentioned in this guide, see the following Server Manual Entries:

• Query Operators

• Comparison Operators

• Logical Operators

• Array Operators

• Element Operators

• Evaluation Operators