Finding documents

Use find to look for multiple documents matching you query, or findOne to look for one specific document. You can select documents based on field equality or use comparison operators ($lt, $lte, $gt, $gte, $in, $nin, $ne). You can also use logical operators $or, $and, $not and $where. See below for the syntax.

You can use regular expressions in two ways: in basic querying in place of a string, or with the $regex operator.

You can sort and paginate results using the cursor API (see below).

You can use standard projections to restrict the fields to appear in the results (see below).

Basic querying

Basic querying means are looking for documents whose fields match the ones you specify. You can use regular expression to match strings.You can use the dot notation to navigate inside nested documents, arrays, arrays of subdocuments and to match a specific element of an array.

  1. // Let's say our datastore contains the following collection
  2. // { _id: 'id1', planet: 'Mars', system: 'solar', inhabited: false, satellites: ['Phobos', 'Deimos'] }
  3. // { _id: 'id2', planet: 'Earth', system: 'solar', inhabited: true, humans: { genders: 2, eyes: true } }
  4. // { _id: 'id3', planet: 'Jupiter', system: 'solar', inhabited: false }
  5. // { _id: 'id4', planet: 'Omicron Persei 8', system: 'futurama', inhabited: true, humans: { genders: 7 } }
  6. // { _id: 'id5', completeData: { planets: [ { name: 'Earth', number: 3 }, { name: 'Mars', number: 2 }, { name: 'Pluton', number: 9 } ] } }
  8. // Finding all planets in the solar system
  9. db.find({ system: 'solar' }, function (err, docs) {
  10.   // docs is an array containing documents Mars, Earth, Jupiter
  11.   // If no document is found, docs is equal to []
  12. });
  14. // Finding all planets whose name contain the substring 'ar' using a regular expression
  15. db.find({ planet: /ar/ }, function (err, docs) {
  16.   // docs contains Mars and Earth
  17. });
  19. // Finding all inhabited planets in the solar system
  20. db.find({ system: 'solar', inhabited: true }, function (err, docs) {
  21.   // docs is an array containing document Earth only
  22. });
  24. // Use the dot-notation to match fields in subdocuments
  25. db.find({ "humans.genders": 2 }, function (err, docs) {
  26.   // docs contains Earth
  27. });
  29. // Use the dot-notation to navigate arrays of subdocuments
  30. db.find({ "completeData.planets.name": "Mars" }, function (err, docs) {
  31.   // docs contains document 5
  32. });
  34. db.find({ "completeData.planets.name": "Jupiter" }, function (err, docs) {
  35.   // docs is empty
  36. });
  38. db.find({ "completeData.planets.0.name": "Earth" }, function (err, docs) {
  39.   // docs contains document 5
  40.   // If we had tested against "Mars" docs would be empty because we are matching against a specific array element
  41. });
  44. // You can also deep-compare objects. Don't confuse this with dot-notation!
  45. db.find({ humans: { genders: 2 } }, function (err, docs) {
  46.   // docs is empty, because { genders: 2 } is not equal to { genders: 2, eyes: true }
  47. });
  49. // Find all documents in the collection
  50. db.find({}, function (err, docs) {
  51. });
  53. // The same rules apply when you want to only find one document
  54. db.findOne({ _id: 'id1' }, function (err, doc) {
  55.   // doc is the document Mars
  56.   // If no document is found, doc is null
  57. });

Operators ($lt, $lte, $gt, $gte, $in, $nin, $ne, $exists, $regex)

The syntax is { field: { $op: value } } where $op is any comparison operator:

  • $lt, $lte: less than, less than or equal
  • $gt, $gte: greater than, greater than or equal
  • $in: member of. value must be an array of values
  • $ne, $nin: not equal, not a member of
  • $exists: checks whether the document posses the property field. value should be true or false
  • $regex: checks whether a string is matched by the regular expression. Contrary to MongoDB, the use of $options with $regex is not supported, because it doesn't give you more power than regex flags. Basic queries are more readable so only use the $regex operator when you need to use another operator with it (see example below)
  1. // $lt, $lte, $gt and $gte work on numbers and strings
  2. db.find({ "humans.genders": { $gt: 5 } }, function (err, docs) {
  3.   // docs contains Omicron Persei 8, whose humans have more than 5 genders (7).
  4. });
  6. // When used with strings, lexicographical order is used
  7. db.find({ planet: { $gt: 'Mercury' }}, function (err, docs) {
  8.   // docs contains Omicron Persei 8
  9. })
  11. // Using $in. $nin is used in the same way
  12. db.find({ planet: { $in: ['Earth', 'Jupiter'] }}, function (err, docs) {
  13.   // docs contains Earth and Jupiter
  14. });
  16. // Using $exists
  17. db.find({ satellites: { $exists: true } }, function (err, docs) {
  18.   // docs contains only Mars
  19. });
  21. // Using $regex with another operator
  22. db.find({ planet: { $regex: /ar/, $nin: ['Jupiter', 'Earth'] } }, function (err, docs) {
  23.   // docs only contains Mars because Earth was excluded from the match by $nin
  24. });

Array fields

When a field in a document is an array, NeDB first tries to see if the query value is an array to perform an exact match, then whether there is an array-specific comparison function (for now there is only $size and $elemMatch) being used. If not, the query is treated as a query on every element and there is a match if at least one element matches.

  • $size: match on the size of the array
  • $elemMatch: matches if at least one array element matches the query entirely
  1. // Exact match
  2. db.find({ satellites: ['Phobos', 'Deimos'] }, function (err, docs) {
  3.   // docs contains Mars
  4. })
  5. db.find({ satellites: ['Deimos', 'Phobos'] }, function (err, docs) {
  6.   // docs is empty
  7. })
  9. // Using an array-specific comparison function
  10. // $elemMatch operator will provide match for a document, if an element from the array field satisfies all the conditions specified with the `$elemMatch` operator
  11. db.find({ completeData: { planets: { $elemMatch: { name: 'Earth', number: 3 } } } }, function (err, docs) {
  12.   // docs contains documents with id 5 (completeData)
  13. });
  15. db.find({ completeData: { planets: { $elemMatch: { name: 'Earth', number: 5 } } } }, function (err, docs) {
  16.   // docs is empty
  17. });
  19. // You can use inside #elemMatch query any known document query operator
  20. db.find({ completeData: { planets: { $elemMatch: { name: 'Earth', number: { $gt: 2 } } } } }, function (err, docs) {
  21.   // docs contains documents with id 5 (completeData)
  22. });
  24. // Note: you can't use nested comparison functions, e.g. { $size: { $lt: 5 } } will throw an error
  25. db.find({ satellites: { $size: 2 } }, function (err, docs) {
  26.   // docs contains Mars
  27. });
  29. db.find({ satellites: { $size: 1 } }, function (err, docs) {
  30.   // docs is empty
  31. });
  33. // If a document's field is an array, matching it means matching any element of the array
  34. db.find({ satellites: 'Phobos' }, function (err, docs) {
  35.   // docs contains Mars. Result would have been the same if query had been { satellites: 'Deimos' }
  36. });
  38. // This also works for queries that use comparison operators
  39. db.find({ satellites: { $lt: 'Amos' } }, function (err, docs) {
  40.   // docs is empty since Phobos and Deimos are after Amos in lexicographical order
  41. });
  43. // This also works with the $in and $nin operator
  44. db.find({ satellites: { $in: ['Moon', 'Deimos'] } }, function (err, docs) {
  45.   // docs contains Mars (the Earth document is not complete!)
  46. });

Logical operators $or, $and, $not, $where

You can combine queries using logical operators:

  • For $or and $and, the syntax is { $op: [query1, query2, …] }.
  • For $not, the syntax is { $not: query }
  • For $where, the syntax is { $where: function () { / object is "this", return a boolean / } }
  1. db.find({ $or: [{ planet: 'Earth' }, { planet: 'Mars' }] }, function (err, docs) {
  2.   // docs contains Earth and Mars
  3. });
  5. db.find({ $not: { planet: 'Earth' } }, function (err, docs) {
  6.   // docs contains Mars, Jupiter, Omicron Persei 8
  7. });
  9. db.find({ $where: function () { return Object.keys(this) > 6; } }, function (err, docs) {
  10.   // docs with more than 6 properties
  11. });
  13. // You can mix normal queries, comparison queries and logical operators
  14. db.find({ $or: [{ planet: 'Earth' }, { planet: 'Mars' }], inhabited: true }, function (err, docs) {
  15.   // docs contains Earth
  16. });

Sorting and paginating

If you don't specify a callback to find, findOne or count, a Cursor object is returned. You can modify the cursor with sort, skip and limit and then execute it with exec(callback).

  1. // Let's say the database contains these 4 documents
  2. // doc1 = { _id: 'id1', planet: 'Mars', system: 'solar', inhabited: false, satellites: ['Phobos', 'Deimos'] }
  3. // doc2 = { _id: 'id2', planet: 'Earth', system: 'solar', inhabited: true, humans: { genders: 2, eyes: true } }
  4. // doc3 = { _id: 'id3', planet: 'Jupiter', system: 'solar', inhabited: false }
  5. // doc4 = { _id: 'id4', planet: 'Omicron Persei 8', system: 'futurama', inhabited: true, humans: { genders: 7 } }
  7. // No query used means all results are returned (before the Cursor modifiers)
  8. db.find({}).sort({ planet: 1 }).skip(1).limit(2).exec(function (err, docs) {
  9.   // docs is [doc3, doc1]
  10. });
  12. // You can sort in reverse order like this
  13. db.find({ system: 'solar' }).sort({ planet: -1 }).exec(function (err, docs) {
  14.   // docs is [doc1, doc3, doc2]
  15. });
  17. // You can sort on one field, then another, and so on like this:
  18. db.find({}).sort({ firstField: 1, secondField: -1 }) ...   // You understand how this works!

Projections

You can give find and findOne an optional second argument, projections. The syntax is the same as MongoDB: { a: 1, b: 1 } to return only the a and b fields, { a: 0, b: 0 } to omit these two fields. You cannot use both modes at the time, except for _id which is by default always returned and which you can choose to omit. You can project on nested documents.

  1. // Same database as above
  3. // Keeping only the given fields
  4. db.find({ planet: 'Mars' }, { planet: 1, system: 1 }, function (err, docs) {
  5.   // docs is [{ planet: 'Mars', system: 'solar', _id: 'id1' }]
  6. });
  8. // Keeping only the given fields but removing _id
  9. db.find({ planet: 'Mars' }, { planet: 1, system: 1, _id: 0 }, function (err, docs) {
  10.   // docs is [{ planet: 'Mars', system: 'solar' }]
  11. });
  13. // Omitting only the given fields and removing _id
  14. db.find({ planet: 'Mars' }, { planet: 0, system: 0, _id: 0 }, function (err, docs) {
  15.   // docs is [{ inhabited: false, satellites: ['Phobos', 'Deimos'] }]
  16. });
  18. // Failure: using both modes at the same time
  19. db.find({ planet: 'Mars' }, { planet: 0, system: 1 }, function (err, docs) {
  20.   // err is the error message, docs is undefined
  21. });
  23. // You can also use it in a Cursor way but this syntax is not compatible with MongoDB
  24. db.find({ planet: 'Mars' }).projection({ planet: 1, system: 1 }).exec(function (err, docs) {
  25.   // docs is [{ planet: 'Mars', system: 'solar', _id: 'id1' }]
  26. });
  28. // Project on a nested document
  29. db.findOne({ planet: 'Earth' }).projection({ planet: 1, 'humans.genders': 1 }).exec(function (err, doc) {
  30.   // doc is { planet: 'Earth', _id: 'id2', humans: { genders: 2 } }
  31. });