Build search queries for objection.js models using HTTP query parameters.
npm install objection-find 
- Introduction
- Installation
- Getting started
- Query parameters
- API documentation
Note: since Objection.js (which this library is based on) now requires Node 6.0.0 as the minimum, objection-find will not work on node < 6.0.0 either.
Objection-find is a module for building search queries for objection.js
models using HTTP query parameters. You can easily filter, order and page the result based on model's properties and
relations using simple expressions. Relations can be eagerly fetched for the results using objection.js relation
expressions.
Using objection-find in an express route is as easy as this:
``js
const findQuery = require('objection-find');
// Our objection.js model.
const Person = require('../models/Person');
expressApp.get('/api/persons', function (req, res, next) {
findQuery(Person)
.allow(['firstName', 'movies.name', 'children.age', 'parent.lastName'])
.allowEager('[children.movies, movies, parent.movies]')
.build(req.query)
.then(function (persons) {
res.send(persons);
})
.catch(next);
});
`
Objection-find can be used with any node.js framework. Express is not a requirement. The route we just created can
be used like this:
`js
$http({
method: 'GET',
url: '/api/persons',
// HTTP Query parameters.
params: {
// Select all persons whose first name starts with 'j' or 'J'
'firstName:likeLower': 'J%',
// And who have acted in the movie 'Silver Linings Playbook'.
// This checks if the relation movies contains at least
// one movie whose name equals 'Silver Linings Playbook'.
'movies.name:eq': 'Silver Linings Playbook',
// And who have at least one child younger than 10.
// This checks if the relation children contains at least
// one person whose age is less than 10.
'children.age:lt': 10,
// Order the result by person's parent's last name.
// parent is a one-to-one relation.
'orderBy': 'parent.lastName',
// Fetch relations for the results. This is an objection.js
// relation expression. Check out objection.js for more info.
'eager': '[children, movies, parent.movies]',
// Fetch only count of entries that satisfy given criteria. Value can include optional alias parameter, e. g. 'id as countId'. '*' is a valid value.
'count': 'id',
// Group fetched entries by specified properties. Primarily intended to be used together with 'count' parameter'.
'groupBy': 'firstName,lastName',
// Select a range starting from index 0
'rangeStart': 0,
// Select a range ending to index 4
'rangeEnd': 4
}
}).then(function (res) {
const persons = res.data.results;
console.log(persons.length); // --> 5
console.log(persons[0].children);
console.log(persons[0].movie);
console.log(persons[0].parent.movies);
// Total size of the result if the range wasn't given.
console.log(res.data.total);
});
`
In our example Person model had a one-to-one relation parent, a many-to-many relation movies and one-to-manychildren
relation . This example used the $http module of AngularJS but you can use
objection-find with anything that can send an HTTP request.
Documentation on the supported query parameters can be found here and API documentation
here.
It is recommended to use query builder for constructing query parameters on the client side.
`sh`
npm install objection objection-find
Easiest way to get started is to use the objection.js example project
and copy paste this to the api.js file:
`js
const findQuery = require('objection-find');
app.get('/persons/search', function (req, res, next) {
findQuery(Person).build(req.query).then(function (persons) {
res.send(persons);
}).catch(next);
});
`
You also need to run this in the root of the example project to install objection-find:
`sh`
npm install --save objection-find
Now you can start bombing the /persons/search route. Documentation on the supported query parameters can be found
here.
Objection-find understands two kinds of query parameters: filters and special parameters.
A filter parameter has the following format:
`
A propertyReference is either simply a property name like firstName or a reference to a relation's property likechildren.age (children is the name of the relation).
filter is one of the built-in filters eq, neq, lt, lte, gt, gte, like, likeLower in, notNull or isNull.registerFilter
Filter can also be a custom filter registered using the method.
The following examples explain how filter parameters work. For the examples, assume we have an objection.js model
Person that has a one-to-one relation parent, a many-to-many relation movies and one-to-many relation children.
| Filter query parameter | Explanation |
|------------------------------------|---------------------------------------------------------------------------------------------------------|
| firstName=Jennifer | Returns all Persons whose first name is 'Jennifer'. |firstName:eq=Jennifer
| | Returns all Persons whose first name is 'Jennifer'. |children.firstName:like=%rad%
| | Returns all Persons who have at least one child whose first name contains 'rad'. |lastName\|movies.name:like=%Gump%
| | Returns all Persons whose last name contains 'Gump' or who acted in a movie whose name contains 'Gump'. |parent.age:lt=60
| | Returns all persons whose parent's age is less than 60. |parent.age:in=20,22,24
| | Returns all persons whose parent's age is 20, 22 or 24. |
Filters are joined with AND operator so for example the query string:
`
firstName:eq=Jennifer&parent.age:lt=60&children.firstName:like=%rad%
would return the Persons whose firstName is 'Jennifer' and whose parent's age is less than 60 and who have
at least one child whose name contains 'rad'.
In addition to the filter parameters, there is a set of query parameters that have a special meaning:
| Special parameter | Explanation |
|-----------------------------------|----------------------------------------------------------------------------------------------------------|
| eager=[children, parent.movies] | Which relations to fetch eagerly for the result models. An objection.js relation expression. That pass to withGraphFetched. |join=[parent, parent.movies]
| | Which relations to join and fetch eagerly for the result models. An objection.js relation expression. That pass to withGraphJoined. |orderBy=firstName
| | Sort the result by certain property. |orderByDesc=firstName
| | Sort the result by certain property in descending order. |rangeStart=10
| | The start of the result range (inclusive). The result will be {total: 12343, results: [ ... ]}. |rangeEnd=50
| | The end of the result range (inclusive). The result will be {total: 12343, results: [ ... ]}`. |