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.

is	Example: {column:{is:value}}	Used to see if a column is of same type and value of supplied value.
==	Example: {column:{'==':value}}	Used to see if a column matches a supplied value using JavaScript's liberal coercion rules.
===	Example: {column:{'===':value}}	Used to see if a column is of same type and value of supplied value.
isnocase	Example: {column:{isnocase:value}}	Used to see if a column value is equal to a supplied value. Ignores case of column and value.
left	Example: {column:{left:value}}	Used to see if the start of a column is the same as a supplied value.
leftnocase	Example: {column:{leftnocase:value}}	Used to see if the start of a column is the same as a supplied value. Ignores case of column and value.
right	Example: {column:{right:value}}	Used to see if the end of a column is the same as a supplied value.
rightnocase	Example: {column:{rightnocase:value}}	Used to see if the end of a column is the same as a supplied value. Ignores case of column and value
like	Example: {column:{like:value}}	Used to see if column contains a supplied value.
likenocase	Example: {column:{likenocase:value}}	Used to see if column contains a supplied value. Ignores case of column and value
regex	Example: {column:{regex:value}}	Used to see if column matches a supplied regular expression.
lt	Example: {column:{lt:value}} or {column:{'<':value}}	Used to see if column is less than a supplied value.
lte	Example: {column:{lte:value}} or {column:{'<=':value}}	Used to see if column is less than or equal to a supplied value.
gt	Example: {column:{gt:value}} or {column:{'>':value}}	Used to see if column is greater than a supplied value.
gte	Example: {column:{gte:value}} or {column:{'>=':value}}	Used to see if column is greater than or equal to a supplied value.
has	Example: {column:{has:value}}	Used to see if column that is an object has a value or object appearing in its tree.
hasAll	Example: {column:{hasAll:value}}	Used to see if column that is an object has a value or object appearing in its tree.
isSameArray	Example: {column:{isSameArray:value}}	Used to see if column is an array and is the same as a supplied array.
isSameObject	Example: {column:{isSameObject:value}}	Used to see if column is an object and is the same as a supplied object.
isString	Example: {column:{isString:true}}	Used to see if column a string.
isNumber	Example: {column:{isNumber:true}}	Used to see if column a number.
isArray	Example: {column:{isArray:true}}	Used to see if column an array.
isObject	Example: {column:{isObject:true}}	Used to see if column an object.
isFunction	Example: {column:{isFunction:true}}	Used to see if column a function.
isBoolean	Example: {column:{isBoolean:true}}	Used to see if column a boolean (true/false).
isNull	Example: {column:{isNull:true}}	Used to see if column null.
isUndefined	Example: {column:{isUndefined:true}}	Used to see if column undefined.