Restful query builder for mongodb with mongoose

Usage no npm install needed!

<script type="module">
  import cellebAutoQuery from 'https://cdn.skypack.dev/@celleb/auto-query';



Build Test

Restful query builder for mongodb with mongoose using your url query

npm i @celleb/auto-query


Define your mongoose model as usual

import { Schema } from 'mongoose';
const userSchema = new Schema({
 name: String,
 surname: String,
 likes: [String],
 car: [
   model: String,
   year: Number,
 activities: [
   name: String,

Define your dictionary

The dictionary is used to transform the api fields to the database fields. If the fields are the same then you can exclude it from the dictionary. The dictionary is POJO with string for both keys and values.

For example {apiField: 'databaseField' }

// shallow/flat dictionary/map
const dictionary = {
 firstName: 'name',
 lastName: 'surname',
 'vehicle.model': 'car.model',
 'vehicle.year': 'car.year',

Create your model and instantiate the query builder

The AutoQuery takes a model and a dictionary.

import { AutoQuery } from '@celleb/auto-query';
import mongoose from 'mongoose';

const User = mongoose.model('User', userSchema);

const qb = new AutoQuery(User, dictionary);

Use the query builder instance in your route handler

Call the query builder's .build method with the request query. The build method returns a Mongoose query and you can chain other methods before calling .exec().

async function routHandler(req: Request, res: Response) {
 return res.json(await qb.build(req.query).exec());

Query Parameter Interface

The following are fields support on the query

interface QueryParams = {
    match?: Record<string, string|number|Array<string|number>>;
    sort?: string;
    skip?: number;
    limit?: number;
    select?: string[];

For example: url?match[firstName]=Jonas&sort=firstName&skip=0&limit=10&select=firstName&select=lastName.

URL Query Fields

You decide how you encode and decode your url query but the decoded query must match the Query Parameter Interface above.


Allows you to query the database using specific fields and operators.

Supported operations

Symbol Description Usage
= Equal to or [in]. Do not add an additional equal sign url?match[firstName]=Jonas or with array url?match[firstName]=Jonas,Jon'
! Not equal to to or not in [nin]. url?match[firstName]=!Jonas or with array url?match[likes]=Football,!Tennis'
>: Greater than or equal url?match[vehicle.year]=>:2017
> Greater than url?match[vehicle.year]=>2017
<: Less than or equal url?match[vehicle.year]=<:2017
< Less than or equal url?match[vehicle.year]=<2017

More operations will be added in the future


Specifies the field and the order by which to sort the results.

Use sort?=-fieldName for descending order and sort=fieldName for ascending order.


Specifies the number of records to skip in the database.

For example skip=10 skips the first 10 records.


Limits the number of matching records returned.

Example limit=10 returns the first 10 results.