NAV
cURL JavaScript

Time Series Query CRUD API

Create, read, replace and delete Time Series Queries entities 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

A Time Series Query, which defines a query on the time series database, can be represented as a JSON object.

The /config/query endpoint, described here, lets you store, read, replace and delete these query definitions by wrapping them in a JSON Wrapper, giving it a name and adding metadata to classify it.

Once a query entity is stored via the /config/query endpoint in the TSA Repository, it can be referenced by the GET /data/query/{query_name} endpoint to execute the timeseries query.

See also:

Overview

The following API endpoints support the management of Time Series Query entities:

endpoint description
POST /config​/query​/{query_name} creates a Time Series Query entity
PUT /config​/query​/{query_name} overwrites a Time Series Query entity
GET /config​/query​/{query_name} gets a Time Series Query entity
DELETE /config​/query​/{query_name} deletes a Time Series Query entity
GET ​/config​/query lists or searches Time Series Query entities

CRUD operations

The GET|DELETE|PUT /config​/query/{query_name} and POST /config​/query endpoints provide a basic CRUD api to create (PUT or POST), retrieve (GET), replace (PUT) and delete (DELETE) a Time Series Query.

create

curl -u apiKey:apiSecret -X POST -H "Content-Type: application/json" -d '{
   "name": "max_flow_099",
   "query": { 
     "freq": "PT1H",
     "aggregation": "max",
     "data": [ { "resource" : "device_099", "metric": "flow" }]
   },
   "meta": {
     "description": "demo query"
   }
}' https://ts-analytics.waylay.io/config/query 
{
  "messages": [],
  "name": "max_flow_099",
  "query": {
    "data": [
      {
        "metric": "flow",
        "resource": "device_099"
      }
    ],
    "freq": "PT1H",
    "aggregation": "max"
  },
  "meta": {
    "description": "demo query"
  },
  "attrs": {
    "created": "2020-09-08T13:40:12.609902+00:00",
    "created_by": "users/0476f99d-ac60-4f86-bc45-7215962754cd",
    "modified": "2020-09-08T13:40:12.609902+00:00",
    "modified_by": "users/0476f99d-ac60-4f86-bc45-7215962754cd"
  },
  "_links": {
    "self": {
      "href": "https://ts-analytics.waylay.io/config/query/max_flow_099"
    }
  }
}

POST /config​/query accepts a (wrapped) Time Series Query representation in the request body, and creates it under the name given in the"name" attribute. This operation fails when the entity already exists. Only the request attributes "name", "query" and "meta" are processed.

Note that PUT /config​/query/{name} (replace) is an alternative creation method that does overwrite any existing entities.

retrieve

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/config/query/max_flow_099

( returns the same representation )

GET /config/query/{query_name} returns the full Time Series Query representation for the entity named in the URL.

replace

curl -u apiKey:apiSecret -X PUT -H "Content-Type: application/json" -d '{
   "query": {
     "freq": "PT24H",
     "aggregation": "max",
     "resource" : "device_099",
     "data": [
         { "metric": "flow" },
         { "metric": "reverse_flow" }
     ]
   },
   "meta": {
     "description": "modified demo query"
   }
}' https://ts-analytics.waylay.io/config/query/max_flow_099
{
  "messages": [],
  "name": "max_flow_099",
  "query": {
    "data": [
      {
        "metric": "flow"
      },
      {
        "metric": "reverse_flow"
      }
    ],
    "freq": "PT24H",
    "resource": "device_099",
    "aggregation": "max"
  },
  "meta": {
    "description": "modified demo query"
  },
  "attrs": {
    "created": "2020-09-08T13:40:12.609902+00:00",
    "created_by": "users/0476f99d-ac60-4f86-bc45-7215962754cd",
    "modified": "2020-09-08T13:51:18.921394+00:00",
    "modified_by": "users/0476f99d-ac60-4f86-bc45-7215962754cd"
  },
  "_links": {
    "self": {
      "href": "https://ts-analytics.waylay.io/config/query/max_flow_099"
    }
  }
}

PUT /config/query/{query_name} accepts a (wrapped) Time Series Query representation in the request body, and creates OR replaces it under the name given in the URL. A "name" attribute in the request is optional, but MUST be the same as the one given in the URL.

Only the request attributes "name", "query" and "meta" are processed.

delete

curl -u apiKey:apiSecret -X DELETE https://ts-analytics.waylay.io/config/query/max_flow_099
{
  "messages": []
}

DELETE /config/query/{query_name} deletes the named Time Series Query.

JSON Entity Wrapper

When performing CRUD operations for a TSA Configuration on the /config endpoint, the actual configuration payload is wrapped in an entity representation.

Example entity representation for a Query Configuration

{
  "name": "office temperature",
  "query": {
    "freq": "PT1H",
    "metric": "temperature",
    "resource": "151CF",
    "aggregation": "median",
    "interpolation": { "method": "pad" },
    "data": [
      { },
      { "name": "signal strength", "metric": "rssi" },
      { "metric": "snr" },
      { "name": "ambient light", "metric": "lightAmbi" }
    ]
  },
  "meta": {
    "tags": ["office", "climate", "test"],
    "description": "Hourly temperature in our office"
  },
  "attrs": {
    "created": "2020-07-30T14:36:48.749339+00:00",
    "created_by": "users/43a7ead3-f76f-46fc-80d7-998454fd6472",
    "modified": "2020-07-30T14:36:48.749339+00:00",
    "modified_by": "users/43a7ead3-f76f-46fc-80d7-998454fd6472"
  }
}

This (wrapped) entity representation uses the following object properties:

Note that a result representation can have additional keywords that are general for the Time Series services:

Related APIs

Query Execution API

The following scripts illustrate the complementarity of Query Execution API and the Query Entity CRUD API:

retrieve the stored query entity, extract the query spec, and execute it as an ad hoc query

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/config/query/max_flow_099 \
| jq '.query' \
| curl -u apiKey:apiSecret -X POST \
    -H "Content-Type: application/json" \
    -d @- \
    https://ts-analytics.waylay.io/data/query

Once stored GET /data/query/{query_name} will execute the query (see Query Execution API).

endpoint description
GET ​/data/query/{query_name} Retrieves the time series data specified in the named Time Series Query, as stored in the TSA Repository.
POST /data/query​ Retrieves the time series data as specified by a Time Series Query in the request body
(independent from the TSA Repository).

the same using a named query execution

curl -u apiKey:apiSecret https://ts-analytics.waylay.io/data/query/max_flow_099

Query Search API

The GET /config/query lists (one page of) all Time Series Query entities that reside in the TSA Repository. See Search API for a detailed description. The following are the main feature of the search endpoint.

endpoint description
GET /config/query?q=<filter>&limit=<n>&offset=<o> Retrieves the time series data specified in the named Time Series Query, as stored in the TSA Repository.
Supports request parameters for paging (limit, offset) and filtering (q).

A search filter is a whitespace-separated list of search terms such as: