npm install @tryghost/nql
npm install @tryghost/nql --save
`
or with yarn:
`
yarn add @tryghost/nql
`Example
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:
`javascript
{
$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:
`sql
where (posts.featured = true and posts.slug in ('photo', 'video'))
`Usage
Some common usages:
`javascript
nql('id:3').toJSON();
\\ => {id:3}
``javascript
nql('id:3').queryJSON({test:true, id:3});
\\ => true
``javascript
nql('tags:test', {expansions: {tags: 'tags.slug'}}).toJSON();
\\ => {'tags.slug': test}
`
`javascript
nql('primary_tag:[photo]', {expansions: [
{key: 'primary_tag', replacement: 'tags.slug', expansion: 'order:0'}
]})
\\ => {$and: [{'tags.slug': {$in: ['photo']}}, {order: 0}]}
`Advanced usage example:
`javascript
// 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();
`Test
- yarn lint run just eslint
- yarn test` run lint && testsCopyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.