A user-friendly string based query format for Mongo
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
src
test
.babelrc
.editorconfig
.eslintrc
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
gulpfile.js
package-lock.json
package.json

README.md

Easy Query

A DSL for turning search strings into Mongo selectors.

npm

The motivation behind this tiny library is that I needed a super simple query language usable by end users without any programming knowledge.

For example the search string: name: "John Appleseed" age: >20 would yield a selector:

{$and: [{name: "John Appleseed"}, {age: {$gt: 20}}]}

The simple format can be explained quickly to the users as:

  • Write key: value or key: "value with space"
  • Either value1 or value2: key: value1;value2
  • Both value1 and value2: key: value1 key: value2
  • Less than key: <5 etc.

Installation

The package is on npm and installable as: npm install easy-query-dsl.

Usage

Using the library isn't complicated either:

var eq = EasyQuery(options);
eq.parse('name: "John Appleseed" age: >20');

Though to produce correct queries you need to configure the library using the options object.

It has two fields: default and keys. Default contain one key object and keys contains a list of key objects.

The default field defines how searches not specifying any key is handled and keys defines how to handle key: value searches.

A key object defines a field to search for over the database and how to handle that field.

There are three types of key objects:

String

The string type handles the values as strings and uses Regular Expressions in the selector.

They have two options: caseSensitive and fuzzy.

{
  field: 'field_name',     // The name of the field in the database.
  type: 'string',          // The type
  alias: ['f'],            // The strings used by the user to specify the field
  opts: {                 // Options for that type
    caseSensitive: false,
    fuzzy: true,
  }
}

Number

The number type handles the values as number and allows the user to specify comparators such as: >5, <5, !5, >=5 and <=5 for the value.

{
  field: 'field_name',
  type: 'number',
  alias: ['f'],
  opts: {}
}

Text

The text type uses the Mongo text search operator and requires a text index for that field. Note that the text operator comes with restrictions and an internal syntax in mongo. Read more here.

They have two options: caseSensitive and diacriticSensitive.

{
  field: 'field_name',
  type: 'text',
  alias: ['f1'],
  opts: {
    caseSensitive: false,
    diacriticSensitive: false,
  }
}

Complete Example

{
  default: {
    field: 'field_name',
    type: 'text',
    // The default doesn't use the alias field.
    opts: {
      caseSensitive: false,
      diacriticSensitive: false,
    }
  }
  keys: [
    {
      field: 'field_name',
      alias: ['f1'],
      type: 'string',
      opts: {
        caseSensitive: false,
        fuzzy: true,
      }
    },
    {
      field: 'field_name',
      alias: ['f1'],
      type: 'number',
      opts: {}
    }
  ]
}

Language Definition

Below follows an informal sketch of the language.

Basics:

key: value -> {key: value}
key: "value with spaces" -> {key: "value with spaces"}
key: value1;value2 -> {$or: [{key: value1}, {key: value2}]
key: value1  key: value2 -> {$and: [{key: value1}, {key: value2}]
key1: value1  key2: value2 -> {$and: [{key1: value1}, {key2: value2}]

String type:

Fuzzy: key: value -> {key: $regex{ pattern: .*value.*} }

Number type:

key: >value -> key: {$gt: value}
key: <=value -> key: {$lte: value}
key: !value -> key: {$ne: value}

Text type:

key: value -> {$text: {$search: value, $caseSensitive: false, $diacriticSensitive: false}}

License

The MIT License (MIT)

Copyright (c) 2018 Erik Gärtner