Filters Builders

Overview

In this guide, you can learn how to use builders to specify filters for your queries in the MongoDB Java driver.

Builders are classes provided by the MongoDB Java driver that help you construct BSON objects. To learn more, see our guide on builders.

Filters are the operations MongoDB uses to limit your results to what you want to see.

Some places we use filters are:

• find()

• match stage of aggregation

• deleteOne()/deleteMany()

• updateOne()/updateMany()

Some examples of results from queries with filters are:

• Items that cost $0 to $25

• A hotel with amenities that include an indoor swimming pool and free parking

• A food critic review that mentions "spicy"

This guide shows you how to use builders with examples of the following types of operators:

• Comparison

• Logical

• Arrays

• Elements

• Evaluation

• Bitwise

• Geospatial

The Filters class provides static factory methods for all the MongoDB query operators. Each method returns an instance of the BSON type, which you can pass to any method that expects a query filter.

import static com.mongodb.client.model.Filters.*;

The Filter examples in this guide use the following sample collections:

Collection: paint_purchases

{ "_id": 1, "color": "red", "qty": 5, "vendor": ["A"] }
{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 3, "color": "blue", "qty": 8, "vendor": ["B", "A"] }
{ "_id": 4, "color": "white", "qty": 6, "vendor": ["D"] }
{ "_id": 5, "color": "yellow", "qty": 11, "vendor": ["A", "B"] }
{ "_id": 6, "color": "pink", "qty": 5, "vendor": ["C"] }
{ "_id": 7, "color": "green", "qty": 8,"vendor": ["B", "C"] }
{ "_id": 8, "color": "orange", "qty": 7, "vendor": ["A", "D"] }

Collection: binary_numbers

{ "_id": 9, "a": 54, "binaryValue": "00110110" }
{ "_id": 10, "a": 20, "binaryValue": "00010100" }
{ "_id": 11, "a": 68, "binaryValue": "1000100" }
{ "_id": 12, "a": 102, "binaryValue": "01100110" }

Collection: geo_points

{ "_id": 13, "coordinates": { "type": "Point", "coordinates": [2.0, 2.0] } }
{ "_id": 14, "coordinates": { "type": "Point", "coordinates": [5.0, 6.0] } }
{ "_id": 15, "coordinates": { "type": "Point", "coordinates": [1.0, 3.0] } }
{ "_id": 16, "coordinates": { "type": "Point", "coordinates": [4.0, 7.0] } }

Comparison

The comparison filters include all operators that compare the value in a document to a specified value.

The comparison operator methods include:

The following example creates a filter that matches all documents where the value of the qty field equals "5" in the paint_purchases collection:

Bson equalComparison = eq("qty", 5);
collection.find(equalComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 1, "color": "red", "qty": 5, "vendor": ["A"] }
{ "_id": 6, "color": "pink", "qty": 5, "vendor": ["C"] }

The following example creates a filter that matches all documents where the value of the qty field is greater than or equal to "10" in the paint_purchases collection:

Bson gteComparison = gte("qty", 10);
collection.find(gteComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 5, "color": "yellow", "qty": 11, "vendor": ["A", "B"] }

The following example creates a filter that matches all documents in the paint_purchases collection because the predicate is empty:

Bson emptyComparison = empty();
collection.find(emptyComparison).forEach(doc -> System.out.println(doc.toJson()));

The output of the preceding query consists of all the documents in the collection.

{ "_id": 1, "color": "red", "qty": 5, "vendor": ["A"] }
{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 3, "color": "blue", "qty": 8, "vendor": ["B", "A"] }
...

Logical

The logical operators perform logical operations based on the conditions of the specified method.

The logical operator methods include:

The following example creates a filter that matches documents where the value of the qty field is greater than "8" or the value of the color field equals "pink" in the paint_purchases collection:

Bson orComparison = or(gt("qty", 8), eq("color", "pink"));
collection.find(orComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 5, "color": "yellow", "qty": 11, "vendor": ["A", "B"] }
{ "_id": 6, "color": "pink", "qty": 5, "vendor": ["C"] }

Arrays

The array operators evaluate the array field in a document.

The array operator methods include:

The following example matches documents with a vendors array containing both "A" and "D" in the paint_purchases collection:

List<String> search = Arrays.asList("A", "D");
Bson allComparison = all("vendor", search);
collection.find(allComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 8, "color": "orange", "qty": 7, "vendor": ["A", "D"] }

Elements

The elements operators evaluate the nature of a specified field.

The elements operator methods include:

The following example matches documents that have a qty field and its value does not equal "5" or "8" in the paint_purchases collection:

Bson existsComparison = and(exists("qty"), nin("qty", 5, 8));
collection.find(existsComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 4, "color": "white", "qty": 6, "vendor": ["D"]}
{ "_id": 5, "color": "yellow", "qty": 11, "vendor": ["A", "B"] }
{ "_id": 8, "color": "orange", "qty": 7, "vendor": ["A", "D"] }

Evaluation

The evaluation operators evaluate the value of any field in a document.

The evaluation operator methods include:

The following example matches documents that have a color field starting with the letter "p" in the paint_purchases collection:

Bson regexComparison = regex("color", "^p");
collection.find(regexComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 2, "color": "purple", "qty": 10, "vendor": ["C", "D"] }
{ "_id": 6, "color": "pink", "qty": 5, "vendor": ["C"] }

Bitwise

The bitwise operators convert a number into its binary value to evaluate its bits.

The bitwise operator methods include:

The following example matches documents that have a bitField field with bits set at positions of the corresponding bitmask "34" (i.e. "00100010") in the binary_numbers collection:

Bson bitsComparison = bitsAllSet("a", 34);
collection.find(bitsComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 9, "a": 54, "binaryValue": "00110110" }
{ "_id": 12, "a": 102, "binaryValue": "01100110" }

Geospatial

The geospatial operators evaluate a specified coordinate and its relation to a shape or location.

The geospatial operator methods include:

The following example creates a filter that matches documents in which the point field contains a GeoJSON geometry that falls within the given Polygon in the geo_points collection:

Polygon square = new Polygon(Arrays.asList(new Position(0, 0), 
                                    new Position(4, 0), 
                                    new Position(4, 4), 
                                    new Position(0, 4),
                                    new Position(0, 0)));
// Prints documents that contain "coordinates" values that are within the bounds of the polygon passed as the filter parameter
Bson geoWithinComparison = geoWithin("coordinates", square);
collection.find(geoWithinComparison).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding query:

{ "_id": 13, "coordinates": {"type": "Point", "coordinates": [2.0, 2.0]} }
{ "_id": 15, "coordinates": {"type": "Point", "coordinates": [1.0, 3.0]} }