XplainDB Cookbook
This cookbook provides a list of different examples for the XplainDB package.
Connect to your Backend
When connecting to an Xplain backend, you have to provide three parameters: a username, a password and a startup configuration.:
// connecting to an Xplain backend using the connect() method...
var xplain = new Xplain.Db.Connection();
xplain.connect({
user: 'username',
password: 'password',
configuration: 'startupConfig.xstartup',
success: function(){
doSomething();
},
error: function(){
alert('oops... better check your username and password');
}
});
Basic Query Definition
Four different ways to define the same query: a query with a single groupBy along “Patient.DoB.Age” (this is the standard dot-notation where Patient.DoB.Age references the attribute named “Age” in the dimension named “DoB” in the “Patient” object). Furthermore, an aggregation is being defined using the COUNT function.:
// define a simple query with one groupBy and one aggregation...
var query1 = new Xplain.Db.Query({
aggregation: {
type: 'COUNT',
measure: 'Patient'
},
groupBy: {
attribute: "Patient.DoB.Age"
}
});
// a different way to define the same query
var agg = new Xplain.Db.Aggregation({
type: 'COUNT',
measure: 'Patient'
});
var gp = new Xplain.Db.GroupBy({
attribute: "Patient.DoB.Age"
});
var query2 = new Xplain.Db.Query({
aggregation: agg,
groupBy: gp
});
// yet another way to define the same query
var query3 = new Xplain.Db.Query();
query3.addAggregation(agg);
query3.addGroupBy(gp);
// this defines the same query again, but using the shorthand
// 'open' method defined in Xplain.Db.Attribute
var session = new Xplain.Db.Session();
var ageAttribute = session.get("Patient.DoB.Age");
var query2 = ageAttribute.open();
Query Execute and Open
In this example, a query is being defined first. After that the query is being executed and opened (see Xplain.Db.Query docs for difference between open and execute).:
// execute query - see Xplain.Db.Query docs for difference between open and execute
query.execute({
success: function(d) {
console.log(JSON.stringify(d.getData()));
}
});
// open query - see Xplain.Db.Query docs for difference between open and execute
query.open({
success: function(d) {
console.log(JSON.stringify(d.getData()));
}
});
Configuration of Backend Calls: Part I
In this example, we pass a set of parameters to the query.open() method to configure the request send to the backend. We actually pass all properties possible:
We define a success function, triggered if the query has been opened successfully
We define a user defined error function, that will be triggered if a problem occurs
We set the timeout to 5 seconds
Furthermore, we set async, cors and url to the default values:
// open query.
query.open({
success: function(d) {
console.log(JSON.stringify(d.getData()));
},
error: function(d) {
// do something here...
alert('Ooops...');
},
timeout: 5000,
async: true,
cors: false,
url: '/'
});
Configuration of Backend Calls: Synchronous
You can also work in synchronous mode. This is NOT recommended (as the script - and all other tasks of the browser - will stop until this request has finished). If you use execute or open synchronous, then these methods will return the result. Thus var result = query.open(); will work.:
// open query.
var result = query.open({
async: false
});
console.log(JSON.stringify(result.getData()));
Using Batch Jobs
The idea behind a batch job in Xplain is simple: instead of sending one query after another, you combine a set of queries into a batch and then send this batch to the backend. Thus, the backend does not have to compute and reply to one query after another but to one single (batch) query.:
// start batch job
Xplain.Db.Batch.start();
var query1 = new Xplain.Db.Query({
groupBy: {attribute:'Patient.Gender.Gender'},
aggregation: {type: 'COUNT', measure: 'Patient'}
});
query1.open();
var query2 = new Xplain.Db.Query({
groupBy: {attribute:'Patient.DoB.Age'},
aggregation: {type: 'COUNT', measure: 'Patient'}
});
query2.open();
// stop "recording" queries for this batch job
Xplain.Db.Batch.stop();
// now run that batch-job and depict all queries
Xplain.Db.Batch.run({
success: function(d) {
console.log(query1.getResult().getData());
console.log(query2.getResult().getData());
}
});
Dealing with Sessions
Dealing with Sessions or “how to get an instance to a session” is pretty easy. No matter where you use or initiate an instance of Xplain.Db.Session, this instance will automatically have access to all session data, e.g. all queries within this session, all metadata about dimensions, attributes, etc.:
function Foo (type) {
var q = Xplain.Db.Query({
id: 'myQuery',
groupBy: {attribute:'Patient.DoB.Age'},
aggregation: {type: 'COUNT', measure: 'Patient'}
});
q.open({
success: function(d) {
console.log(d.getData());
}
})
}
function Bar (type) {
// get an instance of a session
var s = new Xplain.Db.Session();
// get data of query with ID 'myQuery'
var d = s.findQuery('myQuery').getResult().getData();
}
Session Metadata
You may also use Xplain.Db.Session as a starting point to fetch different types of metadata, e.g. a list of all available objects, find dimensions or fetch the type of an attribute…:
// get an instance of a session
var s = new Xplain.Db.Session();
// simple: get root object
var root = s.getRootObject();
console.log('Object Infos:');
console.log('Name: ' + root.getName());
console.log('Path: ' + JSON.stringify(root.getPath()));
console.log('');
// now, get an object and echo some metadata
var obj = s.findObject('Patient');
console.log('Name: ' + obj.getName());
// now, get all sub-objects of this object
var subObjs = obj.getSubObjects();
for (var i=0; i<subObjs.length; i++) {
console.log('- SubObject Infos:');
console.log(' Name: ' + subObjs[i].getName());
console.log(' Path: ' + JSON.stringify(subObjs[i].getPath()));
}