mongo query API component
Pull request Compare This branch is 27 commits behind Automattic:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Component that implements the complete MongoDB query JSON API to operate on individual documents.


var query = require('mongo-query');

// our sample document
var obj = {
  name: 'Tobi',
  age: 8,
  location: { country: 'Canada', zip: 123 }
  likes: [{ id: 1, name: 'Food' }, { id: 2, name: 'Stuff' }]

// run an operation and get changes
var changes = query(obj, { $set: { '': 'US' } });


  • Transactional. If an op fails, the others are rolled back.
  • Precise modification logs. Ops return an array of change objects.
    • Noops are excluded.
    • Before/after values are provided.
    • Whether the op triggered the creation of a new array.
  • Error messages almost exactly match MongoDB's.
  • Query support. Allows for support of the positional operator.
  • Wide test coverage.


query(obj, filter, modifier, opts)

  • Executes the modifier on obj provided they match filter.
  • Returns an array of change objects (see below). If the modifier does not alter the object the array will be empty.
  • Options:
    • strict if true, only modifies if filter has a match (false).


Returns a Query object to perform tests on.

Example: query.filter({ a: { $gt: 3 } }).test({ a: 1 }). For the complete filter API refer to filtr.

query.get(obj, key)

Gets the key from the given obj, which can use dot notation.

Example: query.get(obj, 'some.key').

query.set(obj, key, val)

Sets the key on obj with the given val. Key can use dot notation.


All change objects contain:

  • key: the key that was affected. If the positional operator was used, the key is rewritten with dot notation (eg:
  • op: the type of operation that was performed

Depending on the type of operation they can contain extra fields.


  • value that we set


  • value value that we increment by


  • value value that was popped
  • shift if true, it was a shift instead of a pop


  • value new name


  • value value that was pushed


  • value array of values that were pushed


  • value array of values that were pulled


  • value array of values that were pulled


  • value (undefined)


  • value array of values that were added