Use a Data Query

This applies to: Visual Data Discovery

The Symphony JavaScript client library provides functions to query the Symphony server for data. This guide uses a method that does not provide event handling for the queries. To assist you in querying for data without handling events, Symphony provides:

This topic, which includes annotated steps for using a query in your own web app.
A simple example of a query used to render a table, with annotated code, discussed in this topic, and available for download at the Developer Zone.

For information about the structure of the query configuration object, see Query Configuration Object.

How a Query Works

The Symphony object is used to create a Symphony client object. This client is then used to create a query object. To run the query, you pass it and a data processing function to client.runQuery(). The client.runQuery() function retrieves data and passes it to the data processing function.

Steps for Using a Query in Your Web App

These high-level steps for using a query in a web application will guide your work.

Link Dependencies
Organize Application and Security Parameters
Configure the Query
Code the Query
Run the Query
Find Your Data

Link Dependencies

Using Symphony data queries depends on the zoomdata-client.js library. You can link to this library on your Symphony server at composer/sdk/zoomdata-client.js.

The application framework and example code used in this topic also depend on jQuery (jQuery.js). Symphony recommends that you link jQuery v1.8 or later. Your script must have access to this library to use the example.

Organize Application and Security Parameters

Connecting the webpage to your Symphony server requires supplying the Symphony server with application and security parameters in the form of JavaScript objects. These two objects are themselves bundled together as a single object to be passed to the createClient() method. For example:

ZoomdataSDK.createClient({
	credentials: credentialConfig,
	application: applicationConfig
})

For more information about the application configuration object, see Application Configuration Object.

For more information about the security configuration object, see Data Discovery Security Configuration Object.

Configure the Query

Before you can create a query, you must create a query configuration object. This object is used to create a query using the Symphony client's member function createQuery(). For example, the query configuration object below gathers from its data source up to 200 productGroup items, sorting them in ascending order and measuring them by their average price, filtering out any groups whose average price is not less than 100.

var queryConfig = {
	tz: 'EST',
	time: { timeField: '_ts' },
	player: {},
	filters: [{ path: 'price', operation: 'LT', value: 100 }],
	groups: [{
		name: 'productGroup',
		limit: 200,
		sort: { dir: 'asc', name: 'productGroup' }
	}, {
		name: 'productCategory',
		limit: 200,
		sort: {dir: 'asc', name: 'productCategory'}
	}],
	metrics: [{
		name: 'price',
		func: 'avg' }]
};

Code the Query

The createClient() and runQuery() functions are used to create and run a query. The runQuery() function returns a promise, so you can chain then() and done() functions to it.

To code a query:

Instantiate a Symphony client if you do not already have one that you want to use.

ZoomdataSDK.createClient({ credentials: credentialConfig, application: applicationConfig }).then((client) => { // where client is the newly created instance of the client });
Use the client’s createQuery() method to create the query. The required parameters are a data source available to the client (based on the server it accesses and its permissions) and a query configuration object.

client.createQuery({name: 'Real Time Sales'}, queryConfig).then((queryInstance) => { // resulting queryInstance can be used to query for data from the data source });

Run the Query

The Symphony client library offers different ways to run the query to gather data. This tutorial uses the client.runQuery() method, which applies a function to each data object resulting from the query. There is also a client.run() method, which returns a thread that contains both the data and other messages that are useful for working with data.

To run a query with client.runQuery():

Supply runQuery() with these parameters:
1. a query, which you can create using the steps found in Coding a Query
2. a function to execute on each object resulting from the query, which should take one parameter
client.runQuery( theQuery, function( dataObject ) { console.log( 'Data object returned by query: ', dataObject ); });
Typically, you should chain a .catch() function to handle errors after the event handling function

.catch( function( theError ) { console.log( 'Error: ', theError ); });

The function runQuery() extracts a data object, rather than a single piece of data, from your query and passes it to your data processing function. For more information about finding the data you need in the returned data object, see Find Your Data.

Full Example

ZoomdataSDK.createClient({
	credentials: credentialConfig,
	application: applicationConfig })
.then(client => {
       client.createQuery({name: 'Real Time Sales'}, queryConfig)
              .then(query => {
                    client.runQuery( query, function( dataObject ) {
				// dataObject contains array of data from back end responses. 
				console.log( 'Data object returned by query: ', dataObject );
                     });
             })
})
});

Find Your Data

The runQuery() function returns a data object or more commonly an array of data objects. These objects each have the same structure, which can be predicted by the query configuration and also discovered programmatically.

Structure of the Data Object

Each data object consists of the following objects:

current : an object that contains a count value and a metrics object
- count : indicates the number of rows of data represented in the data object
- metrics : contains one object for each metric
  current: count: 131 metrics: revenue: avg: $23.32 profit: avg: $13.16
  - individual metric objects contain a key:value pair. The key is the operation of the metric, such as 'avg' or 'min'. The value is the metric value, for example:
  - The current object above indicates that 131 rows of data are in the queried group, and have an average revenue of $23.32 and average profit of $13.16
group : an array listing the groups aggregated in the data object
- for example
  group: 0: 'Gaithersburg' 1: 'Coffee'
  The groups object above represents rows of data that satisfy both grouping requirements: 'Gaithersburg' and 'Coffee', which, depending on the data set, may represent sales of coffee in Gaithersburg.

Isolate a Piece of Data Manually

If you know the structure of the query in advance, you can reliably anticipate the structure of the data object. The query returns metrics, groups, and fields in the order they are found in the query object.

To verify the order, use a console.log() statement to output to the debugging console a sample data object returned by the query.

Individual elements of the data object can be isolated and used as a JavaScript object. For example, to access the average price in the data object above, use either of the following expressions.

theDataObject.current.metrics.price.avg

theDataObject['current']['metrics']['price']['avg']

Isolate a Piece of Data Programmatically

You will not always know in advance which metrics, groups, and fields are involved in a data structure. The Query API provides accessor functions to identify programmatically the metrics, groups, and fields involved in a query. These functions are useful in the event that a query is subject to change at runtime. These accessors include:

query['metrics'].get()
query['groups'].get()
query['fields'].get()

Each of the accessors above returns an array of objects with one object for each metric, group, or field, respectively. These objects are structured as they are structured in the query configuration object. For more information about query configuration objects, see Query Configuration Object. In the event that there are no metrics, groups, or fields in the query, that particular accessor will return an empty array.

Using the accessors, you can use the following steps to programmatically iterate through the metrics, groups, or fields used by your data query.

Create an array with the names of metrics, groups, or fields
Use the array to iterate through the returned data objects

Each of these steps is described below in more detail.

To create an array with the names of metrics, groups, or fields:

These steps use metrics as an example. You can also use groups or fields with the same procedure by replacing metrics with groups or fields.

Call query['metrics'].get() and assign the returned array to a variable.

var metrics = query['metrics'].get();
Iterate through the returned array using its forEach() method. Pass to forEach() an anonymous function to extract the name of each metric and add it to an array of the purpose of storing only the names of metrics.

var metricNames = []; metrics.forEach( function(metric) { metricNames.push( metric.name ); });

These steps combined produce an array containing only the names of the metric objects, in the same order that they appear in both the returned metric object list and in the query configuration object.

To use the array to iterate through the returned data objects: