Introduction to the Backbone Query API

As a relatively “new” user of Backbone.js, I looked at different JSON querying tools that existed. At the time I was still struggling with using JSON as the data source and wrapping my head around the process for querying the data set that was contained in a large string. Coming from a Java and strong PL/SQL background in Oracle, I wanted to find something akin to the PL/SQL language I was used to. So I set out on a quest to find something that would whet my appetite.

Some folks like to just simply use Underscore with the _.each or _.findwhere, or another of the other API choices for narrowing the result set down. I, on the other hand, wanted a more precise querying tool that could give me the “likes,” “greater/less than,” and case-insensitive type searches.

I thought that there had to be something out there that does these types of things already. So I searched and found things like JsLinq, SQLike, and so on. Some were okay, but as I was also new to the Backbone scene, I wanted it to translate well to Backbone.

I found backbone_query much to my liking. The API was built for Backbone specifically and had a lot of the items I was looking for.

Getting Started

You can use the standalone file, Jam install, or NPM install into Node.js for use. From there it is pretty simple. All you need to do is create Backbone.QueryCollection instead of the existing Backbone.Collection. This allows the new collection, which extends Backbone.Collection, to be queried with the API.

Query API

Here is a basic example:

MyCollection.query({
    new: true,
    amount: {$gt:10}
});

You can see here that the code is pretty similar to that of an Underscore _.findWhere({new: true}) search. So, syntactically it is very similar. Now let me show a little more advanced query:

MyCollection.query(
    {tags: { $any: ["cheese", "bread", "cat litter"]}},
    {sortBy: "name", order: "desc"}
);

The query above searches the “tag” field and tries to find any of the given values. It also sorts the result by name desc. You can see that this type of querying and ordering can come in handy. It can allow you to only return the results of the query, but sort in many different ways.

Here is an example of the $equal property. It doesn’t have to be explicitly used, but can be:

MyCollection.query({ title:"Test" });
MyCollection.query({ title: {$equal:"Test"} }); // Same as above

The query returns all matches where title = ‘Test’.

In addition there are many different operators to use for narrowing down your searches. Some of which are:

• $contains – the model property is an array and searches for the value in the array
• $ne – the results return all models where the property doesn’t equal the value
• $lt, $lte, $gt, $gte – less than, less than or equal to, greater than, greater than or equal to the value
• $between – returns models where they are between a min and a max value

The list goes on for things such as “ins,” “not ins,” “all,” “like,” “like case insensitive,” “regex,” etc. You can also do callback functions. We are in JavaScript!

MyCollection.query({ title: {$cb: function(attr){ return attr.charAt(0) === "c";}} });
// Returns all models that have a title attribute that starts with "c"

Combined Query

The API allows for combined queries such as and, or, nor, and not.

$and

MyCollection.query({ $and: { title: {$like: "News"}, likes: {$gt: 10}}});
// Returns all models that contain "News" in the title and have more than 10 likes.
MyCollection.query({ title: {$like: "News"}, likes: {$gt: 10} });
// Same as above as $and is assumed if not supplied

$or

MyCollection.query({ $or: { title: {$like: "News"}, likes: {$gt: 10}}});
// Returns all models that contain "News" in the title OR have more than 10 likes.

$nor

MyCollection.query({ $nor: { title: {$like: "News"}, likes: {$gt: 10}}});
// Returns all models that don't contain "News" in the title NOR have more than 10 likes.

$not

MyCollection.query({ $not: { title: {$like: "News"}, likes: {$gt: 10}}});
// Returns all models that don't contain "News" in the title AND DON'T have more than 10 likes.

Compound Query

You can also search by compound combined queries to make your search more precise.

MyCollection.query({
    $and: { title: {$like: "News"}},
    $or: {likes: {$gt: 10}, color:{$contains:"red"}}
});
//Returns models that have "News" in their title and
//either have more than 10 likes or contain the color red.

There is also sorting, paging, and caching facilities for those who want to go down more advanced roads of using the API.

Conclusion

For those who are transitioning from PL/SQL into Backbone and want a syntax close to that of which they are familiar, I suggest using this API. It will help speed up your understanding of JSON results and searching for particular results. The performance is top-notch even with very large result sets. It has helped my own transition and made for some well performing code.

— Matt McCandless, asktheteam@keyholesoftware.com