Query Builder

A friendly interface that allows you to build sophisticated WideSky queries without typing

The WideSky query builder provides an interactive interface to build Grafana dashboards and panels. Built specifically for Grafana, you can build sophisticated insights without having to reference the GraphQL API docs or worry about query syntax errors. Queries can range in complexity from a simple count of entities with the site tag, to complex time series aggregations or transformations.

Query builder


Core Concepts

Below are some core concepts that are helpful to know when building a query.

Objects and Fields

A WideSky GraphQL query is constructed by asking for specific fields on objects. To assist common data analytics problems and to leverage Project Haystack semantic modelling, we've built many custom fields and object types.

Each object type has one or many fields available that can return basic types, e.g. Bool or string, or a complex types, e.g. timeseries data. When you build a query you need to specify the fields you need, the query builder presents the available fields choices based on the object type.

Let's look at a simple example. All fields appear on the left, colored blue.

Simple entity query

You can see that we query for 3 fields:

  • haystack: Each query must begin with this field.
  • search: A sub-field of haystack, search uses a project haystack filter, in this case ‘point’ to search WideSky Entities with the tag point.
  • count: A sub-field of search, count return with the number of entities returned in the search. In our case, it's 4.

Let's look at a query that plots timeseries data:

Simple timeseries example

You can see that we query for 4 fields:

  • haystack: Each query must begin with this field.
  • search: A sub-field of haystack, search uses a project haystack filter, in this case ‘point and his and power’ to search WideSky Entities with the tags point, his and power.
  • history: A sub-field of search, that's used to access history data of the point entities.
  • timeseries: A sub-field of history, which returns the timeseries data. In our case, we get 4 series.

You can freely add and remove fields to alter what data you can request from WideSky in a single query. Overall there are 19 custom object types, the 6 main types are in the following table:

Object # of Available Fields Description
Haystack 2 The Root Object - Each query must start with this object
Entities 7 A collection of 1 or more Project Haystack Entities
Entity 9 A single Project Haystack Entity
History 10 The timeseries history of an entity. Note: The entity must satasify several conditions to have history
Timeseries 1 Timeseries datapoints
Tag 3 Tagging information of an entity

View the Schema Reference, or the Interactive view to see the entire GraphQL schema.

Adding fields

To add a field, click on an existing field to access the pop-up menu under ‘fields’ and select one from a list.

Changing fields

To alter a field, click on an existing field and drill down to ‘change to’ to see a list of available fields.

Removing fields

To remove a field, click on an existing field and select ‘remove’. All arguments and sub-fields are deleted.

Arguments

Each field can have one or more arguments which alter the behaviour of a field. Mandatory arguments are placed in-line with the field and require a value to be set. Non-mandatory arguments are initially collapsed under ‘options’. Click on the options arrow to expand them and set their values. Arguments with a default value appear as are shown in grey. An argument can also have nested arguments which are also initially collapsed.

Time range

The start and end times of the dashboard are exposed as the variables $to and $from. To ensure the time range of the query matches the Grafana dashboard, these variables are automatically entered into the relativeRange arguments of the history field when it's added.

Time rage arguments


Haystack filter auto-complete

The query builder has auto-complete functionality to assist the construction of the Project Haystack filter argument. It offers contextually aware choices after each edit allowing you to query for tags in your asset model without prior knowledge of what's available.

To create a filter, click the select a tag button to the right of the filter field and select a tag. Depending on the selected tag kind the builder suggests choices for the next part of the filter.

You can remove parts of a filter by clicking either an operator and or, comparison operator ==, !=, or path -> and then selecting --Remove--. The right side of the statement up to the next comparison operator will be deleted.


Query formats

Change the query format to suit panels by clicking on Format as and selecting a mode in the table below:

Mode Description
Time Series Used for most panels types to plot data over time, e.g. Graph panel
Table Used for Table or Worldmap panels
WideSky Used for WideSky real-time control button

Time series Format

Use the time series format option for panels that plot data over time. A timeSeries field (sub-field of history) is also required your query.

Auto GroupBy

When there are more data points than can be shown on a graph, the queries can be made more efficient by grouping by a larger time interval. The builder sets the variables __intervalDuration and __intervalNum to the Grafana auto-calculated time interval. These variables are automatically entered into the aggregate or select fields arguments.

Alias

By default, if alias setting is blank, the panel labels each series found in the query response with an auto-generated name.

To define a label for your series, you can either:

  • Set a static name for the series by setting a value.
  • Use data from another field in your query by specifying a path to the field.
  • A mixture of both points above.
Path syntax

You can specify what field(s) to alias by specifying the path of the field relative to the timeSeries field in your query. This path uses a simple relative path syntax encapsulated in braces {<relative path from timeSeries to field>}.

Syntax Description
./ Means the current field
../ The parent field of the current timeSeries field
../../ The field that is two levels above the current timeSeries field
../<field_A> The sub-field <field_A> of the current timeSeries field
../{<field_A>[n].<field_B>} The sub-field field_B from the nth element of sub-fieldfield_A, of the current timeSeries field
Path example

Given the query:

Alias example

Example alias configurations:

Alias value Resulting series label
MSB North MSB North
{../../description} <asset model entity description> e.g. Active Energy
MSB North {../../description} MSB North Active Energy
{../../refEntity/description} MSB North {../../description} Site A MSB North Active Energy

Table format

When Format as is set to table, the builder presents a column selector. Click on select field to assign a field to a column.

All field values are shown using a relative path, e.g. haystack.search.count. Subsequent columns can be flattened to a parent columns if the sub-field has multiple values. You can flatten fields with more than one result to a parent field, by selecting the parent field in flatten with.


Mode switch

You can switch to text edit mode by clicking the pencil icon. This mode allows you edit the GraphQL query directly.