Retrieving data in MATLAB

We provide a MATLAB function (query) that fetches time series data from InfluxDB server and returns a table object.

Background

MATLAB R2016b has a built-in HTTP client function, webread. Moreover, this function returns already decoded MATLAB object if the received content is in JSON format. We use this function to retrieve and decode the JSON data.

Provided function

query(…)

query database

Syntax

tbl = query(Domain, ApiKey, TimeFilter, Name1, Value1, ..., NameN, ValueN)

Download

To download the source of query.m, please use the Raw or Download ZIP button on the GitHubGist page.

Description

query fetches time series data from Domain according to TimeFilter, Name1, Value1, …, NameN, ValueN, and converts the returned data into a table object. Below are the required parameters.

  • Domain is the domain part of the URL.

  • ApiKey is used for authenticating with the server.

  • TimeFilter expression must be written in InfluxQL, the default value "" ignores time.

query(___, Name1, Value1, ..., NameN, ValueN) specifies additional filters and the output format of the table.

Device

InfluxQL regular expression to select devices, the default value "//" matches all devices

Location

InfluxQL regular expression to select locations, the default value "//" matches all locations

Sensor

InfluxQL regular expression to select sensors, the default value "//" matches all sensors

IncludeNetworkSensors
true

allows returning network-related data

false (default)

filters out all network-related data

Channel

InfluxQL regular expression to select channels, the default value "//" matches all channels

AggFunc

InfluxQL aggregate function evaluated on the selected data, default is no aggregation

AggInterval

InfluxQL time interval value, used with AggFunc

DoUnstack
true (default)

return time series into individual columns

false

return all time series in a single column

ConvertTimestamp
true (default)

convert timestamps into date time objects

false

return timestamps in unix time in milliseconds

Timezone

Timezone name, used with ConvertTimestamp, the default value is "UTC"

Demonstration script

The following MATLAB script demonstrates the main functionality of query function with our demo.decentlab.com server. Before running the script, please download query.m from our gist repository by clicking the Raw button and save it in your MATLAB environment.

>> tbl = query(...
    'demo.decentlab.com', ...
    'eyJrIjoiclhMRFFvUXFzQXpKVkZydm52b0VMRVg3M3U2b3VqQUciLCJuIjoiZGF0YS1xdWVyeS1hcGktZGVtby0yIiwiaWQiOjF9', ...
    'time > now() - 1d', ...
    'Device', '/26[67]/', ...
    'Sensor', '/(temperature)|(humidity)/', ...
    'AggFunc', 'mean', ...
    'AggInterval', '7m');

The above example will retrieve the data from demo.decentlab.com server, matching the following criteria:

  • devices with ID containing 266 or 267 (will match also 2671, 12670, 4266, etc)

  • sensor names containing either temperature or humidity

  • compute the mean of groups divided by 7 min interval

  • received in the last one day

The result of the above script.

Note

unstack operation may change the field names so that they become valid identifiers in MATLAB. x is prepended to the series starting with digits, and - becomes _. You should use the original names instead of these names in the query function. Please consult the original names in the Sensors dashboard.

>> summary(tbl)

Variables:

    time: 205x1 datetime
        Values:

            min       05-Feb-2017 16:37:00
            median    06-Feb-2017 04:31:00
            max       06-Feb-2017 16:32:00

    x266_sht_humidity: 205x1 double
        Values:

            min        28.977
            median     29.942
            max        31.498
            NaNs       1

    x266_sht_temperature: 205x1 double
        Values:

            min        20.15
            median    20.193
            max       22.155

    x267_sensirion_sht21_humidity: 205x1 double
        Values:

            min        37.182
            median     37.808
            max        50.32
            NaNs       199

    x267_sensirion_sht21_temperature: 205x1 double
        Values:

            min        2.2066
            median     10.186
            max        13.135
            NaNs       199

Another example demonstrates different possibilities.

>> tbl = query(...
  'demo.decentlab.com', ...
  'eyJrIjoiclhMRFFvUXFzQXpKVkZydm52b0VMRVg3M3U2b3VqQUciLCJuIjoiZGF0YS1xdWVyeS1hcGktZGVtby0yIiwiaWQiOjF9', ...
  'time >= ''2016-12-01 00:00:00'' AND time < ''2017-01-01 00:00:00''', ...
  'Device', '/^266$/', ...
  'Sensor', '/^sht-/', ...
  'Timezone', 'Europe/Zurich', ...
  'DoUnstack', false);

In this example, we obtain data received from only 266. ^ and $ indicates the beginning and ending of regular expression so that no other ID containing 266, such as 1266, 2660, or _266a, matches the expression. In addition, all sensors starting with sht- are selected. The casting was disabled to obtain single column output data.

>> summary(tbl)

Variables:

    time: 17144x1 datetime
        Values:

            min       01-Dec-2016 01:02:43
            median    16-Dec-2016 16:29:52
            max       01-Jan-2017 00:57:02

    series: 17144x1 cell array of character vectors

    value: 17144x1 double
        Values:

            min       15.469
            median    24.258
            max       33.417

Here, the data received in the December of 2016 is returned. Please be careful with absolute time value in a query because it is always interpreted in UTC, and the output is also in UTC by default. For instance, the output timezone is Europe/Zurich in this example, and therefore the time values are beyond 2016-12-31 23:59:59, which is in the timezone of UTC+01 (winter time).