NAV
cURL JavaScript

Time Series Query Execution API

The execution of Time Series Queries, as part of the Time Series Query API.

Examples below make use of the TSA server of the production Waylay SaaS cluster at
https://ts-analytics.waylay.io
The examples use apiKey/apiSecret authentication. These credentials can be obtained through the Waylay Console.

Context

The Time Series Query API at the /data/query endpoint of the TSA Server takes a Time Series Query JSON object and executes the specified query on the Waylay time series database. The input specifiation can either be given by the user (POST /data/query) or be a reference to a stored query (GET /data/query/{name}).

See

This document describes how the result of a query execution is represented, and how request parameters can alter the execution and result representation.

Query Execution

endpoints

Introductory example of a single variate, unaggregated time series query. These examples use data sets that might not be available on your tenant deployment.

curl -u apiKey:apiSecret -X POST -H "Content-Type: application/json" -d '{
  "window": "PT1H", "until": "2020-09-08T12:10:00",
  "data": [ { "resource": "151CF", "metric": "temperature"} ]
}' https://ts-analytics.waylay.io/data/query
endpoint description
POST /data/query​ Retrieves the time series data as specified by a Time Series Query in the request body
(independent from the TSA Repository).
GET ​/data/query/{query_name} Retrieves the time series data as specified by the named Time Series Query, as stored in the TSA Repository.
{
    "messages": [],
    "query": {
        "window": "PT1H",
        "until": "2020-09-08T12:10:00",
        "data": [ { "resource": "151CF", "metric": "temperature" } ]
    },
    "data": [
        {
            "columns": [
                "timestamp", { "resource": "151CF", "metric": "temperature" }
            ],
            "data": [
                [1599564229000, 21],
                [1599565129000, 22],
                [1599566029000, 21],
                [1599566930000, 22]
            ],
            "data_axis": "column",
            "attributes": {
                "role": "input"
            },
            "window_spec": {
                "from": 1599564229000,
                "until": 1599567830000,
                "window": "PT3601S",
                "freq": "PT15M"
            }
        }
    ]
}

store the query under the name query_execution_example and check that execution by name has the same result

curl -u apiKey:apiSecret -X POST -H "Content-Type: application/json" -d '{
  "name": "query_execution_example",
  "query": {
    "window": "PT1H", "until": "2020-09-08T12:10:00",
    "data": [ { "resource": "151CF", "metric": "temperature"} ]
  }
}' https://ts-analytics.waylay.io/config/query
curl -u apiKey:apiSecret https://ts-analytics.waylay.io/config/query/query_execution_example 
( ... same result ...)

result overview

A typical JSON response of a query execution contains the following elements:

The result body can have additional properties that are generic for the Analytics APIs:

overrides

Some properties of a query (as specified in the request body, or referenced in the url path by name) can be overridden.

Any of the top-level attributes can be overridden by a corresponding url parameter:

override the window in a request (to have one day of results)

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/data/query/query_execution_example?window=P1D

add a sample interval and aggregation as override

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/data/query/query_execution_example?window=P1D&freq=PT1H&aggregation=count

Please consult the linked documentation for the exact meaning of each of these parameters.

overriding the default resource in this case has NO EFFECT, as we specified the "resource" at series level in query_execution_example { "window": "PT1H", "until": "2020-09-08T12:10:00", "data": [ { "resource": "151CF", "metric": "temperature"} ] }

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/data/query/query_execution_example?resource=151CF_alt

but it does have effect in this example, as the series specifications al use the default resource:

curl -u apiKey:apiSecret -X POST -H "Content-Type: application/json" -d '{
  "window": "PT1H", "until": "2020-09-08T12:10:00",
  "resource": "151CF",
  "data": [ { "metric": "temperature"}, { "metric": "lightAmbi"} ]
}' https://ts-analytics.waylay.io/data/query?resource=151D8 

Note that for series specification default properties, any url param override is ony effective for a series if it uses the default, i.e. it does not specify a value within the "data" specification that overrides it (see example).

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/data/query/query_execution_example??interpolation.method=linear

Overrides for the (default) interpolation properties need to use a .-separated path to set object properties. ( interpolation.method=linear)

render options

The render url parameters can modify the representation of data sets returned by the Query API.

This include an overal render.mode option for the general layout, and individual options such as render.iso_timestamp that tweak smaller aspects.

These options can be specified as URL parameters (for POST and GET requests).

curl -u apiKey:apiSecret "https://ts-analytics.waylay.io/data/query/query_execution_example?render.iso_timestamp=true" 
{ ...
  "data": [
    {
      "columns": [
        "timestamp",
        "timestamp_iso",
        {
          "resource": "151CF",
          "metric": "temperature"
        }
      ],
      "data": [
        [1599564229000, "2020-09-08T11:23:49+00:00", 21],
        [1599565129000, "2020-09-08T11:38:49+00:00", 22],
        [1599566029000, "2020-09-08T11:53:49+00:00", 21],
        [1599566930000, "2020-09-08T12:08:50+00:00", 22]
      ]
... }

supported render options

The url parameters render.mode, render.iso_timestamp and render.include_window_spec are supported in the current version of the Time Series Query API.

Render Option Possible Values Description
mode see below general mode of representation of a data set
iso_timestamp true, false If set, render timestamps in a row or column index
with both epoch milliseconds and iso representations.
include_window_spec true, false If set, include a window specification.

supported render modes

render mode data_axis include_window iso_timestamp remarks
RENDER_MODE_COMPACT_WS column TRUE FALSE default render mode
RENDER_MODE_SERIES row TRUE FALSE series-oriented data
RENDER_MODE_UPLOAD n/a (object) FALSE FALSE object-based representation compatible with broker api, not compatible with other options

RENDER_MODE_COMPACT_WS

This is the default representation as described above. It is an efficient and flexible format for multivariate timeseries data, but would normally require that a client maps it into its own (generic) data structures before using it in application code.

RENDER_MODE_SERIES

Column-oriented variant that has a seperate array of values for each series. Optimal when data is processed by series, as in most graphing toolkits.

RENDER_MODE_SERIES example

curl -u apiKey:apiSecret "https://ts-analytics.waylay.io/data/query/query_execution_example?render.mode=RENDER_MODE_SERIES" 
{
  "messages": [],
  "query": {
    "until": "2020-09-08T12:10:00",
    "window": "PT1H",
    "data": [ {"metric": "temperature", "resource": "151CF"} ],
    "render": {
      "mode": "RENDER_MODE_SERIES"
    }
  },
  "data": [
    {
      "columns": [
        "timestamp",
        {
          "metric": "temperature"
        }
      ],
      "data": [
        [1599564229000, 1599565129000, 1599566029000, 1599566930000],
        [21, 22,21, 22]
      ],
      "data_axis": "row",
      "attributes": {
        "resource": "151CF"
      },
      "window_spec": {
        "from": 1599564229000,
        "until": 1599567830000,
        "window": "PT3601S",
        "freq": "PT15M"
      }
    }
  ]
}

RENDER_MODE_UPLOAD

Representation for queries with a single resource that is identical to the format for bulk insert using the Waylay Broker API.

The data set is rendered as an array of json object that have a "resource" and "timestamp" property, while all other properties are interpreted as metric data.

If there are multiple levels (e.g. different aggregations) a concatenated metric key is produced.

This render mode can be used if a result needs to be reimported as data using the Broker API.

RENDER_MODE_UPLOAD example

curl -u apiKey:apiSecret "https://ts-analytics.waylay.io/data/query/query_execution_example?render.mode=RENDER_MODE_UPLOAD" 
 {
 "data": [
    [
      {
        "resource": "151CF",
        "timestamp": 1599564229000,
        "temperature": 21
      },
      {
        "resource": "151CF",
        "timestamp": 1599565129000,
        "temperature": 22
      },
      {
        "resource": "151CF",
        "timestamp": 1599566029000,
        "temperature": 21
      },
      {
        "resource": "151CF",
        "timestamp": 1599566930000,
        "temperature": 22
      }
    ]
   ]
 }