Docs Menu
Docs Home
/
Languages
/
Scala
/
Scala
/
Builders

Filters

On this page

  • Comparison
  • Examples
  • Logical
  • Examples
  • Arrays
  • Examples
  • Elements
  • Examples
  • Evaluation
  • Examples
  • Bitwise
  • Examples
  • Geospatial
  • Examples

The Filters class provides static factory methods for the MongoDB query operators. Each method returns an instance of the Bson type, which can in turn be passed to any method that expects a query filter.

You can import the methods of the Filters class statically, as shown in the following code:

import org.mongodb.scala.model.Filters._

The examples in this guide assume this static import.

Comparison

The comparison operator methods include the following:

  • eq: Matches values that are equal to a specified value. Aliased to equal as eq is a reserved word.

  • gt: Matches values that are greater than a specified value.

  • gte: Matches values that are greater than or equal to a specified value.

  • lt: Matches values that are less than a specified value.

  • lte: Matches values that are less than or equal to a specified value.

  • ne: Matches all values that are not equal to a specified value. Aliased to notEqual as neq is a reserved word.

  • in: Matches any of the values specified in an array.

  • nin: Matches none of the values specified in an array.

  • empty: Matches all the documents.

Examples

The following example creates a filter that selects all documents where the value of the qty field is 20:

`eq`("qty", 20)
equal("qty", 20)

The following example creates a filter that selects all documents where the value of the qty field is either 5 or 15:

in("qty", 5, 15)

The following example creates a filter that selects all documents because the filter is empty:

empty()

Logical

The logical operator methods include the following:

  • and: Joins filters with a logical AND and selects all documents that match the conditions of both filters.

  • or: Joins filters with a logical OR and selects all documents that match the conditions of either filter.

  • not: Inverts the effect of a query expression and selects documents that do not match the filter.

  • nor: Joins filters with a logical NOR and selects all documents that fail to match both filters.

Examples

The following example creates a filter that selects all documents where the value of the qty field is greater than 20 and the value of the user field is "jdoe":

and(gt("qty", 20), equal("user", "jdoe"))

The and() method generates an $and operator only if necessary, as the query language implicitly adds together all the elements in a filter. The preceding example renders as the following:

{
   "qty" : { "$gt" : 20 },
   "user" : "jdoe"
}

The following example creates a filter that selects all documents where the price field value equals 0.99 or 1.99, and either the sale field value is true or the qty field value is less than 20:

and(or(equal("price", 0.99), equal("price", 1.99)
    or(equal("sale", true), lt("qty", 20)))

This query cannot be constructed using an implicit $and operation, because it uses the $or operator more than once. This query renders to the following:

{
 "$and" :
    [
      { "$or" : [ { "price" : 0.99 }, { "price" : 1.99 } ] },
      { "$or" : [ { "sale" : true }, { "qty" : { "$lt" : 20 } } ] }
    ]
}

Arrays

The array operator methods include the following:

  • all: Matches arrays that contain all elements specified in the query.

  • elemMatch: Selects documents if an element in the array field matches all the specified $elemMatch conditions.

  • size: Selects documents if the array field is a specified size.

Examples

The following example selects documents with a tags array containing both "ssl" and "security":

all("tags", "ssl", "security")

Elements

The elements operator methods include the following:

  • exists: Selects documents that have the specified field.

  • type: Selects documents if a field is of the specified type. Aliased to bsonType as type is a reserved word.

Examples

The following example selects documents that contain a qty field and the value of this field does not equal 5 or 15:

and(exists("qty"), nin("qty", 5, 15))

Evaluation

The evaluation operator methods include the following:

  • mod: Performs a modulo operation on the value of a field and selects documents with a specified result.

  • regex: Selects documents where values match a specified regular expression.

  • text: Selects documents matching a full-text search expression.

  • where: Matches documents that satisfy a JavaScript expression.

Examples

The following example assumes a collection that has a text index in the field abstract. It selects documents that have an abstract field containing the term "coffee":

text("coffee")

Text indexes allow case-sensitive searches. The following example selects documents that have an abstract field containing the exact term "coffee":

text("coffee", TextSearchOptions().caseSensitive(true))

Text indexes allow diacritic-sensitive searches. The following example selects documents that have an abstract field containing the exact term "café":

text("café", TextSearchOptions().diacriticSensitive(true))

Bitwise

The bitwise operator methods include the following:

  • bitsAllSet: Selects documents where all the specified bits of a field are set.

  • bitsAllClear: Selects documents where all the specified bits of a field are clear.

  • bitsAnySet: Selects documents where at least one of the specified bits of a field are set.

  • bitsAnyClear: Selects documents where at least one of the specified bits of a field are clear.

Examples

The example selects documents that have a bitField field with bits set at positions of the corresponding bitmask 50 (00110010):

bitsAllSet("bitField", 50)

Geospatial

The geospatial operator methods include the following:

  • geoWithin: Selects all documents containing a field whose value is a GeoJSON geometry that falls within a bounding GeoJSON geometry.

  • geoWithinBox: Selects all documents containing a field with grid coordinates data that exist entirely within the specified box.

  • geoWithinPolygon: Selects all documents containing a field with grid coordinates data that exist entirely within the specified polygon.

  • geoWithinCenter: Selects all documents containing a field with grid coordinates data that exist entirely within the specified circle.

  • geoWithinCenterSphere: Selects geometries containing a field with geospatial data (GeoJSON or legacy coordinate pairs) that exist entirely within the specified circle, using spherical geometry.

  • geoIntersects: Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects.

  • near: Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near.

  • nearSphere: Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d indexes support $nearSphere.

To make it easier to construct GeoJSON-based filters, the driver also includes a full GeoJSON class hierarchy:

  • Point: Representation of a GeoJSON Point

  • MultiPoint: Representation of a GeoJSON MultiPoint

  • LineString: Representation of a GeoJSON LineString

  • MultiLineString: Representation of a GeoJSON MultiLineString

  • Polygon: Representation of a GeoJSON Polygon

  • MultiPolygon: Representation of a GeoJSON MultiPolygon

  • GeometryCollection: Representation of a GeoJSON GeometryCollection

Examples

The following example creates a filter that selects all documents where the geo field contains a GeoJSON Geometry object that falls within the given polygon:

val polygon: Polygon = Polygon(Seq(Position(0, 0), Position(4, 0),
                                   Position(4, 4), Position(0, 4),
                                   Position(0, 0)))
geoWithin("geo", polygon)

The following example creates a filter that selects all documents where the geo field contains a GeoJSON Geometry object that intersects the given Point:

geoIntersects("geo", Point(Position(4, 0)))

Back

Builders

Next

Projections