Query Eywa

Once your devices are generating data to Eywa, you should be able to query various data out of it. This page describes the simple query interfaces to achieve that goal.

For better understanding, let's take a look at some example data.

Channel Definition

{
  "id": "GDE3N17PA5gXAlVj",
  "name": "water level",
  "description": "This is a channel for monitoring water level in two places by two reporters.",
  "fields": {
    "depth": "int",
    "width": "int"
  },
  "tags": ["location", "reporter", "weather"],
  "access_tokens": ["12345"]
}

Sample Data

timestamp	depth	location	reporter	weather	width
1452296409000	130	us	kenny	sunny	6
1452296278000	153	china	mike	sunny	1
1452296505000	112	china	mike	sunny	5
1452297212000	167	us	kenny	cloudy	4
1452297385000	109	china	kenny	cloudy	8
1452297679000	143	us	mike	cloud	9
1452298125000	153	us	mike	sunny	10
1452298259000	155	china	kenny	sunny	3
1452298222000	135	us	mike	sunny	3
1452298646000	120	china	kenny	cloudy	0
1452298866000	null	china	mike	sunny	5

Basic Syntax

Time Range Expression

All timestamps are unix milliseconds from epoch.

An example time range including start and end time would be:

time_range=1449436224077:1449436235379

Time range without end time would imply that the current timestamp is the end time.

time_range=1449436224077:

All time ranges should contain the start time.

Time Interval Expression

Time intervals are expressed in the format of \d+[Mwdhms].

For example, 1s means 1 second, 2m means 2 minutes, 12h means 12 hours and 3d means 3 days, 1w means 1 week, and finally, 1M means 1 month.

Tagging Expression

Example:

tags=location:eq:china,reporter:eq:kenny

Multiple expressions are comma separated.

Supported Summary Types

avg, min, max, sum, last

Query for Field Value

This is used to query for a single value matching all the expressions, applied with summary_type.

Since the value is aggregated according to summary_type, the returned value won't have a timestamp attached to it.

request

GET http://<eywa_ip>:<eywa_port>/admin/channels/<channel_id>/value?field=<field>&tags=<tagging expression>&summary_type=<summary_type>&time_range=<time_range expression>

field, summary_type, and time_range are required.

tags is optional.

Here we are using Admin Endpoints for querying the data. These admin endpoints are used for data visualization and also in the command line tool. However, if you want to enable the query interfaces for your consumer apps, say your mobile app. You can use Eywa's API Endpoints.

example

GET http://<eywa_ip>:<eywa_port>/admin/channels/GDE3N17PA5gXAlVj/value?field=depth&tags=reporter:eq:mike&summary_type=avg&time_range=1449436224077:

response

{ "value" : 12.5 }

Specifically, for querying gauges,

GET http://<eywa_ip>:<eywa_port>/admin/channels/GDE3N17PA5gXAlVj/value?field=depth&tags=reporter:eq:mike&summary_type=last

response

{ "value" : 17.6 }

Query for Time Series

This is used to query for a series of timestamped values with applied summaries in each interval.

request

GET http://<eywa_ip>:<eywa_port>/admin/channels/<channel_id>/series?field=<field>&tags=<tagging expression>&summary_type=<summary_type>&time_range=<time_range expression>&time_interval=<interval expression>

field, time_range, time_interval, summary_type are required.

tags are optional.

example

GET http://<eywa_ip>:<eywa_port>/admin/channels/GDE3N17PA5gXAlVj/series?field=depth&tags=reporter:eq:mike&summary_type=avg&time_range=1449436224077:1449436235379&time_interval=1s

response

[
  { "timestamp": 1449456213000, "value": null },
  { "timestamp": 1449456214000, "value": null },
  { "timestamp": 1449456215000, "value": 112 },
  { "timestamp": 1449456216000, "value": 109 },
  { "timestamp": 1449456217000, "value": null },
  { "timestamp": 1449456218000, "value": null },
  { "timestamp": 1449456219000, "value": null },
  { "timestamp": 1449456220000, "value": 155 },
  { "timestamp": 1449456221000, "value": 120 },
  { "timestamp": 1449456222000, "value": 173 }
]

The timestamp returned in response is always unix milliseconds from epoch too.

Query for Raw Data

This is usually for testing purposes, or data exporting. And there are two modes of this query: nop=true or nop=false

nop=true simply returns the approximate size of the raw data. We don't recommend to export all the data at one time, since it will potentially choke the entire service. By doing nop query you can get some idea about your data size, and shrink the time_range to reduce it if it's too large. nop=true is also the default mode.

nop=false returns the raw data your devices have sent to the server.

nop=true

request

GET http://<eywa_ip>:<eywa_port>/admin/channels/<channel_id>/raw?tags=<tagging expression>&time_range=<time_range expression>&nop=true

time_range is required while tags is optional.

example

GET http://<eywa_ip>:<eywa_port>/admin/channels/GDE3N17PA5gXAlVj/raw?tags=reporter:eq:mike&time_range=1449436224077:1449436235379&nop=true

response

{ "size": "1.23mb" }

nop=false

request

GET http://<eywa_ip>:<eywa_port>/admin/channels/<channel_id>/raw?tags=<tagging expression>&time_range=<time_range expression>&nop=false

time_range is required while tags is optional.

example

GET http://<eywa_ip>:<eywa_port>/admin/channels/GDE3N17PA5gXAlVj/raw?tags=reporter:eq:mike&time_range=1449436224077:1449436235379&nop=false

response

{"timestamp": 1452296278000, "depth": 153, "location": "china", "reporter": "mike", "weather": "sunny", "width": 1}
{"timestamp": 1452296505000, "depth": 112, "location": "china", "reporter": "mike", "weather": "sunny", "width": 5}
{"timestamp": 1452297679000, "depth": 143, "location": "us", "reporter": "mike", "weather": "cloudy", "width": 9}
{"timestamp": 1452298125000, "depth": 153, "location": "us", "reporter": "mike", "weather": "sunny", "width": 10}
{"timestamp": 1452298222000, "depth": 135, "location": "us", "reporter": "mike", "weather": "sunny", "width": 3}
{"timestamp": 1452298866000, "depth": null, "location": "china", "reporter": "mike", "weather": "sunny", "width": 5}