ReactiveMongo-Criteria

Note: this fork created mainly for publishing some artifacts while the original repo is stale.

resolvers += Resolver.bintrayRepo("danslapman", "maven")

libraryDependencies += "danslapman" %% "reactivemongo-criteria" % "0.12.7"

Adds a Criteria DSL for creating ReactiveMongo queries.

Brief Review of Where Criteria Officially Lives

This project was integrated into ReactiveMongo-Extensions for a couple of years. Since ReactiveMongo-Extensions has been discontinued, ReactiveMongo-Criteria has been migrated back to its original home (this repository).

Only the portion of ReactiveMongo-Extensions originally from this project has been extracted from the now-defunct extensions project. ReactiveMongo-Criteria should remain API compatible with versions of ReactiveMongo from 0.12 as this library only depends on the public API from the driver.

Overview

Original Query Syntax

The reactivemongo.api.collections.GenericCollection type provides the find method used to find documents matching a criteria. It is this interaction which the DSL targets. Originally, providing a selector to find had an interaction similar to:

  val cursor = collection.find(BSONDocument("firstName" -> "Jack")).cursor[BSONDocument]

This is, of course, still supported as the DSL does not preclude this usage.

Criteria DSL

Untyped DSL Support

What the DSL does provide is the ablity to formulate queries thusly:

// Using an Untyped.criteria
{
  import reactivemongodsl.criteria._
  import Untyped._
  
  // The MongoDB properties referenced are not enforced by the compiler
  // to belong to any particular type.  This is what is meant by "Untyped".
  val adhoc = criteria.firstName === "Jack" && criteria.age >= 18;
  val cursor =   collection.find(adhoc).cursor[BSONDocument];
}

Another form which achieves the same result is to use one of the where methods available:

// Using one of the Untyped.where overloads
{
  import reactivemongodsl.criteria._
  import Untyped._
  
  val cursor = collection.find(
    where (_.firstName === "Jack" && _.age >= 18)
    ).cursor[BSONDocument];
}

There are overloads for between 1 and 22 place holders using the where method. Should more than 22 be needed, then the 1 argument version should be used with a named parameter. This allows an infinite number of property constraints to be specified.

Typed DSL Support

For situations where the MongoDB document structure is well known and a developer wishes enforce property existence during compilation, the Typed Criteria can be used:

  {
  // Using a Typed criteria which restricts properties to those
  // within a given type and/or those directly accessible
  // through property selectors.
  import reactivemongodsl.criteria._
  import Typed._

  case class Nested (rating : Double)
  case class ExampleDocument (aProperty : String, another : Int, nested : Nested)

  val byKnownProperties = criteria[ExampleDocument] (_.aProperty) =~ "^[A-Z]\\w+" && (
    criteria[ExampleDocument] (_.another) > 0 ||
    criteria[ExampleDocument] (_.nested.rating) < 10.0
	);

  val cursor = collection.find(byKnownProperties).cursor[BSONDocument];
  }

When the Typed version is employed, compilation will fail if the provided property navigation does not exist from the root type (specified as the type parameter to criteria above) or the leaf type is not type-compatible with the value(s) provided (if any).

An easy way to think of this is that if it doesn't compile in "regular usage", then it definitely will not when used in a Typed.criteria.

Usage Considerations

Note that Typed and Untyped serve different needs. When the structure of a document collection is both known and identified as static, Typed makes sense to employ. However, Untyped is compelling when document structure can vary within a collection. These are considerations which can easily vary between projects and even within different modules of one project.

Feel free to use either or both Typed and Untyped as they make sense for the problem at hand. One thing to keep in mind is that the examples shown above assumes only one is in scope.

Roadmap

This section details the functionality either currently or planned to be supported by ReactiveMongo-Criteria.

Ability to formulate queries without requiring knowledge of document structure. COMPLETE
Ability to ''type check'' query constraints by specifying a Scala type. COMPLETE
Define and add support for an EDSL specific to projections. TBD

Operators

When using the Criteria DSL, the fact that the operators adhere to the expectations of both programmers and Scala precedences, most uses will "just work." For example, explicitly defining grouping is done with parentheses, just as you would do with any other bit of Scala code.

For the purposes of the operator API reference, assume the following code is in scope:

import reactivemongodsl.criteria.Untyped._

Comparison Operators

With the majority of comparison operators, keep in mind that the definition of their ordering is dependent on the type involved. For example, strings will use lexigraphical ordering whereas numbers use natural ordering.

===, @== Matches properties based on value equality.

criteria.aProperty === "value"

criteria.aProperty @== "value"

<>, =/=, !== Matches properties which do not have the given value.

criteria.aProperty <> "value"

criteria.aProperty =/= "value"

criteria.aProperty !== "value"

< Matches properties which compare "less than" a given value.

criteria.aNumber < 99

<= Matches properties which compare "less than or equal to" a given value.

criteria.aNumber <= 99

> Matches properties which compare "greater than" a given value.

criteria.aProperty > "Alice"

>= Matches properties which compare "greater than or equal to" a given value.

criteria.aNumber >= 100

Existence Operators

exists Matches any document which has the specified field. Use the unary not operator to match based on the leaf property being absent entirely.

criteria.aProperty.exists	// Requires 'aProperty' to be in the document
!criteria.aProperty.exists	// Only matches documents without 'aProperty'

in Matches properties which equal one of the given values or array properties having one element which equals any of the given values. Combine with the unary not operator to specify "not in."

criteria.ranking.in (1, 2, 3, 4, 5)
!criteria.ranking.in (1, 2, 3, 4, 5)

all Matches array properties which contain all of the given values.

criteria.strings.all ("hello", "world")

String Operators

=~ Matches a string property which satisfies the given regular expression String, optionally with regex flags.

criteria.aProperty =~ """^(value)|(someting\s+else)"""
criteria.aProperty =~ """^(value)|(someting\s+else)""" -> IgnoreCase

!~ Matches a string property which does not satisfy the given regular expression String, optionally with regex flags.

criteria.aProperty !~ """\d+"""
criteria.aProperty !~ """foo.*bar""" -> (IgnoreCase | MultilineMatching)

Logical Operators

! The unary not operator provides logical negation of an Expression.

!(criteria.aProperty === "value")

&& Defines logical conjunction (''AND'').

criteria.aProperty === "value" && criteria.another > 0

!&& Defines negation of conjunction (''NOR'').

criteria.aProperty === "value" !&& criteria.aProperty @== "other value"

|| Defines logical disjunction (''OR'').

criteria.aProperty === "value" || criteria.aProperty === "other value"

danslapman/ReactiveMongo-Criteria