Filters Builders

Overview

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

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

Filters are operations used to limit the results of a query based on specified conditions. Filters are a helpful tool to locate information that matches search conditions in a collection.

You can use filters in the following places:

• As a parameter to the find() method

• In a match stage of an aggregation pipeline

• As a parameter to the deleteOne() or deleteMany() method

• As a parameter to the updateOne() or updateMany() method

Some examples of results from queries with filters are:

• Items that cost more than $0 but less than $25

• Foods that are both gluten-free and less than 500 calories

• Food critic reviews that mention "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.*;

Sample Data

The 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);
FindPublisher<Document> findPublisher = collection.find(equalComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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);
FindPublisher<Document> findPublisher = collection.find(gteComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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();
FindPublisher<Document> findPublisher = collection.find(emptyComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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"));
FindPublisher<Document> findPublisher = collection.find(orComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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 vendor array containing both "A" and "D" in the paint_purchases collection:

List<String> search = Arrays.asList("A", "D");
Bson allComparison = all("vendor", search);
FindPublisher<Document> findPublisher = collection.find(allComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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 a value not equal to "5" or "8" in the paint_purchases collection:

Bson existsComparison = and(exists("qty"), nin("qty", 5, 8));
FindPublisher<Document> findPublisher = collection.find(existsComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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");
FindPublisher<Document> findPublisher = collection.find(regexComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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 an a field with bits set at positions of the corresponding bitmask "34" (i.e. "00100010") in the binary_numbers collection:

Bson bitsComparison = bitsAllSet("a", 34);
FindPublisher<Document> findPublisher = collection.find(bitsComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

{ "_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)));
Bson geoWithinComparison = geoWithin("coordinates", square);
FindPublisher<Document> findPublisher = collection.find(geoWithinComparison);
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

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