Query Designer

The Query Designer can be accessed via the Queries tile in the Waylay Console, or directly at https://tsa.waylay.io/#query

The Query Overview

The landing page for the Query Designer lists all queries that are currently defined for your tenant. It supports query by name, and lets you create new queries.

The Query Designer

The Query Designer page is an editor for new or saved Time Series Query definitions, and visualizes the query results for a given time window.

Many UI elements of the query designer have an info popup   that explains it’s role.

The Query Designer has the following elements:

Query breadcrumbs

Informs that we are working in the Query Designer and shows the name of the current query, or <new> for an unsaved query.

Action panel

TS Query Designer Action Panel

The functions of the buttons from left to right are:

  • Save the current query under a query name,
  • Revert your current workspace to the saved version of the active configuration,
  • Download data as specified by the query in a CSV format,
  • Open the Model Designer with the current query as the series specs,
  • Open the Rule Designer with a timeseriesQueryData sensor that makes use of the current query.

Chart area

Chart area overview

The chart area lets you preview the query results:

  • The data chart shows the timeseries as configured for a given time window
  • The overview slider previews the first or default series at a higher aggregation level, and lets you select the time window for the chart above. The slider lets you pan and zoom through the data set. Zooming out is either restricted, or can change the granularity at which data is aggregated (see locked to zoom level)

Parameter definitions

The Parameters section in the designer specifies properties of the whole Query definition.

Each Series section specifies an individual time series from which the dataset is composed.

Each field in these sections has the same meaning as in the TSA Model Designer, although their defaults and organisation are a bit different.

Grouped By

The Grouped By field in the Parameters section defines the interval at which all series are grouped or sampled. The exact grouping method (Aggregation fields) can vary per Series.

When no aggregation is selected, the timeseries are queried without grouping. If in this case multiple series are specified (a multivariate query) the resulting data set will contain values for all timestamps (i.e. outer join of series on timestamp). You can use Interpolation to specify which values are reported when a series has no value at a timestamp that is present in another series, or leave the undefined data points in place.

Locked to zoom level

The Grouped By field can be locked to the zoom level of the chart. When locked, the aggregation interval is chosen to be compatible with the view window that is selected in the overview slider. This will result in ever-greater aggregation intervals when you zoom out.

Initially it is unlocked, allowing you to freely choose the value, but limiting the amount that you can zoom out to a maximum number of intervals (normally around 2000).

Clicking on the lock icon makes the field read-only, and links it to the zoom level of the data selection.

Default Parameters

All other fields in the Parameters section (Default Resource, Default Metric, Default Aggregation, Default Interpolation) are defaults for the corresponding fields at Series level.

Their usage is optional, but

  • it avoids repeated entry of the same specification for each series in the designer.
  • when saved and exposed in the Query API, these parameters can be overridden. A saved Time Series Query that only has a resource specification in Default resource can later be used to fetch similar data (metrics and aggregations) for another resource, similar to switching the Default resource to another value in the Designer.
  • the Default Resource, Default Metric and Default Aggregation specify the input for the overview slider.

Series specification

One or more Series sections specify the time series data from which the query pulls data.

Name, Resource, Metric, Aggregation, and Interpolation can be defined at individual Series level, but take default values from the corresponding fields in the Parameters section.

Name

The (optional) display name to use in the query for this series specification. When not specified, the system uses <resource>/<metric> or <resource>/<metric> (<aggregation>) as generated display name.

This name is also used as column header when generating a CSV export.

Resource

The resource id under which the data was stored in the time series database. Entering a value in this field kicks off a search on existing resources, both on the id and the name of the resource.

select resource by name select resource by id

The dropdown only shows the name of the resource as label, the info popup will inform you of the id.

Use the (query value) item in the dropdown list if for any reason you want to specify a (currently) non-existing resource id.

Once selected, only the resource id is used as specification. Use the name field if you need to make this identification more human-readable.

Metric

This field specifies the metric under which the data was stored in the time series database. If a (default) resource is configured, the dropdown in this field consist of all metric names for which numeric data has been seen for that resource in the timeseries database.

Aggregation

If Group By is specified in the Parameters section, this Aggregation field specifies the aggregation method for the series.

Interpolation

Interpolation specifies how undefined values for a time series are handled. As our timeseries database does not store undefined values, this can only occur when aggregating (over time intervals with no data) or when joining multiple unaggregated series (with different timestamps).

If interpolation is not set, the values will be left undefined. Another common approach is to use the pad interpolation, which repeats the last value seen.

Some interpolation methods will require additional fields:

  • The fixed interpolation requests a Fixed Value that will replace any undefined value for that series.
  • Methods such as n-th order polynomial require an Interpolation Order

Query Attributes

The Attributes section in the designer gives access to some of the metadata of the query that is used when storing it.

  • Description is a human readable text that is stored together with the query.
  • Tags are (space-separated) keywords that you can associate with the saved query, to facilitate lookup or configuration management.

This section also contains a readonly representation of who and when this configuration was created or last saved.

Settings

The Settings sections contain properties of the Query Designer itself, which are not stored with the query, like the Graph Settings that control the graph layout and style.

Feedback area

The feedback area can be unfolded and exists of two main tabs:

  • Series show statistics about the Timeseries.
  • Messages show info, warning and error messages coming from the TS Query REST backend.

Feedback area overview