API Reference

Introduction

The DovetailDB javascript API is very straightforward. Because DovetailDB stores its data as JSON, native Javascript datatypes and objects can be used. At its core, the DovetailDB API simply provides a function to insert, update, remove, and query javascript objects.

Your javascript objects are stored in "bag"s. (a bag roughly corresponds to a table in a relational database) Several bags may exist an a database, and you may create multiple databases for different projects. You must register an accesskey and database name with the API before you make API calls (see dovetail.defaults, below).

This library provides a lightweight interface to the persisted data. Unlike some object-relational mappers, your javascript objects maintain an existence distinct from the persisted objects. For instance, to change the properties of a presisted object, you must call an update function explicitly, not simply edit the property on an object. (though this API could be wrapped in a heavier persistence framework, if desired)

API Example:

// Set this to the accesskey you were assigned:
dovetail.defaults.accesskey = "XXXXXXXXXXXXXXXX";

// Set this to any database name you've created with your acceskey:
dovetail.defaults.db = "SocialNet";

// insert some data:
bob = {name:'Bob',age:32}
dovetail.insert('people', bob);
joe = {name:'Joe',age:21}
dovetail.insert('people', joe);

// Find people named Bob that are 18 or over:
dovetail.query('mybag', {name_is:'Bob',age_min:18}, function(bobs){alert('ID of Bob is '+bobs[0].id);});

// Bob has a birthday:
bob.age=33;
dovetail.update('people', bob.id, bob);

// Remove Joe
dovetail.remove('people', joe.id);

dovetail.query()

dovetail.query(bag, constraints, [options], callback)

Finds objects in a bag.

<bag> (string): The name of the bag to query.

<constraints> (object): An object describing what objects to find. Each key of the object should be a field name to search for, with one of the following suffixes appended. Objects that match all the constraints are returned. Each suffix constrains the named field in a specific manner:

suffix	possible values	meaning
_is	string,number	The field is equal to the value of this key
_in	array	The field is equal one of the values in this array
_notin	array	The field is not equal one of the values in this array
_min	string,number	The field is greater than or equal to the value of this key
_max	string,number	The field is less than or equal to to the value of this key
_exclusivemin	string,number	The field is greater than the value of this key
_exclusivemax	string,number	The field is less than the value of this key

<options> (object, optional): The keys and values of this optional object can be used to customize the behavior of the query.

key	type	meaning
offset	integer	Start returning results after this many initial results
limit	integer	Return at most this number of objects
sort	string	Either: (1) a comma delimeted list of fields, each with an optional direction specifier of "asc" or "desc" (for instance, sort:"age desc, name") -OR- (2) a server-side Javascript function name prefixed with "fn:" (for instance, sort:"fn:cmpMyObjs"). The function must take two objects to compare and return a value that is less than zero or greater than zero if the first argument should sort after or before the second argument, respectively.
comet_timeout	integer	If specified, your query will behave slightly differently. The query will return immediately if there are any available results; however if there are no results, it may wait for results to appear before returning. Generally speaking, the call will wait up to the specified number of seconds, but it may take longer to return or may return with no results in fewer seconds.
map	string	This should be the name of a server-side javascript function that takes a single argument. Each item in the results will be replaced by the return value of this function when given the original result.
reduce	string	This should be the name of a server-side javascript function that takes two arguments. This function will be repeatedly applied to items in the result set until there is only a single result, which is subsequently returned. If a "map" function is also given, that function is applied to each result before reduce is called.

<callback> (function): When the query results are returned from the server, this callback is executed and passed a single parameter. The parameter to the callback is a array of objects that matched the query's constraints.

Returned value: Nothing is returned from this function; use the callback parameter to performs actions based on the results of the query.

Examples:

// setup some data:
dovetail.insert('mybag', {name:'Bob',age:32});
dovetail.insert('mybag', {name:'Joe',age:21});
dovetail.insert('mybag', {name:'Bob',age:18});
function myhandler(rows) {
alert('Found '+rows.length+' rows. Id of first result was '+rows[0].id);
}
// Find people named Bob:
dovetail.query('mybag', {name_is:'Bob'}, myhandler);
// people named Bob or Joe:
dovetail.query('mybag', {name_in:['Bob','Joe']}, myhandler);
// everyone not named Bob:
dovetail.query('mybag', {name_notin:['Bob']}, myhandler);
// everyone 21 or older:
dovetail.query('mybag', {age_min:21}, myhandler);
// everyone ages 16 to 21, but not including 21. (same as 16-20):
dovetail.query('mybag', {age_min:16,age_max_excl:21}, myhandler);
// everyone named Bob that's at least 21 years old:
dovetail.query('mybag', {name_is:'Bob', age_min:21}, myhandler);

dovetail.insert()

dovetail.insert(bag, entry, [callback])

Inserts an object into a bag (and assigns it a unique id). Upon successful insertion, <entry> will be assigned an "id" property.

<bag> (string): The entry will be insterted into this bag.

<entry> (object): The keys and values of this object will be inserted.

<callback> (function, optional): If you wish to trigger some behavior upon successful insertion of the data, you may provide a function here. When called, the function will be given a single string parameter, the id of the inserted object. (this id will have also been assigned to <entry>)

Returned value: Nothing is returned from this function.

Examples:

bob = {name:'Bob',age:32};
dovetail.insert('mybag', bob, function(id) {alert('The id of Bob is available as '+id+' and as '+bob.id);});

update()

dovetail.update(bag, id, entry, [callback])

Modifies a persisted object.

<bag> (string): The bag that contains the object to be modified.

<id> (string): The id of the object to be modified.

<entry> (object): The keys and values to alter on the persisted object. Properties defined in the persisted object will not be removed if they are not defined in <entry> (the new vales simply overwrite existing ones); though there is virtaully no performance improvement for excluding unchanged properties.

<callback> (function, optional): If you wish to trigger some behavior upon successful modification of the data, you may provide a (zero argument) function here.

Returned value: Nothing is returned from this function.

Examples:

bob = {name:'Bob',age:32};
dovetail.update('mybag', '35Wu3GtY6hxkoH1g', {age:50}, function() {alert('Bob is now thrity.');});

remove()

Deletes a persisted object.

dovetail.remove(bag, id, [callback])

<bag> (string): The bag that contains the object to be removed.

<id> (object): The id of the object to be removed.

<callback> (function, optional): If you wish to trigger some behavior upon successful deletion of the object, you may provide a (zero argument) function here.

Returned value: Nothing is returned from this function.

Examples:

dovetail.remove('mybag', bob.id, function() {alert('Bob was removed');});

dovetail.call()

dovetail.call(function, parameters, [callback])

Invokes a function on the server side and returns the result.

<function> (string): The name of the function to call.

<parameters> (array): An array of aguments with which to call the function.

<callback> (function, optional): If given, this callback will be invoked when the server returns. It will be given a single parameter, which will be the return value of the javascript function that was executed.

Returned value: Nothing is returned from this function.

Examples:

// first, we create the server side javascript function.
// This is accomplished by inserting an entry containing the javascript code text
// into the "code" bag of the global "_metadata" database:
dovetail.defaults.db = '_metadata'
dovetail.insert('code', {type:'javascript',db:'SocialNet',filename:'incrementor.js',code:'function addone(x){return x+1}'});

// now, we turn back to our database, and call our newly created function:
dovetail.defaults.db = 'SocialNet'
dovetail.call('addone', [6], function(n) {alert('Six plus one is '+n);});

dovetail.defaults

You may modify properties of this object to control the behavior of API calls. Most notibly, the "accesskey" and "db" properties must be set before any API function can be called.

property	type	meaning
accesskey	string	Your acceskey. You must set an accesskey to make requests.
db	string	The name of the database to use.
server	string	The hostname of the DovetailDB server to use. The hostname may be suffixed with a colon and port number. By default, this is set to our hosted server.
errorcb	function	When an API call fails for some reason, this function will get called instead of the normal callback. By default, it displays an alert box with some brief information on the error. The callback will be supplied one object parameter with the following keys: "name" (a short string identifier for this kind of error), "message" (a more detailed message explaining the error), and optionally "stacktrace" (a server-side javascript stack trace, if server-side javascript was executing)

Examples:

dovetail.defaults.accesskey = "";