Data: Time Series Node

The Data: Time Series Node allows a workflow to query recent state across a time period for one or more devices for one or more attributes.

Node Properties

The configuration for the node is similar to the Time Series Dashboard Block. There are three major components: Device Selection, Query Configuration, and Result Path.

Device Selection

The first step is selecting the devices to query. There are several options for selecting devices:

• Specific Devices and/or Device Tags: Queries specific devices and/or device tags.
• Device IDs Specified on Payload: Queries a payload path to pull one or more Device IDs off of the current workflow payload.
• Parent System ID: Queries all devices with a specified parent system or all devices that have no parent system. This field is templatable.
• Experience Group ID: Queries all devices that are associated with a specified Experience Group. This field is templatable.
• Experience User ID or Email: Queries all devices that are associated with the specified Experience user. This field is templatable.
• Advanced Query: Allows you to construct your own device query.

In the example above, all devices with a tag value equal to 123 are queried, regardless of the tag key associated with the value.

Query Configuration

The Data: Time Series Node also requires the following:

• Attribute: Select one or more attributes to query. Choosing a single attribute vs multiple attributes will affect the format of the final result.
• Time Range: Defines how far back in time to retrieve data. Can be set to Custom to allow for a duration and end time to be entered explicitly or using a template.
• Resolution: Defines the amount of time each aggregation spans. The available resolutions vary depending on the selected time range, just like the Time Series Dashboard Block. Can be set to Custom to allow for a time in milliseconds to be entered explicitly or using a template.
• Aggregation: This templatable input allows you to select an aggregation method to be used for the resolution. Depending on the aggregation, there may be additional fields to configure.
• Order Direction: Allows you to determine the order of the results (default is asc which is oldest point first).
• Matching Value: If Time at Value ... is selected as the aggregation method, this field is required. Enter the value you wish to query. This field is templatable.
• Limit Template: If None is selected as the aggregation method, this optional field allows you to control the maximum number of points returned. The default and maximum is 25,000. This field is templatable.
• Per Device Results: Allows you to choose between a single result aggregated across all matching devices, or a result per matching device. A result per device is the only allowed option when using None as the aggregation method. This choice will affect the format of the final results.

In the above example, the attribute height is queried over the last 60 minutes with a one-minute resolution using a Last aggregation.

Result Path

Once the query is configured, the node needs a payload path to know where to store the result on the current workflow payload. In the above example, the result is be stored at results. The structure of the result can be very different depending on the configuration options chosen.

Aggregating Across Devices

For A Single Attribute

If resolution does not equal duration, what is returned will be an array of points, like so:

[
  { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
  { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 49.7 },
  { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 51.0 }
]

If resolution does equal duration, what is returned will be a single point, like so:

{ "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 }

For Multiple Attributes

If resolution does not equal duration, what is returned will be object of attribute names mapping to arrays of points, like so:

{
  "voltage": [
    { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
    { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 49.7 },
    { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 51.0 }
  ],
  "amps": [
    { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 1 },
    { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 2 },
    { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 3 }
  ],
}

If resolution does equal duration, what is returned will be an object of attribute names mapping to single points, like so:

{
  "voltage": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
  "amps": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 2 }
}

Aggregating Per Device

For A Single Attribute

If resolution does not equal duration, what is returned will be an object of device IDs mapping to arrays of points, like so:

{
  "575ecf887ae143cd83dc4aa2": [
    { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
    { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 49.7 },
    { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 51.0 }
  ],
"575ef5c97ae143cd83dc4aac": [
    { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 18.8 },
    { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 29.7 },
    { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 31.0 }
  ]
}

If resolution does equal duration, what is returned will be an object of device IDs mapping to single points, like so:

{
  "575ecf887ae143cd83dc4aa2": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
  "575ef5c97ae143cd83dc4aac": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 18.8 }
}

For Multiple Attributes

If resolution does not equal duration, what is returned will be an object of device IDs mapping to attribute names mapping to arrays of points, like so:

{
  "575ecf887ae143cd83dc4aa2": {
    "voltage": [
      { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
      { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 49.7 },
      { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 51.0 }
    ],
    "amps": [
      { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 1 },
      { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 2 },
      { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 3 }
    ],
  },
  "575ef5c97ae143cd83dc4aac": {
    "voltage": [
      { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 487.8 },
      { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 46.7 },
      { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 55.0 }
    ],
    "amps": [
      { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 2 },
      { "time": Thurs Feb 18 2016 19:00:00 GMT-0500 (EST), "value": 3 },
      { "time": Thurs Feb 18 2016 20:00:00 GMT-0500 (EST), "value": 4 }
    ],
  },
}

If resolution does equal duration, what is returned will be an object of device IDs mapping to attribute names mapping to single points, like so:

{
  "575ecf887ae143cd83dc4aa2": {
    "voltage": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 48.8 },
    "amps": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 1 }
  }
  "575ef5c97ae143cd83dc4aac": {
    "voltage": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 18.8 },
    "amps": { "time": Thurs Feb 18 2016 18:00:00 GMT-0500 (EST), "value": 2 }
}

Aggregating With None

When aggregating using None as the aggregation method, what is returned is raw data in the following form (matching the form return from the Data: Time Series Query API endpoint), like so:

{
  "start": "2016-06-15T03:50:00.000Z",
  "end": "2016-06-15T04:00:00.000Z",
  "resolution": null,
  "aggregation": null,
  "devices": {
    "575ecf887ae143cd83dc4aa2": {
      "name": "My Device",
      "points": [
        {
          "time": "2016-06-15T03:50:00.000Z",
          "data": {
            "voltage": 10.3
          }
        },
        {
          "time": "2016-06-15T03:55:00.000Z",
          "data": {
            "voltage": 12.7
          }
        }
      ]
    },
    "575ef5c97ae143cd83dc4aac": {
      "name": "My Other Device",
      "points": [
        {
          "time": "2016-06-15T03:50:00.000Z",
          "data": {
            "voltage": 10.3
          }
        },
        {
          "time": "2016-06-15T03:55:00.000Z",
          "data": {
            "voltage": 12.7
          }
        }
      ]
    }
  }
}