Zoomdata Version

Visualization Variable Descriptions (v2.2 GA)


Zoomdata uses default values provided in a data source configuration to determine how that data source displays a particular chart. Each variable required by the chart, such as "X Axis" or "Group by", is provided its default value which is recorded in an object in the source configuration. These variables point to fields in the data source so that, for instance, "Y Axis" might draw its values from the field "sales_price". When embedding a visualization in a chart, you can provide it with a variables key, the value of which lists the chart's variables and the settings that you want for them.

This topic is a reference that explains the syntax of each type of variable description. For information about using these variable descriptions to override a chart's default settings, see Configuring Charts Via Visualization Variables (v2.2 GA) . For information about embedding a chart in a custom web application, see Embedding a Visualization (Chart) in a Web App .

Example of a Variables Key and Value

Here is an example of a variables object for the Packed Bubbles chart.

variables: {
'Bubble Size': 'count',
'Chart Name': '',
'Bubble Color': 'price:avg:{"autoShowColorLegend":true}',
'Chart Description': '',
'Group By': '{ "name":"usergender", "limit":20, "sort": {"name": "count", "dir": "desc"} }'

In the example above, there are some important features described in the following notes.

Notes about the example object

'Bubble Size': 'count',
  • The count metric is a system metric provided by Zoomdata. Its default UI label is "Volume". This metric does not require or accept function.
'Chart Name': '',
  • Chart Name is an example of an optional constant. It can be left null.
'Bubble Color': 'price:avg:{"autoShowColorLegend":true}',
  • Bubble Color , above, is an example of a metric variable used to control a chart's colors. The stringified value is not a standard JSON object.
    • price is the field (column) from the data source used as the metric value.
    • avg is the function applied to the metric value. Available functions are listed in Available Metric Functions (v2.2) .
    • {"autoShowColorLegend":true} is an example of a color-control object. Color-control objects have two roles.
      • They control the assignment of colors to the elements of a chart.
      • They control the display of labels, legends, and so forth in the Zoomdata client application . These parts of a color control object do not affect the embedding of a chart in your custom application.
    • If you omit the color-control object, also omit the second colon (:) in the string.
    • If the metric is count , which does not accept or require a function, omit the function and simply use two colons ( :: ) to separate count from the color-control object if there is a color-control object, for example:
      'Color Metric' : 'count::{"colorSet":"ZoomSequential"}'
'Group By': '{ "name":"usergender", "limit":20, "sort": {"name": "count", "dir": "desc"} }'

Description of Each Chart Variable Type

Zoomdata's Embedding API supports the following types of chart variables.

The JSON objects that describe them are subject to change and they should be considered part of Zoomdata's internal APIs. For more information about using internal APIs, see Cautionary Note About Internal APIs .

For an explanation of how to use the chart variables described below to configure an embedded visualization, see Configuring Charts Via Visualization Variables (v2.2 GA) .

Grouped query

Used for making aggregated group-bys from a field (column of data). The grouped query variable's description follows the same format as a group in the Query Configuration Object .

'Buying Demographic': '{ "name":"usergender", "limit":20, "sort": {"name":"count","dir":"desc"} }'


  • Buying Demographic is the name of the grouped query
  • name indicates the fieldID of the group.
  • limit indicates the maximum number of groups to be aggregated
  • sort contains another simple object
    • name indicates the fieldID to be used for sorting the groups
    • dir indicates the direction of sorting, either
      • asc for ascending order
      • desc for descending order


Provides multiple levels of grouping under a single header. A multi-group variable is stringified array of grouped queries. Each of the listed groups is described like a group in the Query Configuration Object .

'Multi Group By': '[ {"name":"usergender", "limit":50, "sort":{"name":"count","dir":"desc"}}, {"name":"group", "limit":20, "sort": {"name":"count","dir":"desc"}} ]'

For a description of the elements the array, see the description of a Grouped query .

Histogram group

The histrogram group variable type provides a breakdown of metric values by segments, or bins, for example, incomes from $0 to $10000, $10001 to $30000, $30001 to $55000, and so forth. The histogram group is only supported by data sources that also support histogram charts.

'Bins Color': '#1f78b4',
'Cumulative Line Color': '#ff7f00',
'Chart Name': '',
'Chart Description': '',
'Group By': '{ "binsType":"auto","binsCount":10,"binsWidth":100,"values":"absolute","cumulative":false,"name":"datenumberpattern"}" }'


  • Bins Color is a constant value
  • Cumulative Line Color is a constant value
  • Chart Name is a constant value
  • Chart Description is a constant value
  • Group By is a histogram group object. This object is not used elsewhere in Zoomdata and it specifies the properties of the distribution "bins" into which metric values are gathered.


Provides a measurement of some aggregation. Metric variables require the name of the field (column) of the data source that provides the values for that chart variable, together with the function applied to the values. For example:

"Transaction Value": "saleprice:avg"


  • Transaction Value is the name of the metric variable
  • saleprice is the name of the field (column) holding the data for the variable
  • avg is the function applied to the metric. In this case, as Transaction Value data is grouped, the average saleprice will be queried.

For a list of available metric functions, see Available Metric Functions (v2.2) .


Provides a group of measurements under a single header. Multi-metric variables require a space-separated list of the field names (columns) from the data source that provide the values for that chart variable, together with the function applied to the values, separated by colon. For example:

"Model Stats": "costperunit:avg priceperunit:avg sales:sum"


  • Model Stats is the name of the multi-metric variable.
    • costperunit , priceperunit , and sales are each the name of a field (column) containing a metric value in the data source.
    • avg and sum are the functions applied to those metrics so that costperunit and priceperunit are of those values and sales is a sum total of its values. 9

Box plot metric

Provides data in a bundled package suitable for the high-performance rendering of box plot diagrams. The box plot metric variable is only supported by data sources that also support box plot charts.

'Metric': '{"name":"datenumberpattern","func":"percentiles","args":[0,25,50,75,100]}',
'Group By': '{"name":"gender","limit":50,"sort":{"dir":"desc","name":"count"}}'


  • Metric is a metric object (see Query Configuration Object ) with an additional key, args , which specifies the box plot's distribution boundaries, given in percentiles. For instance, [0,25,50,75,100] indicates that the boxes should show first (0-25), second (25-50, third (50-75), and fourth (75-100) quartiles.
  • Group By is an example of a standard group object and follows the same format as a group in the Query Configuration Object .

Ungrouped query

Provides ungrouped (unaggregated) data with one entry per row in the data source. An ungrouped query is a stringified array of field objects, like those in a Query Configuration Object . Each field object requires the field name of each data source column that provides the values for that chart variable, together with the limit of rows to query from that column. For example:

'Fields List': '[ {"name":"_ts","limit":1000}, {"name":"group","limit":1000}, {"name":"category","limit":1000} ]'
  • Fields List is the name of the ungrouped query of fields (columns)
  • name is the field (column) name to query
  • limit is the maximum number of rows to query from the field

Chart constants

Provide a constant value as information about a chart. For example:

"Chart Description": "A chart that shows you things."

Was this topic helpful?