Xplain.Db.Query

Xplain.Db.Query()

The core class that enables you to define and execute queries. The constructor takes a configuration object as parameter. As can be seen in the following example, running a query basically consists of two steps: 1) define a query incl. its aggregations, selections and/or group bys and 2) execute or open that query. Each query has to have at least one groupBy and at least one aggregation.:

// first, define the query.
var query = new Xplain.Db.Query({
                                      groupBy:  {
                              attribute: "Patient.Gender.Gender"
                              },
                    aggregation: {
                        type: 'AVG',
                        measure: 'Patient.Age'
                    }
});

// now execute the query
query.execute({
    success: function(d) {
        // d is an instance of Xplain.Db.QueryData
        console.log('Query successful');
        console.log(JSON.stringify(d.getData()));
    }
});

This example executes the query defined. Beside executing a query, you may also open a query. The difference between executing a query and opening it is that opening a query a) runs that query b) returns the resulting data and c) leaves that query opened. In contrast to this executing a query will a) run that query b) return the resulting data and c) close that query. Thus, an opened query stays opened until you manually close it by calling the close method.

If, like in the example above, no selection has been set, the selectionSet will be set to globalSelections.

Example using open():

// first, define two queries
var query1 = new Xplain.Db.Query({
                                      groupBy:  {
                              attribute: "Patient.Gender.Gender"
                              },
                    aggregation: {
                        type: 'AVG',
                        measure: 'Patient.Age'
                    }
});
var query2 = new Xplain.Db.Query({
                                      groupBy:  {
                              attribute: "Patient.Gender.Gender"
                              },
                    aggregation: {
                        type: 'AVG',
                        measure: 'Patient.Age'
                    },
                    selection: {
                        attribute: 'Patient.EGK.EGK',
                        selectedStates: ['1']
                    }
});

// open query1 and show resulting data
query1.execute({
    success: function(d) {
        console.log(JSON.stringify(d.getData());

        // execute query2. The selection defined in query2 will also change
        // the resulting data fo query1 !
        query2.execute({
            success: function(d) {

                 // show result for query1 and query2
                 console.log(JSON.stringify(d.getData());
                 console.log(JSON.stringify(query1.getResult().getData());

                 // and close both queries
                 query1.close();
                 query2.close();
            }
        });
    }
});

addAggregation

addAggregation(v)

Add an aggregation to this query.

Note: this method will change any resulting data, i.e. it will not fetch any results from the backend. Use open or execute to (re-)fetch data from the backend.

Parameters: v (object, Xplain.Db.Aggregation) – The aggregation object
Returns: this instance

addAggregations

addAggregations(v)

Aggregations may either be defined in the constructor of this query class or they may be set later on using this method. In contrast to setAggregations the addAggregations method will not delete old aggregations but add the new set of aggregations.

Note: this method will change any resulting data, i.e. it will not fetch any results from the backend. Use open or execute to (re-)fetch data from the backend.

Parameters: v (object, array, Xplain.Db.Aggregation) – The aggregation object
Returns: this instance

addGroupBy

addGroupBy(v)

add a groupBy to this query.

Parameters: v (object, Xplain.Db.GroupBy) – The GroupBy object
Returns: this instance

addGroupBys

addGroupBys(The)

groupBys may either be defined in the constructor of this ‘query’ class or it may be added later on using this method. In contrast to setGroupBys the addGroupBys method will not delete old groupBys but add the new set of groupBys.

Note: this method will change any resulting data, i.e. it will not fetch any results from the backend. Use open or execute to (re-)fetch data from the backend.

Parameters: The (object, array, Xplain.Db.GroupBy) – GroupBy object or an array of GroupBy objects

addSelection

addSelection(v)

Add a selection to this query. Note: selections may only be applied to queries which later on will be conducted using the execute() method (and __NOT__ the open() method). ATTENTION: using such a “local” selection will always have a higher priority than a conflicting global selection (see method select in Xplain.Db.Session).

Parameters: v (object, Xplain.Db.Selection) – The selection object
Returns: this instance

close

close([settings])

Closes this query on the backend. The status of this query will be set to “closed”.

Parameters

(optional) (function settings.error=f(data){throw new Xplain.Db.Exception}) – A set of key/value pairs that configure the close request. All settings are optional. A default can be set using the Xplain.Db.Configuration.setDefaults() method.
(optional) – defines if the request sent to the backend should be asynchronous or synchronous.
(optional) – defines if the request should support CORS (note: the backend also has to enable CORS requests).
(optional) – Number of milliseconds until a timeout will be triggered.
(optional) – Function what will be triggered if the Xplain Data backend reports an HTTP Status Code 200. The first parameter passed to this function will be an instance of Xplain.Db.QueryData
(optional) – Function what will be triggered if the Xplain Data backend reports anything but a HTTP Status Code 200. The first parameter passed to this function will be an instance of the data returned by the backend.

Returns

{null|Xplain.Db.QueryData} if async=false, this method will return an instance of Xplain.Db.QueryData. If async=true, use the first parameter passed to the success function or use the this.getResult() method of this class.

execute

execute([settings])

Executes this query. The status of this query will be set to “executed”.

Parameters

(optional) (function settings.error=f(data){throw new Xplain.Db.Exception}) – A set of key/value pairs that configure the execute request. All settings are optional. A default can be set using the Xplain.Db.Configuration.setDefaults() method.
(optional) – the syncType used during the request. One of: “parallel” (executed immediately without any synchronisation), “queued” (put into queue), “single” (put into queue, simultaneously no other call of type single may be in queue or currently processed) and “block” (put into queue, any further call which comes in while a block call exists will be rejected with a exception)
(optional) – defines if the request sent to the backend should be asynchronous or synchronous.
(optional) – defines if the request should support CORS (note: the backend also has to enable CORS requests).
(optional) – The URL used for this request.
(optional) – number of milliseconds until a timeout will be triggered.
(optional) – function what will be triggered if the Xplain Data backend reports an HTTP Status Code 200. The first parameter passed to this function will be an instance of Xplain.Db.QueryData
(optional) – function what will be triggered if the Xplain Data backend reports anything but a HTTP Status Code 200. The first parameter passed to this function will be an instance of the data returned by the backend.

Returns

{null|Xplain.Db.QueryData} if async=false, this method will return an instance of Xplain.Db.QueryData. If async=true, use the first parameter passed to the success function or use the ``this.getResult() method of this class.

getAggregations

getAggregations()

returns an array of aggregations for this query, i.e. an array of Xplain.Db.Aggregations instances.

Returns: {Array} array of Xplain.Db.Aggregations instances

getGroupBys

getGroupBys()

returns an array of group-bys for this query

Returns: {Xplain.Db.GroupBys}

getId

getId()

return the ID of this query

Returns: ID {string}

getMeasures

getMeasures()

After this query has been opened / executed, this method returns an array of all measures for this query. Each measure is represented as an object that consists of:

name: the name of the measure, e.g. SUM(Costs)

type: the type of the aggregation of this measure, e.g. SUM

measure: the object / dimension / attribute of the aggregation of this measure in dot-notation, e.g. Patient.Costs.Costs

Returns: {Array|boolean} An array of objects or false if the query hasn’t been executed / opened yet.

getRawData

getRawData()

returns the result this query as returned by the backend. If no result exists for this query, boolean false will be returned.

Returns: {object} JSON representation of this query as returned by the backend

getResult

getResult()

returns the result this query produced, i.e. an instance of Xplain.Db.QueryData. If no result exists for this query, boolean false will be returned.

Returns: {object|boolean} an instance of Xplain.Db.QueryData

getSelectionSet

getSelectionSet()

returns the selection set of this query

Returns: {string} the selection set of this query

getSelections

getSelections()

returns an array of all local selections (a.k.a. “fixed” selections) for this query, i.e. an array of Xplain.Db.Selections instances. Note that this method does NOT return the global selections (a.k.a. “floating” selections). To get all global selections use the getSelections method of the Xplain.Db.Session class.

Returns: {Array} array of Xplain.Db.Selections instances

getStatus

getStatus()

returns the status of this query (initialized, opened, executed, closed)

Returns: {string} the status of this query

includesUpperLevels

includesUpperLevels()

Checks if all groupyBys used in this query are set to includeUpperLevels == true. If so, this method returns true. Otherwise it returns false

Returns: {boolean} returns true if all groupyBys are set to includeUpperLevels == true

open

open([settings])

Opens this query. In contrast to this.execute() this method will run the corresponding query but keep it opened on the server. Thus, selections later set will influence the result of this query. Use this.close() to close this query later on. The status of this query will be set to “opened”.

If you open a query that already has been opened, the query will be re-submited to the backend, i.e. it will be refreshed. This makes sense if you alter the structure of a query, e.g. add a new aggregation, remove a groupBy, etc. The same happens if you open a query whose ID is already assigned.

Parameters

(optional) (function settings.error=f(data){throw new Xplain.Db.Exception}) – A set of key/value pairs that configure the open request. All settings are optional. A default can be set using the Xplain.Db.Configuration.setDefaults() method.
(optional) – the syncType used during the request. One of: “parallel” (executed immediately without any synchronisation), “queued” (put into queue), “single” (put into queue, simultaneously no other call of type single may be in queue or currently processed) and “block” (put into queue, any further call which comes in while a block call exists will be rejected with a exception)
(optional) – defines if the request sent to the backend should be asynchronous or synchronous.
(optional) – defines if the request should support CORS (note: the backend also has to enable CORS requests).
(optional) – The URL used for this request.
(optional) – number of milliseconds until a timeout will be triggered.
(optional) – function what will be triggered if the Xplain Data backend reports an HTTP Status Code 200. The first parameter passed to this function will be an instance of Xplain.Db.QueryData
(optional) – function what will be triggered if the Xplain Data backend reports anything but a HTTP Status Code 200. The first parameter passed to this function will be an instance of the data returned by the backend.

Returns

{null|Xplain.Db.QueryData} if async=false, this method will return an instance of Xplain.Db.QueryData. If async=true, use the first parameter passed to the success function or use the this.getResult() method of this class.

setAggregations

setAggregations(v)

Aggregations may either be defined in the constructor of this query class or they may be set later on using this method. In contrast to addAggregations the setAggregations method will delete old aggregations.

Note: this method will change any resulting data, i.e. it will not fetch any results from the backend. Use open or execute to (re-)fetch data from the backend.

Parameters: v (object, array, Xplain.Db.Aggregation) – The aggregation object or an array of Aggregation objects

setGroupBys

setGroupBys(The)

groupBys may either be defined in the constructor of this ‘query’ class or it may be set later on using this method. In contrast to addGroupBys the setGroupBys method will delete old groupBys.

Note: this method will change any resulting data, i.e. it will not fetch any results from the backend. Use open or execute to (re-)fetch data from the backend.

Parameters: The (object, array, Xplain.Db.GroupBy) – GroupBy object or an array of GroupBy objects

setId

setId(_id)

set the ID of this query. The ID can only be changed, when the status of this query is ‘initialized’

Parameters: _id (string) – New string of this query
Returns: this instance

setSelectionSet

setSelectionSet(selset)

before opening a query, you may want to set the selectionSet which should be used. Note: this only works for queries which you will a) open (not execute) and b) which are NOT YET openend.

Parameters: selset (string) – The name of the selection set which should be used
Returns: this instance

setSelections

setSelections(v)

Selections may either be defined in the constructor of this query or they may be set later on using this method. Note: selections may only be applied to queries which later on will be conducted using the execute() method (and __NOT__ the open() method). ATTENTION: using such a “local” selection will always have a higher priority than a conflicting global selection (see method select in Xplain.Db.Session).

Parameters: v (object, array, Xplain.Db.Selection) – The selection object or an array of selections
Returns: this instance

toJson

toJson(m)

returns a JSON representation of this query.

Parameters: m (string) – If given, this will be the method used in the JSON representation.
Returns: {object} this query as plain JSON object.

toString

toString([beautify])

returns this query in string format. This is sometimes useful to debug your application.

Parameters: (optional) (boolean beautify) – If true, the string will be beautified. Defaults to false
Returns: {string} this query as a string.