The aim is putting together various nql related projects into single, easy to use api. It allows:
- parsing of NQL expression into Mongo JSON (using nql-lang)
- enhancing a database query with additional filters based on provided expression (using mongo-knex)
- querying JSON objects with NQL expressions (using mingo)
Using npm:
npm install @nexes/nql --save
or with yarn:
yarn add @nexes/nql
A simple NQL expression could have following form: featured:true+slug:['photo', 'video']
When parsing it to Mongo JSON with nql(expression).parse()
the output would be:
{
$and: [
{
featured: true
},
{
slug: {
$in: ['photo', 'video']
}
}
]
}
If the same expression would be applied to Knex QueryBuilder object, the following SQL where statement would be generated:
where (`posts`.`featured` = true and `posts`.`slug` in ('photo', 'video'))
Some common usages:
nql('id:3').toJSON();
\\ => {id:3}
nql('id:3').queryJSON({test:true, id:3});
\\ => true
nql('tags:test', {expansions: {tags: 'tags.slug'}}).toJSON();
\\ => {'tags.slug': test}
nql('primary_tag:[photo]', {expansions: [
{key: 'primary_tag', replacement: 'tags.slug', expansion: 'order:0'}
]})
\\ => {$and: [{'tags.slug': {$in: ['photo']}}, {order: 0}]}
Advanced usage example:
// Builds SQL where statement on top of knex Query Builder including:
// - combining custom filter 'primary_tag:test' with overrides filter and defaults
// - expanding shortcut property 'primary_tag' into 'tags.slug' and adding 'posts_tags.sort_order:0' filter
// - builds a where statement with related `tags` table through manyToMany relation
const query = nql('primary_tag:test', {
relations: {
tags: {
tableName: 'tags',
type: 'manyToMany',
joinTable: 'posts_tags',
joinFrom: 'post_id',
joinTo: 'tag_id'
}
},
expansions: [
{
key: 'primary_tag',
replacement: 'tags.slug',
expansion: 'posts_tags.sort_order:0'
}
],
overrides: 'status:published',
defaults: 'featured:true'
});
query
.querySQL(knex('posts'))
.select();
yarn lint
run just eslintyarn test
run lint && tests
Copyright (c) 2013-2022 Ghost Foundation - Released under the MIT license.