// find all users with age > 29 AND <= 35 and of the feminine sex
db.users.find({age: {$gt: 29, $lte: 35}, sex: {$eq: 'f'}}) (function(err, key, value) {
  if (err) { next(err); return; }
  console.log('(1) got ' + key); // I get called once for every matched record
})
.reset() // reset query
.where({age: {$gt: 29, $lt: 42}}) // find all users with age > 29 and < 42
  (function(err, key, value) {
    if (err) { next(err); return; }
    console.log('(2) got ' + key); // I get called once for every matched record
  })
.reset() // reset query
.where({age: {$gt: 29, $lt: 35}})
.or({sex: {$eq: 'f'}})  // find all users with age > 29 and <= 35 OR of the feminine sex
(function(err, key, value) {
  if (err) { next(err); return; }
  console.log('(3) got ' + key);
})
.bulk(function(err, records) {
  if (err) { next(err); return; }
  console.log('Found ' + records.length + ' matching records');
  records.forEach(function(record) {
    console.log('(4) got ' + record.key);
    // can also access record.value
  });
});

Chainable elements

All chainable elements can be chained to each other, building a query and retrieving the results.

find (spec)

Prepares query, gathering records according to spec. Starts chain.

• spec: specification of which indexes and operators to run.

  Takes an object. Each key of the object is the name of an index, and each value is an operators spec.

  See all available operators.

Example:

users is a key map with indexes age and sex.

To find all users with age > 29 and <= 35 and of sex == 'f' do:

var chainable = db.users.find({age : {$gt: 29, $lte: 35}, sex: {$eq: 'f'}})

This returns a chainable object which you can activate by invoking it like this:

chainable(function(err, key, value) {
  console.log('got ' + key);
});

Or, all together:

var chainable = db.users.find({age : {$gt: 29, $lte: 35}, sex: {$eq: 'f'}})
   (function(err, key, value) {
      console.log('got ' + key);
   });

.order (index_spec)

Values returned will be ordered accorgin to index_spec.

• index_spec: format: "<index>" or "<index> ASC" or "<index> DESC". The index may be in the query or not. It must exist on the key_map, though.

Example:

db.users.find({age : {$gt: 29, $lte: 35}, sex: {$eq: 'f'}}).order('age DESC')

.reset ()

Resets the query. Finder is invalid after this.

.where (spec)

Overrides the query to spec.

• spec: must follow the same spec as find(spec).

.or (spec)

Adds an alternative condition to the already existing one.

• spec: must follow the same spec as find(spec).

.limit (limit)

Sets a limit on the returned number of objects

• limit: integer > 0

.first ()

The same as .limit(1).

.offset (x)

Ignore the first x objects

• x: integer >= 0

.all (callback)

Get all the objects at once, on one callback.

• callback (err, records): called when there is an error or when all records are retrieved.

  records is an Array of objects with key and value attributes.

.stream ([callback])

Starts a results stream.

• callback (stream): optional. Pass this in if you want the callback-style to keep chaining.

returns a stream if no callback is given.

Example:

var stream = db.users.find({age : {$gt: 29, $lte: 35}, sex: {$eq: 'f'}}).stream();
stream.on('record', function(record) {
  console.log(record);
});
stream.on('error', function(err) {
  throw(err);
});
stream.on('end', function() {
  console.log('ended');
});