Tutorial

Make sure the database is running.

docker run -p 8000:8000 -d jptmoore/nibbledb

Run the REPL.

docker run --network host -it jptmoore/nibbleql
Welcome to nibbleql the query language for nibbledb

Set the location of the database we will connect to.

nibble> set host "http://localhost:8000";

We can POST single or multiple values to a time series. In addition to the value we can supply a timestamp and a tag. The tag is an array of pairs of strings which are used in queries.

nibble> post 42.0 to "sensor1";
nibble> post 42.1 to "sensor2";
nibble> post tag=["serial"="A001"], 43.0 to "sensor1";
nibble> post 10.0,20.0,30.0 to "sensor3";
nibble> post timestamp=1599069856546115, tag=["serial"="B001","location"="UK"], 40.0 to "sensor3";
nibble> post (tag=["serial"="A001","location"="FR"], 100.0), (tag=["serial"="B001","location"="FR"], 200.0) to "sensor3";

In range queries we can supply the exact epoch time in microseconds or we can use notation to express time relative to the current point in time. In this case we will ask for values a specific time.

nibble> get from "sensor3" since 1599069856546115;
[
{
"timestamp": 1599071536163401,
"tag": [ { "serial": "B001" }, { "location": "FR" } ],
"value": 200
},
{
"timestamp": 1599071536163377,
"tag": [ { "serial": "A001" }, { "location": "FR" } ],
"value": 100
},
{ "timestamp": 1599071509125991, "value": 30 },
{ "timestamp": 1599071509125973, "value": 20 },
{ "timestamp": 1599071509125956, "value": 10 },
{
"timestamp": 1599069856546115,
"tag": [ { "serial": "B001" }, { "location": "UK" } ],
"value": 40
}
]

If want to further restrict the data returned we can filter tags by their names and values.

nibble> get from "sensor3" since 1599069856546115 filter "location" is "FR";
[
{
"timestamp": 1599071536163401,
"tag": [ { "serial": "B001" }, { "location": "FR" } ],
"value": 200
},
{
"timestamp": 1599071536163377,
"tag": [ { "serial": "A001" }, { "location": "FR" } ],
"value": 100
}
]

It is possible to combine filters to further restrict the result. Filters are combined by a logical AND apart from when they have the same named tag in which case they form a logical OR. The result of any logical OR will be combined with any remaining terms through a logical AND. So in the case below we are doing

("serial" is "B001" AND ("location" is "UK" OR "location" is "FR")).

nibble> get from "sensor3" since 1599069856546115 filter "serial" is "B001", "location" is "FR", "location" is "UK";
[
{
"timestamp": 1599071536163401,
"tag": [ { "serial": "B001" }, { "location": "FR" } ],
"value": 200
},
{
"timestamp": 1599069856546115,
"tag": [ { "serial": "B001" }, { "location": "UK" } ],
"value": 40
}
]

As previously mentioned we can query based on time relative to the current point in time. In this case we will ask for data since 10 minutes ago. We also introduce the ability to carry out basic aggregation calculations on the data returned.

nibble> get min from "sensor1" since 10m;
{ "min": 42 }
nibble> get from "sensor1" since 1d;
[
{
"timestamp": 1580662264279578,
"data": { "serial": "A001", "value": 43 }
},
{ "timestamp": 1580662246471956, "data": { "value": 42 } }
]

We can easily combine the data from multiple time series into one result. This is particularly useful when we want to carry on some aggregation functions on the result. However, unless we add information in the tags we will not know which values belong to which time series once combined.

nibble> get from "sensor1", "sensor2" since 1000s;
[
{
"timestamp": 1599056827686944,
"tag": [ { "serial": "A001" } ],
"value": 43
},
{ "timestamp": 1599056683482166, "value": 42.1 },
{ "timestamp": 1599056677483335, "value": 42 }
]

Sometimes we just want to get the most recent values added to a time series without filtering on specific times.

nibble> get from "sensor2" last 10;
[ { "timestamp": 1580662256258819, "data": { "value": 42.1 } } ]
nibble> get from "sensor1" range 10days to 0days;
[
{
"timestamp": 1580662264279578,
"data": { "serial": "A001", "value": 43 }
},
{ "timestamp": 1580662246471956, "data": { "value": 42 } }
]

As with other queries we can delete values using both since and range filtering syntax. Range filtering works by taking the term the furthest back in time up to a more recent point in time. We can express the current time using the terms 0 seconds, 0 hours or 0 days. We can also apply tag filtering to restrict the values deleted.

nibble> delete from "sensor2" range 10m to 5m;
nibble> delete from "sensor1" range 5s to 0s filter "serial" is "A001";