Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

363 lines (210 sloc) 8.615 kb

Queries

A Query is what is returned when calling many Model methods. These Query objects provide a chaining api to specify search terms, cursor options, hints, and other behavior.

Query#where

Lets you specify query terms with sugar.

query.where(path [, val])

path is a valid document path. val is optional. Its useful to omit val when used in conjunction with other query methods. For example:

query
.where('name', 'Space Ghost')
.where('age').gte(21).lte(65)
.run(callback)

In this case, gte() and lte() operate on the previous path if not explicitly passed. The above query results in the following query expression:

{ name: 'Space Ghost', age: { $gte: 21, $lte: 65 }}

Query#$where

Specifies the javascript function to run on MongoDB on each document scanned. See the MongoDB docs for details.

Model.find().$where(fn)

fn can be either a function or a string.

Query#$or, Query#or

Specifies the $or operator.

query.$or(array);

array is an array of expressions.

query.or([{ color: 'blue' }, { color: 'red' }]);

Query#gt, Query#$gt

Specifies a greater than expression.

query.$gt(path, val);

$gt is also one of the methods with extra chaining sugar: when only one argument is passed, it uses the path used the last call to where(). Example:

Model.where('age').$gt(21)

Results in:

{ age: { $gt: 21 }}

Query#gte, Query#$gte

Specifies a greater than or equal to expression.

query.$gte(path, val);

$gte is also one of the methods with extra chaining sugar: when only one argument is passed, it uses the path used the last call to where(). Example:

Model.where('age').$gte(21)

Results in:

{ age: { $gte: 21 }}

Query#lt,Query#$lt

Specifies a less than expression.

query.$lt(path, val);

$lt is also one of the methods with extra chaining sugar: when only one argument is passed, it uses the path used the last call to where(). Example:

Model.where('age').$lt(21)

Results in:

{ age: { $lt: 21 }}

Query#lte, Query#$lte

Specifies a less than or equal to expression.

query.$lte(path, val);

$lte is also one of the methods with extra chaining sugar: when only one argument is passed, it uses the path used the last call to where(). Example:

Model.where('age').$lte(21)

Results in:

{ age: { $lte: 21 }}

Query#ne, Query#$ne, Query#notEqualTo

Specifies the $ne operator.

query.$ne(path, val);

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used. Example:

query.where('_id').ne('4ecf92f31993a52c58e07f6a')

and

query.notEqualTo('_id', '4ecf92f31993a52c58e07f6a')

both result in

{ _id: { $ne: ObjectId('4ecf92f31993a52c58e07f6a') }}

Query#in, Query#$in

Specifies the $in operator.

query.$in(path, array)

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used.

query.where('tags').in(['game', 'fun', 'holiday'])

results in

{ tags: { $in: ['game', 'fun', 'holiday'] }}

Query#nin, Query#$nin

Specifies the $nin operator.

query.$nin(path, array)

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used.

query.where('games').nin(['boring', 'lame'])

results in

{ games: { $nin: ['boring', 'lame'] }}

Query#all, Query#$all

Specifies the $all operator.

query.$all(path, array)

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used.

query.where('games').all(['fun', 'exhausting'])

results in

{ games: { $all: ['fun', 'exhausting'] }}

Query#regex, Query#$regex

Specifies the $regex operator.

query.regex('name.first', /^a/i)

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used.

query.where('name.first').$regex(/^a/i)

results in

{ 'name.first': { $regex: /^a/i }}

Query#size, Query#$size

Specifies the $size operator.

query.$size(path, integer)

These methods have extra sugar in that when only one argument is passed, the path in the last call to where() is used.

query.size('comments', 2)
query.where('comments').size(2)

both result in

{ comments: { $size: 2 }}

Query#mod, Query#$mod

Specifies the $mod operator.

var array = [10, 1]
query.mod(path, array)

query.mod(path, 10, 1)

query.where(path).$mod(10, 1)

all result in

{ path: { $mod: [10, 1] }}

Query#exists, Query#$exists

Specifies the $exists operator.

query.exists(path, Boolean)

These methods have extra sugar in that when only one argument is passed, the path from the last call to where() is used.

Given the following query,

var query = Model.find();

the following queries

query.exists('occupation');
query.exists('occupation', true);
query.where('occupation').exists();

all result in

{ occupation: { $exists: true }}

Another example:

query.exists('occupation', false)
query.where('occupation').exists(false);

result in

{ occupation: { $exists: false }}

Query#elemMatch, Query#$elemMatch

Specifies the $elemMatch operator.

query.elemMatch(path, criteria)
query.where(path).elemMatch(criteria)

Functions can also be passed so you can further use query sugar to declare the expression:

query.where(path).elemMatch(function)
query.elemMatch(path, function)

In this case a query is passed as the only argument into the function.

query.where('comments').elemMatch(function (elem) {
  elem.where('author', 'bnoguchi')
  elem.where('votes').gte(5);
});

Results in

{ comments: { $elemMatch: { author: 'bnoguchi', votes: { $gte: 5 }}}}

Query#within, Query#$within

Query#box, Query#$box

Query#center, Query#$center

Query#centerSphere, Query#$centerSphere

Query#near, Query#$near

Specifies the $near operator.

var array = [10, 1]
query.near(path, array)

query.near(path, 10, 1)

query.where(path).$near(10, 1)

all result in

{ path: { $near: [10, 1] }}

Query#maxDistance, Query#$maxDistance

Specifies the $maxDistance operator.

query.where('checkin').near([40, -72]).maxDistance(1);

results in

{ checkin: { $near: [40, -72], $maxDistance: 1 }}

Query#select

Query#fields

Query#only

Query#exclude

Query#slice

Query#$slice

Query#populate

// sorting

Query#sort

Query#asc

Query#desc

// options

Query#limit

Query#skip

Query#maxscan

Query#snapshot

Query#batchSize

Query#slaveOk

Query#hint

// executing

Query#find

query.find(criteria [, callback])

Query#findOne

Query#count

Query#distinct

Query#update

Query#remove

Query#run

Query#exec

query.run([callback])

Query#each

Query#stream

Returns a QueryStream for the query.

Model.find({}).stream().pipe(writeStream)
Jump to Line
Something went wrong with that request. Please try again.