Skip to content

gflandre/mongo-aggregation-debugger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Mongo Aggregation Debugger

NPM

Mongo Aggregation Debugger helps debug MongoDb aggregation queries by being able to visualize each stage of the pipeline

Why use it

It is pretty hard to understand why a specific aggregation query fails or doesn't output the right results since it can be pretty complex and go through a lot of stages before returning values.

The Mongo Aggregation Debugger helps you understand what is going on by either:

  • outputting in the console the results of each stage of the aggregation pipeline
  • returning an array of results of each stage of teh aggregation pipeline for programmatic use
  • running the query in a temporary database and outputting the results, very useful for automated testing

How it works

You give the debugger access to your instance of mongodb, and it creates a temporary collection in which it will run each stage of the aggregation query in series. The temporary database is dropped after each debug.

Install

npm install mongo-aggregation-debugger

Instantiation

var mad = require('mongo-aggregation-debugger')();

You can provide an optional object as an argument to specify the mongodb connection information:

key default value description
host localhost mongodb host name
port 27017 mongodb port number
username null (optional) username of the mongodb instance
password null (optional) password of the mongodb instance
options {} (optional) additional mongodb options

API

log

This method outputs in the console the result of each stage of the aggregation pipeline.

Use

log(data, query[, options][, callback])

argument type values description
data array The data to run the query against
query array The aggregation query
options object showQuery: boolean Whether to show the query of the stage being run or not
callback function(err) The callback returned when all stages were executed

Example:

var mad = require('mongo-aggregation-debugger')();

var data = [{
  foo: 'bar',
  test: true,
  array: [ 1, 2, 3 ]
}, {
  foo: 'bar2',
  test: false,
  array: [ 10, 20 ]
}];

var query = [{
  '$match': {
    test: true
  }
}, {
  '$project': {
    foo: 1,
    array: 1
  }
}, {
  '$unwind': "$array"
}, {
  '$group': {
    _id: "$foo",
    foo: { $first: "$foo" },
    sum: { $sum: "$array" }
  }
}];

mad.log(data, query, function (err) {
  if (err) {
    // do something
  }

  console.log('All done!');
});

Running the code above would output this in your console: capture d ecran 2015-07-05 a 14 24 46

Example with the showQuery option:

mad.log(data, query, { showQuery: true }, function (err) {
  if (err) {
    // do something
  }

  console.log('All done!');
});

capture d ecran 2015-07-05 a 14 28 37

stages

This method returns the result of each stage of the aggregation pipeline for programmatic use.

Use

stages(data, query[, callback])

argument | type | description ------------ | ------------- | ------------- | ------------- data | array | The data to run the query against query | array | The aggregation query callback | function(err, results) | results is an array composed of as many objects as there are stages in the aggregation pipeline. Each object has a query attribute which is the query of the stage and a result attribute with the results of that query

Example:

var util = require('util');
var mad = require('mongo-aggregation-debugger')();

var data = [{
  foo: 'bar',
  test: true,
  array: [ 1, 2, 3 ]
}, {
  foo: 'bar2',
  test: false,
  array: [ 10, 20 ]
}];

var query = [{
  '$match': {
    test: true
  }
}, {
  '$project': {
    foo: 1,
    array: 1
  }
}, {
  '$unwind': "$array"
}, {
  '$group': {
    _id: "$foo",
    foo: { $first: "$foo" },
    sum: { $sum: "$array" }
  }
}];

mad.stages(data, query, function (err, results) {
  if (err) {
    // do something
  }

  console.log(util.inspect(results, { depth: null }));
});

The output is:

[ { query: [ { '$match': { test: true } } ],
    results:
     [ { _id: 5599279a731b5aba47df6d97,
         foo: 'bar',
         test: true,
         array: [ 1, 2, 3 ] } ] },
  { query:
     [ { '$match': { test: true } },
       { '$project': { foo: 1, array: 1 } } ],
    results: [ { _id: 5599279a731b5aba47df6d97, foo: 'bar', array: [ 1, 2, 3 ] } ] },
  { query:
     [ { '$match': { test: true } },
       { '$project': { foo: 1, array: 1 } },
       { '$unwind': '$array' } ],
    results:
     [ { _id: 5599279a731b5aba47df6d97, foo: 'bar', array: 1 },
       { _id: 5599279a731b5aba47df6d97, foo: 'bar', array: 2 },
       { _id: 5599279a731b5aba47df6d97, foo: 'bar', array: 3 } ] },
  { query:
     [ { '$match': { test: true } },
       { '$project': { foo: 1, array: 1 } },
       { '$unwind': '$array' },
       { '$group':
          { _id: '$foo',
            foo: { '$first': '$foo' },
            sum: { '$sum': '$array' } } } ],
    results: [ { _id: 'bar', foo: 'bar', sum: 6 } ] } ]

exec

This method only runs the entire query passed, not all the stages seperately. It is useful for automated tests since it creates and drops a temporary database.

Use

exec(data, query[, callback])

argument | type | description ------------ | ------------- | ------------- | ------------- data | array | The data to run the query against query | array | The aggregation query callback | function(err, results) | results is the results of the query being run

Example:

var util = require('util');
var mad = require('mongo-aggregation-debugger')();

var data = [{
  foo: 'bar',
  test: true,
  array: [ 1, 2, 3 ]
}, {
  foo: 'bar2',
  test: false,
  array: [ 10, 20 ]
}];

var query = [{
  '$match': {
    test: true
  }
}, {
  '$project': {
    foo: 1,
    array: 1
  }
}, {
  '$unwind': "$array"
}, {
  '$group': {
    _id: "$foo",
    foo: { $first: "$foo" },
    sum: { $sum: "$array" }
  }
}];

mad.exec(data, query, function (err, results) {
  if (err) {
    // do something
  }

  console.log(util.inspect(results, { depth: null }));
});

The output is:

[ { _id: 'bar', foo: 'bar', sum: 6 } ]

Unit tests

In order to test this lib you'll need to install mocha: npm install -g mocha. Then just run the mocha command at the root of the project.

More info

Contribute

If you think it would make sense to add some features/methods don't hesitate to fork and make pull requests.

You can contact the main contributor on Twitter

Licence

Distributed under the MIT License.

About

Debug MongoDb's aggregation framework and visualize what each stage of the pipeline outputs

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published