0.7.4 • Public • Published


    Build Status JavaScript Style Guide License badge release npm version Stars badge

    This library is usefull example with expressjs + mongoose applications to help construct mongoose query model directly from url parameters. Example:


    Converted to:

    model.find({group: "users"}).select("name").skip(1).limit(5).populate('name')

    Tested with node.js versions

    12.x, 14.x, 16.x,latest release

    Changes log

    See releases page.


    Use npm:

    npm install mongoose-query


    npm test && npm run lint

    Usage Example

    var QueryPlugin = require(mongoose-query);
    var TestSchema = new mongoose.Schema({});
    var testmodel = mongoose.model('test', TestSchema);
    //express route
    module.exports = function query(req, res) {
      testmodel.query(req.query, function(error, data){
        res.json(error?{error: error}:data);


    var QueryPlugin = require(mongoose-query);
    schema.plugin( QueryPlugin(, <options>) )

    optional options:

    • logger: custom logger, e.g. winston logger, default: "dummy logger"
    • includeAllParams: Parse also other values. e.g. ?name=me. default: true
    • ignoreKeys : <array{String}> keys to be ignored. Default: []

    Model static methods:

    model.query( <query>(, <callback>) )

    model.leanQuery(<query>(, <callback>) ): gives plain objects (lean)

    Note: without <callback> you get Promise.

    URL API:[q=<query>][&t=<type>][&f=<fields>][&s=<order>][&sk=<skip>]
    q=<query>                   restrict results by the specified JSON query
                                regex e.g. q='{"field":{"$regex":"/mygrep/", "$options":"i"}}'
    t=<type>                    find|findOne|count|aggregate|distinct|aggregate|mapReduce
    f=<set of fields>           specify the set of fields to include or exclude in each document
                                (1 - include; 0 - exclude)
    s=<sort order>              specify the order in which to sort each specified field
                                (1- ascending; -1 - descending), JSON
    sk=<num results to skip>    specify the number of results to skip in the result set;
                                useful for paging
    l=<limit>                   specify the limit for the number of results (default is 1000)
    p=<populate>                specify the fields for populate, also more complex json object is supported.
    x=<explain>                 allowed values: 'queryPlanner', 'executionStats', 'allPlansExecution'
    to=<ms>                     timeout for query
    d=<boolean>                 allowDiskUse (for heavy queries)
    map=<mapFunction>           mongodb map function as string
                                e.g. "function(){if (this.status == 'A') emit(this.cust_id, 1);)}"
    reduce=<reduceFunction>     mongodb reduce function as string
                                e.g. "function(key, values) {return result;}"
    fl=<boolean>                Flat results or not
    Special values:
    "oid:<string>"              string is converted to ObjectId
    "/regex/(options)"          converted to regex
    { $regex: /<string>/,       regex match with optional regex options
     ($options: "") }        
    Alternative search conditions:
    "key={i}a"                  case insensitive
    "key={e}a"                  ends with a
    "key={ei}a"                 ends with a, case insensitive
    "key={b}a"                  begins with a
    "key={bi}a"                 begins with a, case insensitive
    "key={in}a,b"               At least one of these is in array
    "key={nin}a,b"              Any of these values is not in array
    "key={all}a,b"              All of these contains in array
    "key={empty}"               Field is empty or not exists
    "key={!empty}"              Field exists and is not empty
    "key={mod}a,b"              Docs where key mod a is b
    "key={gt}a"                 value is greater than a
    "key={gte}a"                value is greater or equal than a
    "key={lt}a"                 value is lower than a
    "key={lte}a"                value is lower or equal
    "key={ne}a"                 value is not equal
    "key={size}a"               value is array, and array size is a
    "key={sort_by}"             sort by asc
    "key={sort_by}-1"           sort by desc
    **References to mongo:**
    - [elemMatch](
    - [size](

    Results with fl=false:

     	nest: {
        ed: {
          data: 'value',

    Results with fl=true:

     {'': 'value',


    Allowed date formats:

    • 2010/10/1 (y/m/d)
    • 31/2/2010 (d/m/y)
    • 2011-10-10T14:48:00 (ISO 8601)

    Note: Only valid format is ISO when using date inside q -parameter.


    npm i mongoose-query

    DownloadsWeekly Downloads






    Unpacked Size

    54.9 kB

    Total Files


    Last publish


    • jussiva