Zoomdata Version

Query Configuration Object

Overview

The query configuration is contained in a JSON object including specific key:value pairs. You do not need to include unused keys. The exceptions are:

  • the time key, which must specify a timeField value if a player is to be used by the query
  • you must use one and only one of the following keys: fields, groups, and dimensions. Using none or more than one of these keys results in an error. The dimensions key is available starting with Zoomdata 2.4.

Additionally, if you use the query configuration object to create a query that is then used to supply data to an embedded chart, it must have the following keys:

  • filters, though it can be defined as [] if you do not want to apply any filter
  • metrics, without which the chart will not have data to present

Example

var yourConfigObject = {
tz: 'UTC',                             //time zone
time: {
   timeField: '_ts',                   //table field used for time
   from: '+2016-10-23 22:30:15.5',     //start and finish time
   to: '-2016-11-23 22:30:15.5' 
   },                         //format: {+/-}YYYY-MM-DD HH:mm:ss.SSS
player: {
   speed: 1,                          //rate of querying, in sec.
   pauseAfterRead: false,             // boolean
   timeWindowScale: 'ROLLING'         // or 'PINNED'
   },
filters: [
   {path: 'usersentiment', operation: 'BETWEEN', value: [-0.5, 0.5]},
   {path: 'color', operation: 'IN', value: [‘red’, 'green', 'blue']},
   {path: 'age', operation: 'LT', value: 21},
   {path: 'color', operation: 'NOTIN', value: ['red', 'green', 'blue']}
   ],
groups: [
   {name:'usercity', limit: 200, sort:{dir: 'asc', name: 'usercity'}},
   {name:'department', limit: 10, sort:{dir: 'desc', name: 'sales' }}
   ],
fields: [
   {name: 'price', limit:50},
   {name: 'usercity', limit: 50}
   ],
metrics: [
   {name:'price', func:'avg'},
   {name:'count', func:'sum'}
   ]
};

Each possible parameter is described below.

tz: ''

Sets the timezone used by the web app. Use ISO standard abbreviations. The value defaults to the Zoomdata server time.

Back to top

time: {}

A time object, which specifies the time range to be included in the query. Essentially, this parameter filters the query based on time using the timefield, from, and to elements.

key usage notes examples
timeField String. Sets the field to be used as the time measurement. This field refers to the data source columns containing the time measurement, rather than any label that appears in the user interface.  
from String. Sets the earliest time from which data should be included in the query.  Use the format [-/+]YYYY-MM-DD HH:mm:ss.SSS (preceded by a + or - to include or exclude the specified time). +2015-10-23 10:30:15.500 to start at 23 October 2015 10:30:15.5, inclusive
to String. sets the latest time to which data should be included in the query. Use the format [-/+]YYYY-MM-DD HH:mm:ss.SSS  (preceded by a + or - to include or exclude the specified time). -2016-01-10 10:30:15.500 to start at 10 January 2016 10:30:15.5, exclusive

Back to top

player: {}

A player object, which specifies parameters for retrieving data from a source. It consists of the speed, pauseAfterRead, and timeWindowScale elements. If you include a player object in the query, you must also include a time object that includes at least the timeField element.

key usage notes examples
speed Integer. Sets the interval at which data should be retrieved, in seconds. Accepted values are: 1 (every second), 60 (every minute), 3600 (every hour), and 86400 (daily). 60
pauseAfterRead Boolean. Sets whether the data stream, if applicable, should be paused after initial retrieval. data set empty message may result when pauseAfterRead is set to false with a non-live data source. true
timeWindowScale String. 'ROLLING' or 'PINNED'. Sets whether the time interval of retrieved data “rolls” or stays “pinned” to its original starting point (the from element of the time object). The retrieval of a rolling time window starts at the point where the last retrieval finished. The retrieval of a pinned time window always starts at the same point, which is provided by the from element. The image below shows rolling time windows above the timeline, and pinned windows beneath it.

'ROLLING'

'PINNED'

Back to top

filters: [{},{}]

Array of filter objects. Filter objects are applied to the data query using logical-and operations so that data is passed from the data query only if it satisfies all applied filters. Each filter consists of a path, an operation, and a value.

key usage notes examples
path String. The name of the group or metric on which the filter operates. This name is that of the data source column containing the group or metric of the filter, rather than the label that appears in the user interface. customer_gender

customer_age

user_occupation
operation String. The logical operator used by the filter. Valid options include the following:
logical operationkey value
<'LT'
<='LE'
=='EQUALS' (case sensitive)
=='EQUALSI' (case insensitive)
>='GE'
>'GT'
in a set'IN'
not in a set'NOTIN'
between two values'BETWEEN'
!='NOTEQUALS'
text search'TEXT_SEARCH'
filter-level AND'AND'
filter-level OR'OR'

 

'EQUALSI'

'BETWEEN'

'NOTIN'
value Single value or array of values. The value(s) considered by the logical operation. If two or more values are needed, such as for a logical set or for a ‘BETWEEN’ operation, they should be provided in an array.

Single values, such as required for an ‘EQUALS’ or ‘LT’ operation, should be provided as simple values.
'female'

[21,65]

['teacher','lawyer',
'plumber']

Back to top

groups: [{},{}]

Array of group objects. Group objects specify which data is returned by a query and how it is grouped. Each group object has a name, limit, and a sort object.

If groups is defined, fields and dimensions must be omitted.
key usage notes examples
name String. The name of the attribute to be used for grouping data. This name is the name of the data source column containing the attribute, rather than the label that appears in the user interface. 'home_state'
limit The maximum number of distinct items to be included in the data set. If the limit is set lower than the total number of items in a group, not all members of the group will be included in the returned data set. For example, if the limit is set to 25, then the group us_state could not return data from all fifty US states. 50
sort A sort object. See below.   {dir: 'desc',
name: 'home_state'}

Back to top

sort: {}

A sort object. Sort objects describe the way in which a group is ordered. Each sort object consists of the name of the group or metric for the sorting and the direction in which the group’s data is sorted.

key usage notes examples
name String. The name of the group or metric on which the filter operates. This name is that of the data source column containing the group or metric by which groups are to be sorted, rather than the label that appears in the user interface. 'home_state'
dir String. The direction of the sorting. Valid options are 'asc' and 'desc' for ascending and descending sorts, respectively. 'asc'

Back to top

Array of group objects. Group objects specify which data is returned by a query and how it is grouped. Each group object has a name, limit, and a sort object.

fields: [{},{}]

Array of field objects. A field object is used to take a whole column of data without grouping it by the items found in the column. Each field object consists of the name of a column.

If fields is defined, groups and dimensions must be omitted.
key usage notes examples
name String. This name is that of the data source column containing the field. 'home_state'
limit Integer The maximum number of records to report.  50

Back to top

metrics: [{},{}]

Array of metric objects. Each metric object indicates a column to be returned and used by the data query as a metric. Each metric object can have a name and function.

key usage notes examples
name String. The name of the metric. This name is that of the data source column containing the metric, rather than the label that appears in the user interface. 'user_age'
function String. Determines the function applied to the metric. Valid options include the following:

'min', 'max', 'avg', 'sum', 'calc', 'distinct_count', 'last_value', 'percentiles'
'avg'

Back to top