package org.mongodb.morphia.query;


import com.mongodb.DBCollection;
import com.mongodb.DBObject;
import com.mongodb.ReadPreference;
import org.bson.types.CodeWScope;

import java.util.Map;
import java.util.concurrent.TimeUnit;


Author:Scott Hernandez
Type parameters:
  • <T> – The java type to query against
/** * @param <T> The java type to query against * @author Scott Hernandez */
public interface Query<T> extends QueryResults<T>, Cloneable {
Creates a container to hold 'and' clauses
Params:
  • criteria – the clauses to 'and' together
Returns:the container
/** * Creates a container to hold 'and' clauses * * @param criteria the clauses to 'and' together * @return the container */
CriteriaContainer and(Criteria... criteria);
Batch-size of the fetched result (cursor).
Params:
  • value – must be >= 0. A value of 0 indicates the server default.
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Batch-size of the fetched result (cursor). * * @param value must be >= 0. A value of 0 indicates the server default. * @return this * @deprecated use the methods that accept Options directly * @see FindOptions#batchSize(int) */
@Deprecated Query<T> batchSize(int value);
Creates and returns a copy of this Query.
Returns:this
/** * Creates and returns a copy of this {@link Query}. * * @return this */
Query<T> cloneQuery();
This makes it possible to attach a comment to a query. Because these comments propagate to the profile log, adding comments can make your profile data much easier to interpret and trace.
Params:
  • comment – the comment to add
See Also:
Returns:the Query to enable chaining of commands
@mongodb.driver.manualreference/operator/meta/comment $comment
Deprecated:use the methods that accept Options directly. This can be replicated with options.modifier("$comment", comment)
/** * This makes it possible to attach a comment to a query. Because these comments propagate to the profile log, adding comments can make * your profile data much easier to interpret and trace. * * @param comment the comment to add * @return the Query to enable chaining of commands * @mongodb.driver.manual reference/operator/meta/comment $comment * @see FindOptions#modifier(String, Object) * @deprecated use the methods that accept Options directly. This can be replicated with {@code options.modifier("$comment", comment)} */
@Deprecated Query<T> comment(String comment);
Creates a criteria to apply against a field
Params:
  • field – the field
Returns:the FieldEnd to define the criteria
/** * Creates a criteria to apply against a field * * @param field the field * @return the FieldEnd to define the criteria */
FieldEnd<? extends CriteriaContainerImpl> criteria(String field);
Disables cursor timeout on server.
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Disables cursor timeout on server. * * @return this * @deprecated use the methods that accept Options directly * @see FindOptions#noCursorTimeout(boolean) */
@Deprecated Query<T> disableCursorTimeout();
Disable snapshotted mode (default mode). This will be faster but changes made during the cursor may cause duplicates.
See Also:
Returns:this
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$snapshot", false)
/** * Disable snapshotted mode (default mode). This will be faster but changes made during the cursor may cause duplicates. * * @return this * @deprecated use the methods that accept Options directly. This can be replicated using {@code options.modifier("$snapshot", false)} * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> disableSnapshotMode();
Turns off validation (for all calls made after)
Returns:this
/** * Turns off validation (for all calls made after) * * @return this */
Query<T> disableValidation();
Enables cursor timeout on server.
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Enables cursor timeout on server. * * @return this * @deprecated use the methods that accept Options directly * @see FindOptions#noCursorTimeout(boolean) */
@Deprecated Query<T> enableCursorTimeout();
Enables snapshotted mode where duplicate results (which may be updated during the lifetime of the cursor) will not be returned. Not compatible with order/sort and hint.
See Also:
Returns:this
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$snapshot", true)
/** * Enables snapshotted mode where duplicate results (which may be updated during the lifetime of the cursor) will not be returned. Not * compatible with order/sort and hint. * * @return this * @deprecated use the methods that accept Options directly. This can be replicated using {@code options.modifier("$snapshot", true)} * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> enableSnapshotMode();
Turns on validation (for all calls made after); by default validation is on
Returns:this
/** * Turns on validation (for all calls made after); by default validation is on * * @return this */
Query<T> enableValidation();
Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information may be useful when optimizing a query.
Returns:Map describing the process used to return the query results.
@mongodb.driver.manualreference/operator/meta/explain/ explain
/** * Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information * may be useful when optimizing a query. * * @return Map describing the process used to return the query results. * @mongodb.driver.manual reference/operator/meta/explain/ explain */
Map<String, Object> explain();
Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information may be useful when optimizing a query.
Params:
  • options – the options to apply to the explain operation
Returns:Map describing the process used to return the query results.
@mongodb.driver.manualreference/operator/meta/explain/ explain
Since:1.3
/** * Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information * may be useful when optimizing a query. * * @param options the options to apply to the explain operation * @return Map describing the process used to return the query results. * @mongodb.driver.manual reference/operator/meta/explain/ explain * @since 1.3 */
Map<String, Object> explain(FindOptions options);
Fluent query interface: createQuery(Ent.class).field("count").greaterThan(7)...
Params:
  • field – the field
Returns:the FieldEnd to define the criteria
/** * Fluent query interface: {@code createQuery(Ent.class).field("count").greaterThan(7)...} * * @param field the field * @return the FieldEnd to define the criteria */
FieldEnd<? extends Query<T>> field(String field);
Create a filter based on the specified condition and value.

Note: Property is in the form of "name op" ("age >").

Valid operators are ["=", "==","!=", "<>", ">", "<", ">=", "<=", "in", "nin", "all", "size", "exists"]

Examples:

  • filter("yearsOfOperation >", 5)
  • filter("rooms.maxBeds >=", 2)
  • filter("rooms.bathrooms exists", 1)
  • filter("stars in", new Long[]{3, 4}) //3 and 4 stars (midrange?)
  • filter("quantity mod", new Long[]{4, 0}) // customers ordered in packs of 4)
  • filter("age >=", age)
  • filter("age =", age)
  • filter("age", age) (if no operator, = is assumed)
  • filter("age !=", age)
  • filter("age in", ageList)
  • filter("customers.loyaltyYears in", yearsList)

You can filter on id properties if this query is restricted to a Class.

Params:
  • condition – the condition to apply
  • value – the value to apply against
Returns:this
/** * Create a filter based on the specified condition and value. </p> <p><b>Note</b>: Property is in the form of "name op" ("age * >"). * <p/> * <p>Valid operators are ["=", "==","!=", "<>", ">", "<", ">=", "<=", "in", "nin", "all", "size", "exists"] </p> * <p/> * <p>Examples:</p> * <p/> * <ul> * <li>{@code filter("yearsOfOperation >", 5)}</li> * <li>{@code filter("rooms.maxBeds >=", 2)}</li> * <li>{@code filter("rooms.bathrooms exists", 1)}</li> * <li>{@code filter("stars in", new Long[]{3, 4}) //3 and 4 stars (midrange?)}</li> * <li>{@code filter("quantity mod", new Long[]{4, 0}) // customers ordered in packs of 4)}</li> * <li>{@code filter("age >=", age)}</li> * <li>{@code filter("age =", age)}</li> * <li>{@code filter("age", age)} (if no operator, = is assumed)</li> * <li>{@code filter("age !=", age)}</li> * <li>{@code filter("age in", ageList)}</li> * <li>{@code filter("customers.loyaltyYears in", yearsList)}</li> * </ul> * <p/> * <p>You can filter on id properties <strong>if</strong> this query is restricted to a Class<T>. * * @param condition the condition to apply * @param value the value to apply against * @return this */
Query<T> filter(String condition, Object value);
See Also:
Returns:the batch size
Deprecated:use the methods that accept Options directly
/** * @return the batch size * @see #batchSize(int) * @deprecated use the methods that accept Options directly * @see FindOptions#batchSize(int) */
@Deprecated int getBatchSize();
Returns:the DBCollection of the Query.
Deprecated:This is an internal method and subject to change or removal. Do not use.
/** * @return the {@link DBCollection} of the {@link Query}. * * @deprecated This is an internal method and subject to change or removal. Do not use. */
@Deprecated DBCollection getCollection();
Returns:the entity Class.
/** * @return the entity {@link Class}. */
Class<T> getEntityClass();
Returns:the Mongo fields DBObject.
Deprecated:This is an internal method and subject to change or removal. Do not use.
/** * @return the Mongo fields {@link DBObject}. * @deprecated This is an internal method and subject to change or removal. Do not use. */
@Deprecated DBObject getFieldsObject();
See Also:
Returns:the limit
Deprecated:use the methods that accept Options directly
/** * @return the limit * @see #limit(int) * @deprecated use the methods that accept Options directly * @see FindOptions#limit(int) */
@Deprecated int getLimit();
See Also:
Returns:the offset.
Deprecated:use the methods that accept Options directly
/** * @return the offset. * @see #offset(int) * @deprecated use the methods that accept Options directly * @see FindOptions#getSkip() */
@Deprecated int getOffset();
Returns:the Mongo query DBObject.
Deprecated:This is an internal method and subject to change or removal. Do not use.
/** * @return the Mongo query {@link DBObject}. * @deprecated This is an internal method and subject to change or removal. Do not use. */
@Deprecated DBObject getQueryObject();
Returns:the Mongo sort DBObject.
Deprecated:This is an internal method and subject to change or removal. Do not use.
/** * @return the Mongo sort {@link DBObject}. * @deprecated This is an internal method and subject to change or removal. Do not use. */
@Deprecated DBObject getSortObject();
Hints as to which index should be used.
Params:
  • idxName – the index name to hint
See Also:
Returns:this
Deprecated:use the methods that accept Options directly. This can be replicated with options.modifier("$hint", idxName)
/** * Hints as to which index should be used. * * @param idxName the index name to hint * @return this * @deprecated use the methods that accept Options directly. This can be replicated with {@code options.modifier("$hint", idxName)} * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> hintIndex(String idxName);
Limit the fetched result set to a certain number of values.
Params:
  • value – must be >= 0. A value of 0 indicates no limit. For values < 0, use FindOptions.batchSize(int) which is the preferred method
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Limit the fetched result set to a certain number of values. * * @param value must be >= 0. A value of 0 indicates no limit. For values < 0, use {@link FindOptions#batchSize(int)} which * is the preferred method * @return this * @deprecated use the methods that accept Options directly * @see FindOptions#limit(int) */
@Deprecated Query<T> limit(int value);

Specify the inclusive lower bound for a specific index in order to constrain the results of this query.

You can chain key/value pairs to build a constraint for a compound index. For instance:

query.lowerIndexBound(new BasicDBObject("a", 1).append("b", 2));

to build a constraint on index {"a", "b"}

Params:
  • lowerBound – The inclusive lower bound.
See Also:
Returns:this
@mongodb.driver.manualreference/operator/meta/min/ $min
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$min", new Document(...))
/** * <p> Specify the inclusive lower bound for a specific index in order to constrain the results of this query. <p/> You can chain * key/value pairs to build a constraint for a compound index. For instance: </p> <p> {@code query.lowerIndexBound(new * BasicDBObject("a", 1).append("b", 2)); } </p> <p> to build a constraint on index {@code {"a", "b"}} </p> * * @param lowerBound The inclusive lower bound. * @return this * @mongodb.driver.manual reference/operator/meta/min/ $min * @deprecated use the methods that accept Options directly. This can be replicated using * {@code options.modifier("$min", new Document(...)) } * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> lowerIndexBound(DBObject lowerBound);
Constrains the query to only scan the specified number of documents when fulfilling the query.
Params:
  • value – must be > 0. A value < 0 indicates no limit
See Also:
Returns:this
@mongodb.driver.manualreference/operator/meta/maxScan/#op._S_maxScan $maxScan
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$maxScan", value)
/** * Constrains the query to only scan the specified number of documents when fulfilling the query. * * @param value must be > 0. A value < 0 indicates no limit * @return this * @mongodb.driver.manual reference/operator/meta/maxScan/#op._S_maxScan $maxScan * @deprecated use the methods that accept Options directly. This can be replicated using {@code options.modifier("$maxScan", value) } * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> maxScan(int value);
Specifies a time limit for executing the query. Requires server version 2.6 or above.
Params:
  • maxTime – must be > 0. A value < 0 indicates no limit
  • maxTimeUnit – the unit of time to use
See Also:
Returns:this
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$maxTimeMS", MILLISECONDS.convert(value, unit))
/** * Specifies a time limit for executing the query. Requires server version 2.6 or above. * * @param maxTime must be > 0. A value < 0 indicates no limit * @param maxTimeUnit the unit of time to use * @return this * @deprecated use the methods that accept Options directly. This can be replicated using {@code options.modifier("$maxTimeMS", * MILLISECONDS.convert(value, unit)) } * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> maxTime(long maxTime, TimeUnit maxTimeUnit);
Starts the query results at a particular zero-based offset.
Params:
  • value – must be >= 0
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Starts the query results at a particular zero-based offset. * * @param value must be >= 0 * @return this * @deprecated use the methods that accept Options directly * @see FindOptions#skip(int) */
@Deprecated Query<T> offset(int value);
Creates a container to hold 'or' clauses
Params:
  • criteria – the clauses to 'or' together
Returns:the container
/** * Creates a container to hold 'or' clauses * * @param criteria the clauses to 'or' together * @return the container */
CriteriaContainer or(Criteria... criteria);
Sorts based on a property (defines return order). Examples:

  • order("age")
  • order("-age") (descending order)
  • order("age, date")
  • order("age,-date") (age ascending, date descending)
Params:
  • sort – the sort order to apply
Returns:this
/** * Sorts based on a property (defines return order). Examples: * <p/> * <ul> * <li>{@code order("age")}</li> * <li>{@code order("-age")} (descending order)</li> * <li>{@code order("age, date")}</li> * <li>{@code order("age,-date")} (age ascending, date descending)</li> * </ul> * * @param sort the sort order to apply * @return this */
Query<T> order(String sort);
Sorts based on a metadata (defines return order). Example: order(Meta.textScore()) ({textScore : { $meta: "textScore" }})
Params:
  • sort – the sort order to apply
Returns:this
/** * Sorts based on a metadata (defines return order). Example: * {@code order(Meta.textScore())} ({textScore : { $meta: "textScore" }}) * @param sort the sort order to apply * @return this */
Query<T> order(Meta sort);
Sorts based on a specified sort keys (defines return order).
Params:
  • sorts – the sort order to apply
Returns:this
/** * Sorts based on a specified sort keys (defines return order). * * @param sorts the sort order to apply * @return this */
Query<T> order(Sort... sorts);
Adds a field to the projection clause. Passing true for include will include the field in the results. Projected fields must all be inclusions or exclusions. You can not include and exclude fields at the same time with the exception of the _id field. The _id field is always included unless explicitly suppressed.
Params:
  • field – the field to project
  • include – true to include the field in the results
See Also:
Returns:this
/** * Adds a field to the projection clause. Passing true for include will include the field in the results. Projected fields must all * be inclusions or exclusions. You can not include and exclude fields at the same time with the exception of the _id field. The * _id field is always included unless explicitly suppressed. * * @param field the field to project * @param include true to include the field in the results * @return this * @see <a href="https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/">Project Fields to Return from Query</a> */
Query<T> project(String field, boolean include);
Adds an sliced array field to a projection.
Params:
  • field – the field to project
  • slice – the options for projecting an array field
See Also:
Returns:this
@mongodb.driver.manual/reference/operator/projection/slice/ $slice
/** * Adds an sliced array field to a projection. * * @param field the field to project * @param slice the options for projecting an array field * @return this * @see <a href="https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/">Project Fields to Return from Query</a> * @mongodb.driver.manual /reference/operator/projection/slice/ $slice */
Query<T> project(String field, ArraySlice slice);
Adds a metadata field to a projection.
Params:
  • meta – the metadata option for projecting
See Also:
Returns:this
@mongodb.driver.manualreference/operator/projection/meta/ $meta
/** * Adds a metadata field to a projection. * * @param meta the metadata option for projecting * @return this * @see <a href="https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/">Project Fields to Return from Query</a> * @mongodb.driver.manual reference/operator/projection/meta/ $meta */
Query<T> project(Meta meta);
Route query to non-primary node
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Route query to non-primary node * * @return this * @see ReadPreference#secondary() * @see ReadPreference#secondaryPreferred() * @deprecated use the methods that accept Options directly * @see FindOptions#readPreference(ReadPreference) * @see ReadPreference#secondary() * @see ReadPreference#secondaryPreferred() */
@Deprecated Query<T> queryNonPrimary();
Route query to primary node
See Also:
Returns:this
Deprecated:use the methods that accept Options directly.
/** * Route query to primary node * * @return this * @see ReadPreference#primary() * @deprecated use the methods that accept Options directly. * @see FindOptions#readPreference(ReadPreference) * @see ReadPreference#primary() * @see ReadPreference#primaryPreferred() */
@Deprecated Query<T> queryPrimaryOnly();
Limits the fields retrieved to those of the query type -- dangerous with interfaces and abstract classes
Returns:this
/** * Limits the fields retrieved to those of the query type -- dangerous with interfaces and abstract classes * * @return this */
Query<T> retrieveKnownFields();
Limits the fields retrieved
Params:
  • include – true if the fields should be included in the results. false to exclude them.
  • fields – the fields in question
Returns:this
Deprecated:use project(String, boolean) instead
/** * Limits the fields retrieved * * @param include true if the fields should be included in the results. false to exclude them. * @param fields the fields in question * @return this * @deprecated use {@link #project(String, boolean)} instead */
@Deprecated Query<T> retrievedFields(boolean include, String... fields);
Only return the index field or fields for the results of the query. If $returnKey is set to true and the query does not use an index to perform the read operation, the returned documents will not contain any fields
See Also:
Returns:the Query to enable chaining of commands
@mongodb.driver.manualreference/operator/meta/returnKey/#op._S_returnKey $returnKey
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$returnKey", true)
/** * Only return the index field or fields for the results of the query. If $returnKey is set to true and the query does not use an index * to perform the read operation, the returned documents will not contain any fields * * @return the Query to enable chaining of commands * @mongodb.driver.manual reference/operator/meta/returnKey/#op._S_returnKey $returnKey * @deprecated use the methods that accept Options directly. This can be replicated using {@code options.modifier("$returnKey", true) } * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> returnKey();
Perform a text search on the content of the fields indexed with a text index..
Params:
  • text – the text to search for
Returns:the Query to enable chaining of commands
@mongodb.driver.manualreference/operator/query/text/ $text
/** * Perform a text search on the content of the fields indexed with a text index.. * * @param text the text to search for * @return the Query to enable chaining of commands * @mongodb.driver.manual reference/operator/query/text/ $text */
Query<T> search(String text);
Perform a text search on the content of the fields indexed with a text index..
Params:
  • text – the text to search for
  • language – the language to use during the search
Returns:the Query to enable chaining of commands
@mongodb.driver.manualreference/operator/query/text/ $text
/** * Perform a text search on the content of the fields indexed with a text index.. * * @param text the text to search for * @param language the language to use during the search * @return the Query to enable chaining of commands * @mongodb.driver.manual reference/operator/query/text/ $text */
Query<T> search(String text, String language);

Specify the exclusive upper bound for a specific index in order to constrain the results of this query.

You can chain key/value pairs to build a constraint for a compound index. For instance:

query.upperIndexBound(new BasicDBObject("a", 1).append("b", 2));

to build a constraint on index {"a", "b"}

Params:
  • upperBound – The exclusive upper bound.
See Also:
Returns:this
@mongodb.driver.manualreference/operator/meta/max/ $max
Deprecated:use the methods that accept Options directly. This can be replicated using options.modifier("$max", new Document(...))
/** * <p> Specify the exclusive upper bound for a specific index in order to constrain the results of this query. <p/> You can chain * key/value pairs to build a constraint for a compound index. For instance: </p> <p> {@code query.upperIndexBound(new * BasicDBObject("a", 1).append("b", 2)); } </p> <p> to build a constraint on index {@code {"a", "b"}} </p> * * @param upperBound The exclusive upper bound. * @return this * @mongodb.driver.manual reference/operator/meta/max/ $max * @deprecated use the methods that accept Options directly. This can be replicated using * {@code options.modifier("$max", new Document(...)) } * @see FindOptions#modifier(String, Object) */
@Deprecated Query<T> upperIndexBound(DBObject upperBound);
Updates the ReadPreference to use
Params:
  • readPref – the ReadPreference to use
See Also:
Returns:this
Deprecated:use the methods that accept Options directly
/** * Updates the ReadPreference to use * * @param readPref the ReadPreference to use * @return this * @see ReadPreference * @deprecated use the methods that accept Options directly * @see FindOptions#readPreference(ReadPreference) */
@Deprecated Query<T> useReadPreference(ReadPreference readPref);
Limit the query using this javascript block; only one per query
Params:
  • js – the javascript block to apply
Returns:this
/** * Limit the query using this javascript block; only one per query * * @param js the javascript block to apply * @return this */
Query<T> where(String js);
Limit the query using this javascript block; only one per query
Params:
  • js – the javascript block to apply
Returns:this
/** * Limit the query using this javascript block; only one per query * * @param js the javascript block to apply * @return this */
Query<T> where(CodeWScope js); }