Writing queries

The heart of TaffyDB and any database is running queries against your data. This is done after creation of your database by calling the root function and building Filter Objects.

// Create a new empty database
var db = TAFFY();

// Run a query against the DB to return all rows
db();

// Real world example - remove all records
db().remove();

Looking up individual records

Every object within a TaffyDB collection has a ___id value set by TaffyDB. This value is not intended for you to know, but is useful when building dynamic applications. This can be used to lookup a record by passing it into the root function as a string.

// Looks up a record based on its id
db("T000008R000002");

// Real world example - update records "status" column
db("T000008R000002").update({status:"Active"});

This also works if you have a copy of the whole record.

// get the first record
var firstRecord = db().first();

// look up this record again
db(firstRecord);

// Real world example - update records "status" column
db(firstRecord).update({status:"Active"});

Using functions

To give you full control over the results of your query you can always pass in a function. Just have it return true if you want the record in your final results.

// functional example, returns all records
db(function () {
	return true;
});


// Real world example - function returns records with a status of active
db(function () {
	return (this.status == "Active") ? true : false;
});

Basic queries

TaffyDB uses a very JavaScript centric Filter Object for looking up queries. There is no string concatenation and you can quickly compose these by hand or dynamically from within your app. The filter object is compared against each record using some business rules and if it passes the record remains in the results set.

The most common Filter Object is used simply to check if a column is equal to value.

// does a match for column and value
db({column:"value"});


// Real world example - records with a status of active
db({status:"Active"});

This is the short form of this

// does a match for column and value
db({column:{is:"value"}});


// Real world example - records with a status of active
db({status:{is:"Active"}});

The "is" part of this expressions can be swapped out for a variety of other comparisons as listed below.

Using !(bang)

For any comparison operator you can quote it and add a ! sign to reverse the meaning.

// does a match for column that is not a value
db({column:{"!is":"value"}});

// Real world example - records with a status other than of active
db({status:{"!is":"Active"}});

Adding additional filters

Using the almighty comma you can add additional lookups to you Filter Object.

// does a match for column that is a value and column2 is a value
db({column:"value",column2:"value"});

// Real world example - records with a status of active and a role of admin
db({status:"Active",role:"Admin"});

You can also pass in additional Filter Objects into the function

// does a match for column that is a value and column2 is a value
db({column:"value"},{column2:"value"});

// Real world example - records with a status of active and a role of admin
db({status:"Active"},{role:"Admin"});

Using arrays for IN and OR

In a database you can use "in" to pass in a collection of values to compare against. This is possible in TaffyDB via the array.

// does a match for column that is one of two values
db({column:["value","value2"]);

// Real world example - records with a status of active or pending
db({status:["Active","Pending"]});

You can also pass in an array of Filter Objects with each one being treated as a logical OR.

// does a match for column that is one of two values
db([{column:"value"},{column:"value2"}]);

// Real world example - records with a status of active or pending
db([{status:"Active"},{status:"Pending"}]);

Bringing it all together

A real world example of a complex query.

// return records where the role is Admin and the status is Active. 
// Also return records where the role is Admin, the status is Pending, and the manager_review is true

db({role:"Admin"},[{status:"Active"},{status:"Pending",manager_review:true}]);

Comparison Operators

In addition to the default "is" operator there are a lot of other operators you can use to lookup records.