Retrieving data in Python¶

We provide a Python function, query, that fetches time series data from InfluxDB server and returns pandas.DataFrame object.

Setting up¶

The query function uses requests, an HTTP client library for humans, to access the database. Since the function returns pandas.DataFrame object, we need pandas as well. To install them:

$ sudo apt install python-requests python-pandas

or if you prefer pip:

$ pip install requests pandas

Please make sure installing them on your correct Python environment. This guide is written with python v3.5, requests v2.14.2, and pandas v0.20.1.

Provided function¶

query(domain, api_key[, time_filter=''][, device='//'][, location='//'][, sensor='//'][, include_network_sensors=False][, channel='//'][, agg_func=None][, agg_interval=None][, do_unstack=True][, convert_timestamp=True][, timezone='UTC'])¶

fetches time series data with matching parameters from the database server and converts into pandas.DataFrame object

Parameters

domain (str) – The domain part of the URL
api_key (str) – Secret key for authenticating with the server
time_filter (str) – Time filter expression written in InfluxQL, the default value '' ignores time
device (str) – InfluxQL regular expression to select devices, the default value '//' matches all devices
location (str) – InfluxQL regular expression to select locations, the default value '//' matches all locations
sensor (str) – InfluxQL regular expression to select sensors, the default value '//' matches all sensors
include_network_sensors (bool) – True - allows returning network-related data, False (default) - filters out all network-related data
channel (str) – InfluxQL regular expression to select channels, the default value '//' matches all channels
agg_func (str) – InfluxQL aggregate function evaluated on the selected data, no aggregate function is applied by default
agg_interval (str) – InfluxQL time interval value, used with agg_func
do_unstack (bool) – True (default) - return time series in individual columns, False - return all time series in a single column
convert_timestamp (bool) – True (default) - convert timestamps into date time objects, False - return timestamps in unix time in milliseconds
timezone (str) – Timezone name, used with convert_timestamp

Returns

object containing time series data

Type

pandas.DataFrame

Download¶

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

Demonstration script¶

The following Python script demonstrates the main functionality of query function with our demo.decentlab.com server. Before running the script, please download it and save it in your Python environment as decentlab.py.

from decentlab import query
df = query(domain='demo.decentlab.com',
           api_key='eyJrIjoiclhMRFFvUXFzQXpKVkZydm52b0VMRVg3M3U2b3VqQUciLCJuIjoiZGF0YS1xdWVyeS1hcGktZGVtby0yIiwiaWQiOjF9',
           time_filter="time > '2020-01-01' AND time < '2020-01-05'",
           device='/^(3001|6414)$/',
           sensor='/sht30|mb7389/',
           agg_func='mean',
           agg_interval='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

Note that the head function shows only the first five rows. The result of the above script:

>>> df.head()

series                     3001.sensirion-sht30-humidity  \
time
2020-01-01 00:00:00+00:00                      31.614322
2020-01-01 12:00:00+00:00                      31.190077
2020-01-02 00:00:00+00:00                      30.880091
2020-01-02 12:00:00+00:00                      30.750819
2020-01-03 00:00:00+00:00                      30.785120

series                     3001.sensirion-sht30-temperature  \
time
2020-01-01 00:00:00+00:00                         20.873315
2020-01-01 12:00:00+00:00                         20.905385
2020-01-02 00:00:00+00:00                         20.862344
2020-01-02 12:00:00+00:00                         20.898224
2020-01-03 00:00:00+00:00                         20.874380

series                     6414.maxbotix-mb7389-distance  \
time
2020-01-01 00:00:00+00:00                    3189.880282
2020-01-01 12:00:00+00:00                    3184.826389
2020-01-02 00:00:00+00:00                    3194.190141
2020-01-02 12:00:00+00:00                    3188.147887
2020-01-03 00:00:00+00:00                    3192.784722

series                     6414.maxbotix-mb7389-trials
time
2020-01-01 00:00:00+00:00                         15.0
2020-01-01 12:00:00+00:00                         15.0
2020-01-02 00:00:00+00:00                         15.0
2020-01-02 12:00:00+00:00                         15.0
2020-01-03 00:00:00+00:00                         15.0