See also:
Collections can be queried with find.
collection.find(query[[[, fields], options], callback]);
Where
The result for the query is actually a cursor object. This can be used directly or converted to an array.
var cursor = collection.find({});
cursor.each(...);
To indicate which fields must or must no be returned fields value can be used. For example the following fields value
{
"name": true,
"title": true
}
retrieves fields name and title (and as a default also _id) but not any others.
findOne is a convinence method finding and returning the first match of a query while regular find returns a cursor object instead. Use it when you expect only one record, for example when querying with _id or another unique property.
collection.findOne(query, [fields, [options]], callback);
Where
Example:
collection.findOne({_id: doc_id}, function(err, document) {
console.log(document.name);
});
Default _id values are 12 byte binary hashes. You can alter the format with custom Primary Key factories (see Custom Primarky Keys in Database).
In order to treat these binary _id values as strings it would be wise to convert binary values to hex strings. This can be done with toHexString property.
var idHex = document._id.toHexString();
Hex strings can be reverted back to binary (for example to perform queries) with ObjectID.createFromHexString
{_id: ObjectID.createFromHexString(idHex)}
When inserting new records it is possible to use custom _id values as well which do not need to be binary hashes, for example strings.
collection.insert({_id: "abc", ...});
collection.findOne({_id: "abc"},...);
This way it is not necessary to convert _id values to hex strings and back.
The simplest query object is an empty one {} which matches every record in the database.
To make a simple query where one field must match to a defined value, one can do it as simply as
{fieldname: "fieldvalue"}
This query matches all the records that a) have fields called fieldname and b) its value is “fieldvalue”.
For example if we have a collection of blog posts where the structure of the records is {title, author, contents} and we want to retrieve all the posts for a specific author then we can do it like this:
posts = pointer_to_collection;
posts.find({author:"Daniel"}).toArray(function(err, results){
console.log(results); // output all records
});
If the queried field is inside an object then that can be queried also. For example if we have a record with the following structure:
{
user: {
name: "Daniel"
}
}
Then we can query the “name” field like this: {"user.name":"Daniel"}
If more than one fieldname is specified, then it’s an AND query
{
key1: "value1",
name2: "value2"
}
Whis query matches all records where key1 is “value1” and key2 is “value2”
OR queries are a bit trickier but doable with the $or operator. Query operator takes an array which includes a set of query objects and at least one of these must match a document before it is retrieved
{
$or:[
{author:"Daniel"},
{author:"Jessica"}
]
}
This query match all the documents where author is Daniel or Jessica.
To mix AND and OR queries, you just need to use $or as one of regular query fields.
{
title:"MongoDB",
$or:[
{author:"Daniel"},
{author:"Jessica"}
]
}
Conditional operators <, <=, >, >= and != can’t be used directly, as the query object format doesn’t support it but the same can be achieved with their aliases $lt, $lte, $gt, $gte and $ne. When a field value needs to match a conditional, the value must be wrapped into a separate object.
{"fieldname":{$gte:100}}
This query defines that fieldname must be greater than or equal to 100.
Conditionals can also be mixed to create ranges.
{"fieldname": {$lte:10, $gte:100}}
Queried field values can also be matched with regular expressions
{author:/^Daniel/}
In addition to OR and conditional there’s some more operators:
If you have a document with nested objects/arrays then the keys inside these nested objects can still be used for queries.
For example with the following document
{
"_id": idvalue,
"author":{
"firstname":"Daniel",
"lastname": "Defoe"
},
"books":[
{
"title":"Robinson Crusoe"
"year": 1714
}
]
}
not only the _id field can be used as a query field - also the firstname and even title can be used. This can be done when using nested field names as strings, concated with periods.
collection.find({"author.firstname":"Daniel})
Works even inside arrays
collection.find({"books.year":1714})
Query options define the behavior of the query.
var options = {
"limit": 20,
"skip": 10,
"sort": "title"
}
collection.find({}, options).toArray(...);
Paging can be achieved with option parameters limit and skip
{
"limit": 20,
"skip": 10
}
retrieves 10 elements starting from 20
Sorting can be acieved with option parameter sort which takes an array of sort preferences
{
"sort": [['field1','asc'], ['field2','desc']]
}
With single ascending field the array can be replaced with the name of the field.
{
"sort": "name"
}
Option parameter explain turns the query into an explain query.
Cursor objects are the results for queries and can be used to fetch individual fields from the database.
cursor.nextObject(function(err, doc){}) retrieves the next record from database. If doc is null, then there weren’t any more records.
cursor.each(function(err, doc){}) retrieves all matching records one by one.
cursor.toArray(function(err, docs){}) converts the cursor object into an array of all the matching records. Probably the most convenient way to retrieve results but be careful with large datasets as every record is loaded into memory.
collection.find().toArray(function(err, docs){
console.log("retrieved records:");
console.log(docs);
});
cursor.rewind() resets the internal pointer in the cursor to the beginning ## Counting matches
Counting total number of found matches can be done against cursors with method count.
cursor.count(callback)
Where
Example
cursor.count(function(err, count){
console.log("Total matches: "+count);
});