Writing Queries

Unless you've been living under a rock somewhere for the last couple of years, you have some idea of what a NoSQL database is. In the broad spectrum of NoSQL systems, SculeJS can most accurately be described as document-oriented in much the same way as MongoDB. That's really no coincidence since SculeJS was designed to be like MongoDB - hence the name: minuscule as opposed to humongous.

If you have some familiarity with the way queries are performed in MongoDB then you're already way ahead of the curve, however it probably isn't a bad idea to quickly read this document and familiarize yourself with some of the quirks inherent to the SculeJS way of doing things.

Query Syntax

Performing queries against SculeJS collections is done using a combination of query expression and query conditions objects. Right now SculeJS supports the following operators:

• $eq: a general equality operator similar to ==

{a:{$eq:1}}
{a:1}

• $ne: a general inequality operator similar to !=

{a:{$ne:1}}

• $gt: an arithmetic operator similar to >
  • {a:
• $gte: an arithmetic operator similar to >=
• $lt: an arithmetic operator similar to <
• $lte: an arithmetic operator similar to <=
• $in: a list equality operator that determines whether or not a value exists within a defined array of values
• $nin: a list equality operator that determines whether or not a value does not exist within a defined array of values
• $all: a list equality operator that determines whether or not an array contains all of the values within a defined array of values
• $size: matches an object, string, or array with the number of elements (length) specified by the argument
• $exists: a boolean operator that determines whether or not a field exists in a document
• $near: a geo-locational proximity operator
• $within: a geo-locational boundary operator
• $and: a logical AND operator
• $or: a logical OR operator

Query expressions are built up using a collection of clauses built around the above operators. Some examples with their SQL equivalents are provided below:

---

SELECT * FROM test WHERE a = 3;

// the following two expressions are equivalent
{a:{$eq:3}}
{a:3}

---

SELECT * FROM test WHERE a = 3 AND b = 4;

// the following two expressions are equivalent
{a:{$eq:3}, b:{$eq:4}}
{a:3, b:4}

---

SELECT * FROM test WHERE a > 3;

{a:{$gt:3}}

---

SELECT * FROM test WHERE a > 3 AND b <= 4;

{a:{$gt:3}, b:{$lte:4}}

---

SELECT * FROM test WHERE a != 3 AND b >= 5

{a:{$ne:3}, b:{$gte:5}}

---

SELECT * FROM test WHERE a = 1 OR a = 2 OR a = 3 OR a = 4

{a:{$in:[1, 2, 3, 4]}}

---

SELECT * FROM test WHERE a != 1 OR a != 2

{a:{$nin:[1, 2]}}

---

SELECT * FROM test WHERE (a = 3 AND b < 4) OR (a > 5 AND b = 10)

{$or:[{a:3, b:{$lt:4}}, {a:{$gt:5}, b:10}]}

---

SELECT * FROM test WHERE a = 3 AND b = 3 AND (a > 10 OR b < 11)

{a:3, b:3, $or:[{a:{$gt:10}},{b:{$lt:11}}]}

All clauses in SculeJS query expression objects are logically AND-ed unless otherwise specified by an $or operator. There are also some caveats to using logical operators:

• You can't nest an $or within an $or
• You can't nest multiple $and expressions

In actual fact SculeJS will barf if it encounters a query expression with mutiple levels of nested logical operators. The following is an example of some queries that will raise exceptions:

{$or:[{a:3},{$or:[{a:10}, {b:11}]}]}
{$and:[{$and:[{b:1}, {a:3}]}, {$or:[{a:3}, {a:10}]}]}

Retrieving data

You can retrieve objects from SculeJS collections using one of three methods:

• find
• findAll
• findOne

find

TODO: write this

findAll

TODO: write this

findOne

TODO: write this

Performing Updates