Mongoose's query API provides some of the most powerful search tools available in MongoDB, and are available as chainable methods to any Mongoose model API query such as find, findOne, or where:
Property | Example | Description |
all | query.all('tags', ['person', 'place']); | Returns documents where the value of a field is an array that contains all the specified elements. |
and | query.and([{ status: 'priority' }, { title: 'foobar' }]); | Performs a logical and operation on an array of expressions and returns the documents that match them. |
batchSize | query.batchSize(100) | Sets the number of documents to be returned in each batch by MongoDB. Unlike limit, which sets the total number or results returned, batch is simply how the total matches will be broken apart. |
box | query.box({ ll : [40, -24], ur :[43, -25] }); | Sets a geospatial query result using a provided rectangle definition. |
cast | query.cast(Post); | Sets the query schema to that of a defined model or document. |
catch | query.catch(); | A promise catch for failed queries. |
circle | query.circle('locations', { center: [20, 20], radius: 10}); | Sets a geospatial query result using a provided circle definition. |
collation | query.collation({ 'locale': 'fr_CA' }); |
Allows language-specific rules for string comparison, such as rules for lettercase and accent marks. |
comment | query.comment('title search'); | Attach a comment to a query that can be retrieved in any context that it is used. |
count | query.count(); | Sets query to only return the count of matches. |
cursor | query.cursor(). on('data', function(doc) {}); | Returns a reference to the MongoDB driver cursor; useful for doing stream operations with MongoDB queries. |
deleteMany | query.deleteMany(); | Sets query to execute a deleteMany operation on the matches. |
deleteOne | query.deleteOne(); | Sets query to execute a deleteOne operation on the first match. |
distinct | query.distinct('title'); | Sets query to execute a distinct operation, which will return a list of unique values for the field on the same collection. |
elemMatch | query.elemMatch('score', { $gte: 75, $lt: 100 }); |
Returns documents with an array field that matches one or more queries. |
equals | query.where('title').equals('foobar'); | Adds a complementary comparison value to another query operation for equality. |
exec | query.exec(); | Executes the query. |
exists | query.exists('title', true); | When provided with a field and a true Boolean, returns documents that have that field set to null. When Boolean is false, returns documents that do not have that field. |
find | query.find(); | Returns documents that match a provided query; can be chained with other find and where query results to act as a filter. |
findOne | query.find(); | Returns a single documents that matches a provided query. |
findOneAndRemove | query.findOneAndRemove(); | Removes a single document that matches a provided query. |
findOneAndUpdate | query.findOneAndUpdate(); | Updates a single document that matches a provided query. |
geometry | query.geometry({ type: 'Point', coordinates: [100, 200] } | Sets a geospatial query using a $geoJSON definition. |
getQuery | query.getQuery(); | Returns the current query conditions. |
getUpdate | query.getUpdate(); | Returns the current update operations on this query. |
gt | query.gt('score', 2000); | Performs a logical greater than operation on this query. |
gte | query.gte('score', 2000); | Performs a logical greater than or equal operation on this query. |
hint | query.hint({title: 1}); | Sets a preferred index for MongoDB to use in resolving the query. |
in | query.in('tags', ['person', 'place', 'thing']); | Returns documents where the value of a field equals any value in the specified array. |
intersects | query.intersects({ type: 'LineString' , coordinates: [[150.0, 30.0], [150, 19.0]] }) | Sets a geospatial intersection query using a $geoJSON definition. |
lean | query.lean(); | Optimization flag for returning normal JSON objects instead of Mongoose documents. |
limit | query.limit(20) | Sets the total number of documents returned with the query. |
lt | query.lt('score', 2000); | Performs a logical less than operation on this query. |
lte | query.lte('score', 2000); | Performs a logical less than or equal operation on this query. |
maxDistance | query.maxDistance('location', 200); | Sets a geospatial maximum distance query. |
maxScan | query.maxScan(70); | Constrains a query to only scan a specified number of documents. Useful for preventing long running queries. |
merge | query.merge(anotherQuery); | Merges another query onto the current query. |
mod | query.mod('score', [5, 2]); | Returns documents using a modulo operation on a provided field, by a provided devisor, that matches the provided remainder. |
mongooseOptions | query.mongooseOptions(); | Returns Mongoose-specific options for the current query. |
ne | query.ne('title', 'foobar'); | Performs a logical not equal operation on this query. |
near | query.near({ center: [10, 10] }); | Sets a geospatial nearby query. |
nin | query.nin('tags', ['people', 'places']); | Returns documents that do not have any of the provided values for a field, or the field does not exist. |
nor | query.nor([{ status: 'priority' }, { title: 'foobar' }]); | Performs a logical nor operation using the provided expressions and returns the documents that match none of them. |
or | query.or(([{ status: 'priority' }, { title: 'foobar' }]); | Performs a logical or operation using the provided expressions and returns the documents that match any of them. |
polygon | query.polygon('location', [10,20], [51, 35], [70,15]) | Sets a geospatial polygon query. |
populate | query.populate('author'); | Similar to Model.populate, allows you to populate subdocument fields of query results. |
read | query.read('primary'); | If using replicas, allows you define the MongoDB nodes to read from. |
regex | query.regex('title', /foobar/); | Returns documents with field values that return matches from a provided regular expression. |
remove | query.remove(); | Similar to Model.remove, will remove documents that match the query. |
replaceOne | query.replaceOne({}); | Similar to Model.replaceOne, will replace the first matched document from the query with the provided one. |
select | query.select('title published'); | Provides query projection to MongoDB for which fields to include in matched document results. Fields to be included are provided as a string of fieldnames. Fields can also be prefixed with -- to exclude specific values from results. |
selected | query.selected(); | Returns whether a select query projection has been defined on this query. |
selectedExclusively | query.selectedExclusively(); | Returns whether a select query project was used exclusively ('-field') on this query. |
selectedInclusively | query.selectedInclusively(); | Returns whether a select query project was used inclusively ('field') on this query. |
setOptions | query.setOptions({}); |
An alternative way to set the tailable, sort, limit, skip, maxScan, batchSize, comment, snapshot, hint, read, lean, and safe properties. |
size | query.size('tags', 5); | Returns documents that match the length for a provided field. |
skip | query.skip(20); | Sets an offset for the documents to be returned. Usually used in conjunction with limit to implement pagination. |
slice | query.slice('tags', [20, 10]); | Returns a subset of elements within the provided property for the documents returned using a skip and limit parameter. |
snapshot | query.snapshot(); | Notifies MongoDB to prevent returning a document more than once if an intervening write operation moved a document. This is mostly used in sensitive multiuser session transactions. |
sort | query.sort('-published'); | Sets a sort order for the documents returned using a provided field in ascending order. Can be prefixed with a '-' to return values in descending order instead. |
stream | query.stream().on('data', function (item) {}); | Exposes a Node.js stream interface for the current query. |
tailable | query.tailable(); | Tells MongoDB to use a tailable cursor for this query. |
then | query.then(); | A promise catch for successful queries. |
toConstructor | var DoIt = query.toConstructor(); | A factory method for converting the current query state into a reusable query method. |
update | query.update({}); | Same as Model.update, will update documents that matches the query with the provided properties. |
updateMany | query.updateMany({}); | Same as Model.updateMany, will update all the documents that match the query with the provided properties. |
updateOne | query.updateOne({}); | Same as Model.updateOne, will update the first document that matches the query with the provided properties. |
where | query.where('title', 'foobar'); | Same as Model.where, allows you to provide a query for a field and value. |
$where | query.$where('this.title !== "foobar"'); | Same as Model.$where, allows you to provide a JavaScript expression as a query to MongoDB. |
within | query.within().geometry() | Sets a geospatial query within a predefined geospatial query shape, such as circle, rectangle, geometry, or polygon. |
$geoWithin | query.$geoWithin = false; |
Flag to tell MongoDB to opt out of using $geoWithin. |