Class: DataQuery

data. DataQuery

A DataQuery is used to facilitate in the retrieval of a DataSet from the linked web service.

A DataQuery can be created from a Dataflow by calling the dataflow.createDataQuery() method, alternatively a DataQuery can be created using the new Operator, and calling the setDataflow method to initialise the state.

The DataQuery can be told to store the state of the DataQuery on the URL by calling storeStateOnUrl method passing in true.

The DataQuery provides access to the underlying Dataflow and Data Structure.

In addition the DataQuery can also be used to load DataQueryMetadata using the DataQuery.loadDataQueryMetadata() method. DataQueryMetadata provides stateful information about what data exists in the context of the Dataflow. And as such can be used to help a user construct a meaningful query which does not result in No Data.

alt text


new DataQuery()

Examples

Creating a Query and executing the query against the Server

function createQuery() {
  //Create a Data Query - do not store the state of the Query on the URL
	 dataflow.createDataQuery(false, onCreateQueryResponse);
}

function onCreateQueryResponse(dataQuery) {
  //Add query filters and execute the query on the server
  dataQuery.addCodeSelection("FREQ", "A");
  dataQuery.addCodeSelection("REF_AREA", "UK");
  dataQuery.executeQuery(null, onDataQueryResponse); 
}

Load a DataQueryMetadata to help build a Code Picker

function createQuery() {
  //Create a Data Query - do not store the state of the Query on the URL
	 dataflow.createDataQuery(false, onCreateQueryResponse);
}

function onCreateQueryResponse(dataQuery) {
  dataQuery.loadDataQueryMetadata(onMetadataLoad)
}

function onMetadataLoad(dataQueryMetadata) {
  var seriesCount = dataQueryMetadata.getValidSeriesCount();
  var obsCount = dataQueryMetadata.getValidObsCount();
  var reportingBegin = dataQueryMetadata.getReportingBegin();
  var reportingEnd = dataQueryMetadata.getReportingEnd();
  dataQueryMetadata.addCodeSelectionStateChangeListener(onCodeSelection);  //Call a function when the user selects/deselects a code
  dataQueryMetadata.addCodeDataStateChangeListener(onCodeStateChange);  //Call a function when a code becomes an invalid/valid choice due to other selections
  dataQueryMetadata.addUpdateMetadataCompleteListener(onMetadataUpdate); //Call a function on completion of updating the metadata information
  
  //Use the dataQueryMetadata Dimension and Codes to help build a Checkbox Code picker
}

Methods


addCodeSelection(dimId, codeId)

Adds a code for selection for the Dimension with the given id

Parameters:
Name Type Description
dimId string

the dimension id

codeId string

the code id


addDataQueryCallback(callback)

Adds a callback listener to be called on completion of a $executeQuery() method.

The callback function should take the DataSet as its argument

Parameters:
Name Type Description
callback function

function to be called with DataSet obtained from the server

See:
Example
function addCallbackFunctions() {
  dataQuery.addDataQueryCallback(onDataQueryResponse1);
  dataQuery.addDataQueryCallback(onDataQueryResponse2);
}

function runQuery() {
  dataQuery.executeQuery();  //Do not need to pass in callback function, as we have registered one against the data query
}

function onDataQueryResponse1(dataset) {
  //Do something
}

function onDataQueryResponse2(dataset) {
  //Do something else
}

clearAllSelections()

Clears all previous code selections and series selections


clearCodeSelections(dimId)

Clears the code selections for the given dimension

Parameters:
Name Type Description
dimId string

the Dimension Id


executeQuery(additional, callback)

Obtains a DataSet from the linked service based on the query parameters, this DataSet is passed to the callback function

Parameters:
Name Type Description
additional Object

query parameters example { "format" : "sdmx-json", "detail" : "full" }

callback function

function to be called with returned $DataSet


getCodeSelections(dimId)

Returns an Array of code selections for the given dimension, or an empty array if non exist

Parameters:
Name Type Description
dimId string

the Dimension Id

Returns:

array of code ids for the given dimension or undefined/null if none exist

Type
Array.<string>

getCountSelections()

Returns a count of all the code selections for all the dimensions

Returns:
Type
number

getDataflow()

Returns the ${bean.datastructure.DataflowBean|Dataflow} for which this DataQuery is for

Returns:
Type
bean.datastructure.DataflowBean

getDataQueryFilterString()

Returns part of the SDMX web service query String representing the code selections and query parameters used to define restrictions on data (startPeriod,endPeriod, lastNObservations, firstNObservations).

Returns:

Example: A.UK+FR+..LLP.. if nothing has been selected returns all

Type
string

getDataQueryMetadata()

Returns data.DataQueryMetadata.

Note: loadDataQueryMetadata() should first be called otherwise this function will return null

Returns:

data.DataQueryMetadata


getDataQueryString(additional)

Returns a REST data query string based on the selected codes.

Parameters:
Name Type Description
additional Object

parameters example { "format" : "sdmx-json", "detail" : "full" }

Returns:

example data/BIS,EER,1.0/A.B...?startPeriod=2010

Type
string

getDataStructure()

Returns the Data Structure for which this DataQuery is for

Returns:
Type
bean.datastructure.DataStructureBean

getDateFrom()

Returns the selected start date as ISO8601 String, or null if there is not one selected

Returns:
Type
string

getDateTo()

Returns the selected end date as an ISO String, or null if there is not one selected

Returns:
Type
string

getLastN()

Returns the last N observations selected in the data query, or null if this is not set

Returns:
Type
number

hasCodeSelections(dimId)

Returns true if the dimension has at least one code selection for it

Parameters:
Name Type Description
dimId string

the Dimension Id

Returns:
Type
boolean

hasDateFrom()

Returns true if a date from has been selected in the query

Returns:
Type
boolean

hasDateTo()

Returns true if a date to has been selected in the query

Returns:
Type
boolean

hasLastN()

Returns true if the selection has 'last N' observations set

Returns:
Type
boolean

loadDataQueryMetadata(callback)

Loads data.DataQueryMetadata which can be used to help build a data query

Parameters:
Name Type Description
callback function

function to be called with loaded data.DataQueryMetadata


removeCodeSelection(dimId, codeId)

Removes a code for selection against the Dimension with the given id

Parameters:
Name Type Description
dimId string

the dimension id

codeId string

the code id


setDataflow(dataflow, callback)

Sets the Dataflow for this DataQuery, this will load the associated DataStructure from the server which will be accessible via the getDataStructure() method.

The callback function is called when the DataStructure has been loaded

Parameters:
Name Type Description
dataflow bean.datastructure.DataflowBean
callback function

function, on completion of set


setDataProviderId(id)

Sets the data provider id for this query

Parameters:
Name Type Description
id string

the data provider id


setDateFrom(dateFrom)

Sets the first observation date (inclusive) for the data query

Parameters:
Name Type Description
dateFrom object

this can be a JavaScript date or a ISO8601 String


setDateTo(dateFrom)

Sets the last observation date (inclusive) for the data query

Parameters:
Name Type Description
dateFrom object

this can be a JavaScript date or a ISO8601 String


setLastN(lastN)

Sets the 'last N' observations to be bought back from the data query, if this is set, then the date range will be removed from the query

Parameters:
Name Type Description
lastN number

defines the last 'n' observations to be bought back for each series which matches the query selection


setProvision(provision)

Sets the Provision Agreement for this query

Parameters:
Name Type Description
provision bean.datastructure.ProvisionAgreementBean

the provision agreement


storeStateOnUrl(store)

Sets a true/false value of whether to store data query selection and parameter state on the URL of the web browser. The state is stored after the # on the URL so updating this value does
not force a page refresh. The state is stored in a parameter called 'dq' and is terminated by a ';' for example http://myserver.com/mypage.html#dq=A.B.C?lastNObservations=12;

If this is set to true, the state of this DataQuery is also populated by reading the value of the same dq parameter from the URL (if it is present)

Parameters:
Name Type Description
store boolean

state