Tutorial

---

The following tutorial will guide you through storing and querying data via the HTTP API. You will need to have curl available to run the example code and a running Streametry server. Replace host with the hostname:port of where the server is running.

We will use temperature sensors as an example. Imagine we have two sensors called A and B that publish temperature readings once in a while. The JSON form of their data is:

{temp: 20, city: "NY"}

1. Store initial data

Initially the sensors publish their current temperature reading and their location. Run these commands to store the initial data:

curl http://host/met/sensors/A -X POST -d '{temp: 20, city: "NY"}'
curl http://host/met/sensors/B -X POST -d '{temp: 25, city: "SF"}'

2. Lookup

If we want to see what the current state of a sensor is we run:

curl http://host/met/sensors/A

which should return:

{"temp": 20, "city": "NY"}

3. Push some updates

As the sensors read more data they can push more updates. The following commands will update the temp field but will leave the city field intact:

curl http://host/met/sensors/A -X PUT -d '{temp: 21}'
curl http://host/met/sensors/B -X PUT -d '{temp: 26}'

4. Lookup updated data

curl http://host/met/sensors/A

should return:

{"temp": 21, "city": "NY"}

5. Run a query

Let's say now we wanted to find all sensors that have temperature above a certain threshold. We could run a simple query using the Coffeescript syntax:

curl http://host/met -X POST -d 'stream("sensors")
    .filter( (sensor) -> sensor.temp > 25 )'

should return:

{"B": {"temp": 26, "city": "SF"}}

because currently only sensor B has temperature above 25.

Don't close the query yet! Now while the query is still running open another terminal window and update the temperature for sensor A to be 27. What you will notice is that the query will return additional results as soon as you do that.

6. Run an aggregate query

Now we would like to see what the average, min and max temperature is currently. Run the following query:

curl http://host/met -X POST -d 'stream("sensors")
    .filter( (sensor) -> sensor.temp > 25 )
    .stats("temp")'

will give you something like this:

{"stats": {"count": 2, "min": 26.0, "max": 27.0, "avg": 26.5}}

7. Run a historical query

While we were pushing all that data Streametry was automatically saving each change in temperature. Assuming the sensors have been publishing temperature for a while we might want to have a look at what the temperature changes have been in the past hour:

curl http://host/met -X POST -d 'history("sensors", "temp")
    .filter( Time.past(1, "hour") )'

should return all the reading with timestamps in the following form:

{"B": {"temp": 26.0, "t": 1403176288126}}

Having all the readings and timestamps is convenient for plotting them on a chart.

8. Run an aggregate query on historical data

Finally we would like to ask questions about past temperature readings such as what was the average in the past day:

curl http://host/met -X POST -d 'history("sensors", "temp")
    .filter( Time.past(1, "day") )
    .avg("temp")'

Historical queries are live as well so as new data comes in the average will be updated.

Conclusion

These steps should give you an initial idea of how you can publish and query your own data. Have a look at the documentation for more types of queries you can run and how you can publish query results to a web browser.

The url in these examples consisted of four main parts http:// host / met / sensors / A:

Position	Name	Description
1	host	The address of the server
2	met	Name of an application chosen by the user (meteo)
3	sensors	Name of a collection
4	A	Key in the collection. Name of the sensor in this example.