Package org.springframework.data.mongodb.core.query

Class Criteria

java.lang.Object

org.springframework.data.mongodb.core.query.Criteria

All Implemented Interfaces:

CriteriaDefinition

Direct Known Subclasses:

GridFsCriteria

public class Criteria
extends Object
implements CriteriaDefinition

Central class for creating queries. It follows a fluent API style so that you can easily chain together multiple criteria. Static import of the Criteria.where method improves readability.

Author:

Thomas Risberg, Oliver Gierke, Thomas Darimont, Christoph Strobl, Mark Paluch, Andreas Zink, Ziemowit Stolarczyk, Clément Petit, James McNee

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Criteria.BitwiseCriteriaOperators	MongoDB specific bitwise query operators like $bitsAllClear, $bitsAllSet,... for usage with bits() and Query.

Constructor Summary

Constructors

Modifier	Constructor	Description
	Criteria()
	Criteria(String key)
protected	Criteria(List<Criteria> criteriaChain, String key)

Method Summary

Modifier and Type	Method	Description
Criteria	alike(Example<?> sample)	Creates a criterion using the given object as a pattern.
Criteria	all(Object... values)	Creates a criterion using the $all operator.
Criteria	all(Collection<?> values)	Creates a criterion using the $all operator.
Criteria	and(String key)	Static factory method to create a Criteria using the provided key
Criteria	andDocumentStructureMatches(MongoJsonSchema schema)	Creates a criterion ($jsonSchema) matching documents against a given structure defined by the MongoJsonSchema.
Criteria	andOperator(Collection<Criteria> criteria)	Creates a criteria using the $and operator for all of the provided criteria.
Criteria	andOperator(Criteria... criteria)	Creates a criteria using the $and operator for all of the provided criteria.
Criteria.BitwiseCriteriaOperators	bits()	Use Criteria.BitwiseCriteriaOperators as gateway to create a criterion using one of the bitwise operators like $bitsAllClear.
static Criteria	byExample(Object example)	Static factory method to create a Criteria matching an example object.
static Criteria	byExample(Example<?> example)	Static factory method to create a Criteria matching an example object.
Criteria	elemMatch(Criteria criteria)	Creates a criterion using the $elemMatch operator
boolean	equals(Object obj)
Criteria	exists(boolean value)	Creates a criterion using the $exists operator.
static Criteria	expr(MongoExpression expression)	Static factory method to create a Criteria matching a documents against the given expression.
org.bson.Document	getCriteriaObject()	Get Document representation.
String	getKey()	Get the identifying key.
protected org.bson.Document	getSingleCriteriaObject()
Criteria	gt(Object value)	Creates a criterion using the $gt operator.
Criteria	gte(Object value)	Creates a criterion using the $gte operator.
int	hashCode()
Criteria	in(Object... values)	Creates a criterion using the $in operator.
Criteria	in(Collection<?> values)	Creates a criterion using the $in operator.
Criteria	intersects(GeoJson geoJson)	Creates criterion using $geoIntersects operator which matches intersections of the given geoJson structure and the documents one.
Criteria	is(Object value)	Creates a criterion using equality
Criteria	isNull()	Creates a criterion using null equality comparison which matches documents that either contain the item field whose value is null or that do not contain the item field.
Criteria	isNullValue()	Creates a criterion using a BsonType comparison which matches only documents that contain the item field whose value is equal to BsonType.NULL.
Criteria	lt(Object value)	Creates a criterion using the $lt operator.
Criteria	lte(Object value)	Creates a criterion using the $lte operator.
static Criteria	matchingDocumentStructure(MongoJsonSchema schema)	Static factory method to create a Criteria matching documents against a given structure defined by the MongoJsonSchema using ($jsonSchema) operator.
Criteria	maxDistance(double maxDistance)	Creates a geo-spatial criterion using a $maxDistance operation, for use with $near or $nearSphere.
Criteria	minDistance(double minDistance)	Creates a geospatial criterion using a $minDistance operation, for use with $near or $nearSphere.
Criteria	mod(Number value, Number remainder)	Creates a criterion using the $mod operator.
Criteria	ne(Object value)	Creates a criterion using the $ne operator.
Criteria	near(Point point)	Creates a geospatial criterion using a $near operation.
Criteria	nearSphere(Point point)	Creates a geospatial criterion using a $nearSphere operation.
Criteria	nin(Object... values)	Creates a criterion using the $nin operator.
Criteria	nin(Collection<?> values)	Creates a criterion using the $nin operator.
Criteria	norOperator(Collection<Criteria> criteria)	Creates a criteria using the $nor operator for all of the provided criteria.
Criteria	norOperator(Criteria... criteria)	Creates a criteria using the $nor operator for all of the provided criteria.
Criteria	not()	Creates a criterion using the $not meta operator which affects the clause directly following
Criteria	orOperator(Collection<Criteria> criteria)	Creates a criteria using the $or operator for all of the provided criteria.
Criteria	orOperator(Criteria... criteria)	Creates a criteria using the $or operator for all of the provided criteria.
Criteria	regex(String regex)	Creates a criterion using a $regex operator.
Criteria	regex(String regex, String options)	Creates a criterion using a $regex and $options operator.
Criteria	regex(Pattern pattern)	Syntactical sugar for is(Object) making obvious that we create a regex predicate.
Criteria	regex(org.bson.BsonRegularExpression regex)	Use a MongoDB native BsonRegularExpression.
Criteria	sampleRate(double sampleRate)	Creates a criterion using the $sampleRate operator.
Criteria	size(int size)	Creates a criterion using the $size operator.
Criteria	type(int typeNumber)	Creates a criterion using the $type operator.
Criteria	type(Collection<JsonSchemaObject.Type> types)	Creates a criterion using the $type operator.
Criteria	type(JsonSchemaObject.Type... types)	Creates a criterion using the $type operator.
static Criteria	where(String key)	Static factory method to create a Criteria using the provided key
Criteria	within(Shape shape)	Creates a geospatial criterion using a $geoWithin operation.
Criteria	withinSphere(Circle circle)	Creates a geospatial criterion using a $geoWithin $centerSphere operation.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Criteria

public Criteria()

Criteria

public Criteria(String key)

Criteria

protected Criteria(List<Criteria> criteriaChain,
 String key)

Method Details

where

public static Criteria where(String key)

Static factory method to create a Criteria using the provided key

Parameters:

key - the property or field name.

Returns:

new instance of Criteria.

byExample

public static Criteria byExample(Object example)

Static factory method to create a Criteria matching an example object.

Parameters:

example - must not be null.

Returns:

new instance of Criteria.

Since:

1.8

See Also:

• alike(Example)

byExample

public static Criteria byExample(Example<?> example)

Static factory method to create a Criteria matching an example object.
By default the Example uses typed matching restricting it to probe assignable types. For example, when sticking with the default type key (_class), the query has restrictions such as _class : { $in : [com.acme.Person] } .
To avoid the above-mentioned type restriction use an UntypedExampleMatcher with Example.of(Object, org.springframework.data.domain.ExampleMatcher).

Parameters:

example - must not be null.

Returns:

new instance of Criteria.

Since:

1.8

See Also:

• alike(Example)

matchingDocumentStructure

public static Criteria matchingDocumentStructure(MongoJsonSchema schema)

Static factory method to create a Criteria matching documents against a given structure defined by the MongoJsonSchema using ($jsonSchema) operator.

Parameters:

schema - must not be null.

Returns:

this

Since:

2.1

See Also:

• MongoDB Query operator: $jsonSchema

expr

public static Criteria expr(MongoExpression expression)

Static factory method to create a Criteria matching a documents against the given expression.

The expression can be either something that directly renders to the store native representation like

 expr(() -> Document.parse("{ $gt : [ '$spent', '$budget'] }")))
 

or an AggregationExpression which will be subject to context (domain type) specific field mapping.

 expr(valueOf("amountSpent").greaterThan("budget"))
 

Parameters:

expression - must not be null.

Returns:

new instance of Criteria.

Since:

4.1

and

public Criteria and(String key)

Static factory method to create a Criteria using the provided key

Returns:

new instance of Criteria.

is

public Criteria is(@Nullable
 Object value)

Creates a criterion using equality

Parameters:

value - can be null.

Returns:

this.

isNull

public Criteria isNull()

Creates a criterion using null equality comparison which matches documents that either contain the item field whose value is null or that do not contain the item field.
Use isNullValue() to only query for documents that contain the field whose value is equal to BsonType.NULL.
Use exists(boolean) to query for documents that do (not) contain the field.

Returns:

this.

Since:

3.3

See Also:

• Query for Null or Missing Fields: Equality Filter

isNullValue

public Criteria isNullValue()

Creates a criterion using a BsonType comparison which matches only documents that contain the item field whose value is equal to BsonType.NULL.
Use isNull() to query for documents that contain the field with a null value or do not contain the field at all.
Use exists(boolean) to query for documents that do (not) contain the field.

Returns:

this.

Since:

3.3

See Also:

• Query for Null or Missing Fields: Type Check

ne

public Criteria ne(@Nullable
 Object value)

Creates a criterion using the $ne operator.

Parameters:

value - can be null.

Returns:

this.

See Also:

• MongoDB Query operator: $ne

lt

public Criteria lt(Object value)

Creates a criterion using the $lt operator.

Parameters:

value - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $lt

lte

public Criteria lte(Object value)

Creates a criterion using the $lte operator.

Parameters:

value - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $lte

gt

public Criteria gt(Object value)

Creates a criterion using the $gt operator.

Parameters:

value - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $gt

gte

public Criteria gte(Object value)

Creates a criterion using the $gte operator.

Parameters:

value - can be null.

Returns:

this.

See Also:

• MongoDB Query operator: $gte

in

public Criteria in(Object... values)

Creates a criterion using the $in operator.

Parameters:

values - the values to match against

Returns:

this.

See Also:

• MongoDB Query operator: $in

in

public Criteria in(Collection<?> values)

Creates a criterion using the $in operator.

Parameters:

values - the collection containing the values to match against

Returns:

this.

See Also:

• MongoDB Query operator: $in

nin

public Criteria nin(Object... values)

Creates a criterion using the $nin operator.

Parameters:

values -

Returns:

this.

See Also:

• MongoDB Query operator: $nin

nin

public Criteria nin(Collection<?> values)

Creates a criterion using the $nin operator.

Parameters:

values - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $nin

mod

public Criteria mod(Number value,
 Number remainder)

Creates a criterion using the $mod operator.

Parameters:

value - must not be null.

remainder - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $mod

all

public Criteria all(Object... values)

Creates a criterion using the $all operator.

Parameters:

values - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $all

all

public Criteria all(Collection<?> values)

Creates a criterion using the $all operator.

Parameters:

values - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $all

size

public Criteria size(int size)

Creates a criterion using the $size operator.

Parameters:

size -

Returns:

this.

See Also:

• MongoDB Query operator: $size

exists

public Criteria exists(boolean value)

Creates a criterion using the $exists operator.

Parameters:

value -

Returns:

this.

See Also:

• MongoDB Query operator: $exists

sampleRate

public Criteria sampleRate(double sampleRate)

Creates a criterion using the $sampleRate operator.

Parameters:

sampleRate - sample rate to determine number of documents to be randomly selected from the input. Must be between 0 and 1.

Returns:

this.

Since:

3.3

See Also:

• MongoDB Query operator: $sampleRate

type

public Criteria type(int typeNumber)

Creates a criterion using the $type operator.

Parameters:

typeNumber -

Returns:

this.

See Also:

• MongoDB Query operator: $type

type

public Criteria type(JsonSchemaObject.Type... types)

Creates a criterion using the $type operator.

Parameters:

types - must not be null.

Returns:

this.

Since:

2.1

See Also:

• MongoDB Query operator: $type

type

public Criteria type(Collection<JsonSchemaObject.Type> types)

Creates a criterion using the $type operator.

Parameters:

types - must not be null.

Returns:

this.

Since:

3.2

See Also:

• MongoDB Query operator: $type

not

public Criteria not()

Creates a criterion using the $not meta operator which affects the clause directly following

Returns:

this.

See Also:

• MongoDB Query operator: $not

regex

public Criteria regex(String regex)

Creates a criterion using a $regex operator.

Parameters:

regex - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $regex

regex

public Criteria regex(String regex,
 @Nullable
 String options)

Creates a criterion using a $regex and $options operator.

Parameters:

regex - must not be null.

options - can be null.

Returns:

this.

See Also:

• MongoDB Query operator: $regex

regex

public Criteria regex(Pattern pattern)

Syntactical sugar for is(Object) making obvious that we create a regex predicate.

Parameters:

pattern - must not be null.

Returns:

this.

regex

public Criteria regex(org.bson.BsonRegularExpression regex)

Use a MongoDB native BsonRegularExpression.

Parameters:

regex - must not be null.

Returns:

this.

withinSphere

public Criteria withinSphere(Circle circle)

Creates a geospatial criterion using a $geoWithin $centerSphere operation. This is only available for Mongo 2.4 and higher.

Parameters:

circle - must not be null

Returns:

this.

See Also:

• MongoDB Query operator: $geoWithin
• MongoDB Query operator: $centerSphere

within

public Criteria within(Shape shape)

Creates a geospatial criterion using a $geoWithin operation.

Parameters:

shape - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $geoWithin

near

public Criteria near(Point point)

Creates a geospatial criterion using a $near operation.

Parameters:

point - must not be null

Returns:

this.

See Also:

• MongoDB Query operator: $near

nearSphere

public Criteria nearSphere(Point point)

Creates a geospatial criterion using a $nearSphere operation. This is only available for Mongo 1.7 and higher.

Parameters:

point - must not be null

Returns:

this.

See Also:

• MongoDB Query operator: $nearSphere

intersects

public Criteria intersects(GeoJson geoJson)

Creates criterion using $geoIntersects operator which matches intersections of the given geoJson structure and the documents one. Requires MongoDB 2.4 or better.

Parameters:

geoJson - must not be null.

Returns:

this.

Since:

1.8

maxDistance

public Criteria maxDistance(double maxDistance)

Creates a geo-spatial criterion using a $maxDistance operation, for use with $near or $nearSphere.

NOTE: The unit of measure for distance may depends on the used coordinate representation (legacy vs. geoJson) as well as the target operation.

Parameters:

maxDistance - radians or meters

Returns:

this.

See Also:

• MongoDB Query operator: $maxDistance

minDistance

public Criteria minDistance(double minDistance)

Creates a geospatial criterion using a $minDistance operation, for use with $near or $nearSphere.

NOTE: The unit of measure for distance may depends on the used coordinate representation (legacy vs. geoJson) as well as the target operation.

Parameters:

minDistance - radians or meters

Returns:

this.

Since:

1.7

elemMatch

public Criteria elemMatch(Criteria criteria)

Creates a criterion using the $elemMatch operator

Parameters:

criteria - must not be null.

Returns:

this.

See Also:

• MongoDB Query operator: $elemMatch

alike

public Criteria alike(Example<?> sample)

Creates a criterion using the given object as a pattern.

Parameters:

sample - must not be null.

Returns:

this.

Since:

1.8

andDocumentStructureMatches

public Criteria andDocumentStructureMatches(MongoJsonSchema schema)

Creates a criterion ($jsonSchema) matching documents against a given structure defined by the MongoJsonSchema.
NOTE: $jsonSchema cannot be used on field/property level but defines the whole document structure. Please use MongoJsonSchema.MongoJsonSchemaBuilder.properties(JsonSchemaProperty...) to specify nested fields or query them using the $type operator.

Parameters:

schema - must not be null.

Returns:

this

Since:

2.1

See Also:

• MongoDB Query operator: $jsonSchema

bits

public Criteria.BitwiseCriteriaOperators bits()

Use Criteria.BitwiseCriteriaOperators as gateway to create a criterion using one of the bitwise operators like $bitsAllClear.

Returns:

new instance of Criteria.BitwiseCriteriaOperators. Never null.

Since:

2.1

orOperator

public Criteria orOperator(Criteria... criteria)

Creates a criteria using the $or operator for all of the provided criteria.

Note that MongoDB doesn't support an $nor operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

orOperator

public Criteria orOperator(Collection<Criteria> criteria)

Creates a criteria using the $or operator for all of the provided criteria.

Note that MongoDB doesn't support an $nor operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

Since:

3.2

norOperator

public Criteria norOperator(Criteria... criteria)

Creates a criteria using the $nor operator for all of the provided criteria.

Note that MongoDB doesn't support an $nor operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

norOperator

public Criteria norOperator(Collection<Criteria> criteria)

Creates a criteria using the $nor operator for all of the provided criteria.

Note that MongoDB doesn't support an $nor operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

Since:

3.2

andOperator

public Criteria andOperator(Criteria... criteria)

Creates a criteria using the $and operator for all of the provided criteria.

Note that MongoDB doesn't support an $and operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

andOperator

public Criteria andOperator(Collection<Criteria> criteria)

Creates a criteria using the $and operator for all of the provided criteria.

Note that MongoDB doesn't support an $and operator to be wrapped in a $not operator.

Parameters:

criteria - must not be null.

Returns:

this.

Throws:

IllegalArgumentException - if this method follows a not() call directly.

Since:

3.2

getKey

@Nullable
public String getKey()

Description copied from interface: CriteriaDefinition

Get the identifying key.

Specified by:

getKey in interface CriteriaDefinition

Returns:

can be null.

getCriteriaObject

public org.bson.Document getCriteriaObject()

Description copied from interface: CriteriaDefinition

Get Document representation.

Specified by:

getCriteriaObject in interface CriteriaDefinition

Returns:

never null.

getSingleCriteriaObject

protected org.bson.Document getSingleCriteriaObject()

equals

public boolean equals(@Nullable
 Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object