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(…)

fetch data from server

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"

Timeout

Seconds before interrupting the HTTP request, the default value is 20

Database

Database name to retrieve the data from, the default value is "main"

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 > ''2020-01-01'' AND time < ''2020-01-05''', ...
    'Device', '/^(3001|6414)$/', ...
    'Sensor', '/sht30|mb7389/', ...
    'AggFunc', 'mean', ...
    'AggInterval', '12h')

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

  • devices with ID 3001 or 6414

  • sensor names containing either sht30 or mb7389

  • compute the mean of groups divided by 12-hour interval

  • received between 2020-01-01 and 2020-01-05

The value of tbl:

tbl =

  8x5 table

            time            x3001_sensirion_sht30_humidity    x3001_sensirion_sht30_temperature    x6414_maxbotix_mb7389_distance    x6414_maxbotix_mb7389_trials
    ____________________    ______________________________    _________________________________    ______________________________    ____________________________

    01-Jan-2020 00:00:00                31.614                             20.873                              3189.9                             15
    01-Jan-2020 12:00:00                 31.19                             20.905                              3184.8                             15
    02-Jan-2020 00:00:00                 30.88                             20.862                              3194.2                             15
    02-Jan-2020 12:00:00                30.751                             20.898                              3188.1                             15
    03-Jan-2020 00:00:00                30.785                             20.874                              3192.8                             15
    03-Jan-2020 12:00:00                31.266                             21.049                              3182.4                             15
    04-Jan-2020 00:00:00                32.441                             20.963                              3190.2                             15
    04-Jan-2020 12:00:00                33.129                             21.081                                3186                             15

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.