The document describes a JavaScript and jQuery API for interacting with Google Apps Script's ScriptDB, enabling real-time data sharing and maintenance directly from web applications. It details how to perform various operations such as creating, updating, querying, and deleting objects, while also comparing it to similar APIs. Additionally, it covers access control, batching of requests, and the handling of dates, silos, and multiple databases within the ScriptDB environment.

1. javaScript/jQuery
API for ScriptDB
Google Apps ScriptDB from a webapp

2. what is this API for?
● Allow maintenance and query Google Apps
Script ScriptDB directly from a client webapp
● Share data in real time between Google
Docs, webapps and Excel (using VBA API
for Excel)
● a free noSQL database for javascript
webapps and Excel

3. COMPONENTS
the same handlers are used by
the VBA API
Your
Your
Your
code
code
client
code
cookie
simple
noSql
Your
ScriptDB
dispatcher
rest
scriptdb
API
scripdb api credentials
Your
Your
code
Multiple
code
ScriptDB
Your GAS
webapp
Handler (s)
GAS
Library
API

4. access control
User and
Access
type
credentials
your entry/
your scope
cookie
●
●
Can be used to control access operations by
endpoint
Only needs to be stored one time
new cScriptDbCom().setScriptCredentials( {
endPoint : gasHandlerEndPoints.scriptdbrequesthandler,
restAPIKey : 'xliberationApp',
scopeEntry : 'rest',
credentialsEntry: 'dbTest',
clientKey:'xliberation',
library: 'dbTest',
needDebug: false,
needOauth: false } );

5. comparison with parse.com and
VBA scriptDB API
VBA and GAS Main Apps are virtually the
same code irrespective of the whether parse
or scriptdb is used
VBA and javascript clients have similar code
and share the same GAS handlers and
databases
cParseCom VBA
API
cScriptDBCom
VBA API
cParseCom
GAS API
cScriptDBCom
javascript API
parse.com restAPI handler
GAS scriptDB webApp and API library
parse.com cloud based noSQL
database
GAS scriptDB cloud based noSQL database

6. note on examples
All the examples that follow put their results in a
page element using this function
/* display contents of some object at given element
* @param {object} control some object
* @param {string} id the id of the element
* @return {null}
*/
function renderScriptDb(control,id) {
$(id).text(JSON.stringify(control));
}

7. optimization and batching
● The gas library api will batch all requests it can.
● Batching is done automatically by the API
● Operations are asynchronous and orchestrated by
promises
getScriptDb("VBAParseCustomers","dbTest").getCount()
.done (function (data,cob) {
renderScriptDb(data.count,'#countcopycustomers');
})
.fail(function (data,cob) {
renderScriptDb(JSON.stringify(data),'#countcopycustomers');
});

8. example - create object (s)
Data is stored in silos within one or more ScriptDb
one object
dbTarget.createObject(data)
.done ( function(data) { .. do something good .. })
.fail ( function (error) { .. do something bad.. });
multiple objects
db.createObjects([some objects...])
.done( function (data) {...it worked..})
.fail( function (error) {...it failed..});

9. example - do a query
Queries are by example, and can include limit/skip
var dbCustomer = getScriptDb("VBAParseCustomers","dbTest");
dbCustomer.getObjectsByQuery({country:"United States"})
.done (function (data,cob) {
renderScriptDb(data.results,'#countryquery');
})

10. example - update objects
All matching objects are updated to the given value. New
fields are created, existing fields are replaced
getScriptDb("testClass","dbTest").updateObjects({town:’chicago’},null,{state:'IL’'})
.done(function(data){
renderScriptDb(data,'#bitupdate');
})
.fail(function(error){
renderScriptDb(error,'#bitupdate');
});

11. example - count matching objects
Count operations can have optional queries
getScriptDb("VBAParseCustomers",entry).getCount({country:"United States"})
.done (function (data,cob) {
renderScriptDb(data.count,'#countquery');
})
.fail(function (error,cob) {
renderScriptDb(fSON.stringify(error),'#countquery');
});

12. example - get object by id
Each object is assigned a unique Id returned by queries
getScriptDb("VBAParseCustomers",entry).getObjectById(objId)
.done (function (data,cob) {
renderScriptDb(data.results,'#id');
})
.fail(function (error,cob) {
renderScriptDb(JSON.stringify(error),'#id');
});

13. example - delete objects
All objects matching the query are deleted
dbTarget.deleteObjects({customerid:1})
.done (function (data,cob) {
renderScriptDb(data.results,'#delete');
})
.fail(function (error,cob) {
renderScriptDb(JSON.stringify(error),'#delete');
});

14. limits and skipping
Queries are subject to limits, so you can work multiple passes for big queries using skip/limit. A recursive convenience
method is provided to use, and show you how to do it (eg. db.getAllMatchingQueries({state:’IL’}) will take care of this
automatically as below - but watch out for memory usage)
self.getAllMatchingQueries = function (queryJob, queryParameters,list, defer) {
list = list || [];
defer = defer || $.Deferred();
var jobSkip = {skip:list.length};
self.getObjectsByQuery (queryJob, self.mergeParameters(queryParameters, jobSkip))
.done (function (data,defers) {
if (!data.results.length) {
defer.resolve(list);
}
else {
for (var i = 0 ; i < data.results.length; i++) {
list.push(data.results[i]);
}
self.getAllMatchingQueries(queryJob,queryParameters,list,defer);
}
})
.fail (function (error,defers){
defer.reject (error);
});
return defer.promise();
};
this is
automatically
handled for update
and delete

15. notes on finalFlush()
Because POST operations are batched, you need to call finalFlush() at some
point for each scriptdbcom instance. This clears any batch queues and resolves
any outstanding promises. It can be called as often and whenever you like, but
should be called at least once if there have been any POST type operations
(CREATE,UPDATE,DELETE), following the last one. Note that POST
operations are not resolved until they have been successfully flushed from the
Batch Queue.
finalFlush() also returns a promise for when all its work is complete.
dbTarget.finalFlush().then( function (data) { … do something , its all over… } );

16. dates and times
These are handled the same way as parse.com
"date":{
"__type":"Date",
"iso":"2013-08-22T00:00:00.000Z"
}

17. silos and parse classes
● A Silo is like a parse Class. For 2D data it can be
considered like a table.
● Multiple classes can be held in the same scriptDB.
● scriptDB siloing is handled automatically
● A seperate cScriptDbCom instance should be
instantiated for each class being worked on

18. multiple scriptDB
● The scriptDB dispatcher handled which actual scriptDB
to write to.
● Multiple DBs can be used by referencing multiple
libraries in the scriptDB dispatcher.
● Library names will be signalled to the dispatcher if they
are in the setup for this entry

19. restricting operations
You may want to allow a different kind of access to certain users.
●
provide a different URL or use the app keys to signal some restricted access , and include something like this in
the doGet() and doPost() functions
var whatsAllowed = ['query','count','getbyid'];
●
setting that configuration up under a different entry
new cScriptDbCom().setScriptCredentials( {
endPoint : gasHandlerEndPoints.scriptdbrequesthandler,
restAPIKey : 'xliberationApp',
scopeEntry : 'rest',
credentialsEntry: 'dbTest',
clientKey:'xliberation',
library: 'dbTest',
needDebug: false,
needOauth: false } );

20. accessing from other apps
● The scriptDB GAS handler API can be
accessed using any rest query mechanism.
● The VBA API and javaScript just manages
the conversation with the scriptDB GAS
handler
● Examples of other languages will be on
Excel Liberation at a later date.

21. public facing scriptdb
OAuth2 support is not yet released for the JavaScript
version (it is with the VBA one). This is because Google
Apps Script doesn’t yet support CORS (cross origin
resource sharing) for javaScript clients.
A temporary workaround for access control is described
here.

22. further detail
All this code is downloadable or copyable from
Google Apps Script Libraries.
For more information see Excel Liberation