|
Introduction
MongoDB offers a rich query environment with lots of features. This page lists some of those features.
Queries in MongoDB are represented as JSON-style objects, very much like the documents we actually store in the database. For example:
// i.e., select * from things where x=3 and y="foo"
db.things.find( { x : 3, y : "foo" } );
Note that any of the operators on this page can be combined in the same query document. For example, to find all document where j is not equal to 3 and k is greater than 10, you'd query like so:
db.things.find({j: {$ne: 3}, k: {$gt: 10} });
Unless otherwise noted, the operations below can be used on array elements in the same way that they can be used on "normal" fields. For example, suppose we have some documents such as:
> db.things.insert({colors : ["blue", "black"]})
> db.things.insert({colors : ["yellow", "orange", "red"]})
Then we can find documents that aren't "red" using:
> db.things.find({colors : {$ne : "red"}}) {"_id": ObjectId("4dc9acea045bbf04348f9691"), "colors": ["blue","black"]}
Retrieving a Subset of Fields
See Retrieving a Subset of Fields
Conditional Operators
=
Use these special forms for greater than and less than comparisons in queries, since they have to be represented in the query document:
db.collection.find({ "field" : { $gt: value } } ); // greater than : field > value
db.collection.find({ "field" : { $lt: value } } ); // less than : field < value
db.collection.find({ "field" : { $gte: value } } ); // greater than or equal to : field >= value
db.collection.find({ "field" : { $lte: value } } ); // less than or equal to : field t.find( { x : { $elemMatch : { a : 1, b : { $gt : 1 } } } } ) { "_id" : ObjectId("4b5783300334000000000aa9"), "x" : [ { "a" : 1, "b" : 3 }, 7, { "b" : 99 }, { "a" : 11 } ] }
Note that a single array element must match all the criteria specified; thus, the following query is semantically different in that each criteria can match a different element in the x array:
> t.find( { "x.a" : 1, "x.b" : { $gt : 1 } } )
See the dot notation page for more.
You only need to use this when more than 1 field must be matched in the array element.
Value in an Embedded Object
For example, to look author.name=="joe" in a postings collection with embedded author objects:
db.postings.find( { "author.name" : "joe" } );
See the dot notation page for more.
Meta operator: $not
Version 1.3.3 and higher.
The $not meta operator can be used to negate the check performed by a standard operator. For example:
db.customers.find( { name : { $not : /acme.*corp/i } } );
db.things.find( { a : { $not : { $mod : [ 10 , 1 ] } } } );
The $not meta operator can only affect other operators. The following does not work. For such a syntax use the $ne operator.
db.things.find( { a : { $not : true } } ); // syntax error
$not is not supported for regular expressions specified using the {$regex: ...} syntax. When using $not, all regular expressions should be passed using the native BSON type (e.g. {"$not": re.compile("acme.*corp")} in PyMongo)
Javascript Expressions and $where
In addition to the structured query syntax shown so far, you may specify query expressions as Javascript. To do so, pass a string containing a Javascript expression to find(), or assign such a string to the query object member $where. The database will evaluate this expression for each object scanned. When the result is true, the object is returned in the query results.
For example, the following mongo shell statements all do the same thing:
> db.myCollection.find( { a : { $gt: 3 } } );
> db.myCollection.find( { $where: "this.a > 3" } );
> db.myCollection.find("this.a > 3");
> f = function() { return this.a > 3; } db.myCollection.find(f);
You may mix mongo query expressions and a $where clause. In that case you must use the $where syntax, e.g.:
> db.myCollection.find({registered:true, $where:"this.a>3"})
Javascript executes more slowly than the native operators listed on this page, but is very flexible. See the server-side processing page for more information.
Cursor Methods
count()
The count() method returns the number of objects matching the query specified. It is specially optimized to perform the count in the MongoDB server, rather than on the client side for speed and efficiency:
nstudents = db.students.find({'address.state' : 'CA'}).count();
Note that you can achieve the same result with the following, but the following is slow and inefficient as it requires all documents to be put into memory on the client, and then counted. Don't do this:
nstudents = db.students.find({'address.state' : 'CA'}).toArray().length; // VERY BAD: slow and uses excess memory
On a query using skip() and limit(), count ignores these parameters by default. Use count(true) to have it consider the skip and limit values in the calculation.
n = db.students.find().skip(20).limit(10).count(true);
limit()
limit() is analogous to the LIMIT statement in MySQL: it specifies a maximum number of results to return. For best performance, use limit() whenever possible. Otherwise, the database may return more objects than are required for processing.
db.students.find().limit(10).forEach( function(student) { print(student.name + ""); } );
In the shell (and most drivers), a limit of 0 is equivalent to setting no limit at all.
skip()
The skip() expression allows one to specify at which object the database should begin returning results. This is often useful for implementing "paging". Here's an example of how it might be used in a JavaScript application:
function printStudents(pageNumber, nPerPage) {
print("Page: " + pageNumber);
db.students.find().skip((pageNumber-1)*nPerPage).limit(nPerPage).forEach( function(student) { print(student.name + ""); } );
}
Paging Costs
Unfortunately skip can be (very) costly and requires the server to walk from the beginning of the collection, or index, to get to the offset/skip position before it can start returning the page of data (limit). As the page number increases skip will become slower and more cpu intensive, and possibly IO bound, with larger collections. Range based paging provides better use of indexes but does not allow you to easily jump to a specific page.
snapshot()
Indicates use of snapshot mode for the query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (even if the object were updated). If an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode.
Note that short query responses (less than 1MB) are always effectively snapshotted.
Currently, snapshot mode may not be used with sorting or explicit hints.
sort()
sort() is analogous to the ORDER BY statement in SQL - it requests that items be returned in a particular order. We pass sort() a key pattern which indicates the desired order for the result.
db.myCollection.find().sort( { ts : -1 } ); // sort by ts, descending order
sort() may be combined with the limit() function. In fact, if you do not have a relevant index for the specified key pattern, limit() is recommended as there is a limit on the size of sorted results when an index is not used. Without a limit(), or index, a full in-memory sort must be done but by using a limit() it reduces the memory and increases the speed of the operation by using an optimized sorting algorithm.
Special operators
Only return the index key:
db.foo.find()._addSpecial("$returnKey" , true )
Limit the number of items to scan:
db.foo.find()._addSpecial( "$maxScan" , 50 )
Set the query:
db.foo.find()._addSpecial( "$query" : {x : {$lt : 5}} ) // same as db.foo.find({x : {$lt : 5}})
Sort results:
db.foo.find()._addSpecial( "$orderby", {x : -1} ) // same as
db.foo.find().sort({x:-1})
Explain the query instead of actually returning the results:
db.foo.find()._addSpecial( "$explain", true ) // same as db.foo.find().explain()
Snapshot query:
db.foo.find()._addSpecial( "$snapshot", true ) // same as db.foo.find().snapshot()
Set index bounds (see min and max Query Specifiers for details):
db.foo.find()._addSpecial("$min" , {x: -20})._addSpecial("$max" , { x : 200 })
Show disk location of results:
db.foo.find()._addSpecial("$showDiskLoc" , true)
Force query to use the given index:
db.foo.find()._addSpecial("$hint", {_id : 1})
group()
The group() method is analogous to GROUP BY in SQL. group() is more flexible, actually, allowing the specification of arbitrary reduction operations. See the Aggregation section of the Mongo Developers' Guide for more information.
See Also
Indexes
Optimizing Queries (including explain() and hint()) |
|