Easy Query
A DSL for turning search strings into Mongo selectors.
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
orkey: "value with space"
- Either
value1
orvalue2
:key: value1;value2
- Both
value1
andvalue2
: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 = ;eq;
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