How do I use the goliothctl tool to query my stream data from the command line?

The goliothctl command line tool can be used to query your device data. Let’s look at one simple example, and at one complex example that querys for very specific results.

Prerequisite: install goliothctl and authenticate

Before we begin, make sure you have followed our guide to install Golioth command line tools.

Once installed, confirm you have authenticated your goliothctl tool:

$ goliothctl login

Simple query using goliothctl

Query the time, deviceId, and all LightDB stream endpoints using the * wildcard:

goliothctl stream query -f "time" --field "deviceId" --field "*"

Note that this defaults to just the past four hours of readings. If you’d like to make it longer (or shorter) you can add the interval setting. Here I’m querying for 40 hours and have limited the results to ‘temp’ (the endpoint I use for temperature readings):

goliothctl stream query -f "time" --field "deviceId" --field "time" --interval 40h

Complex queries using goliothctl and JSON objects

You can use goliothctl with a file containing a JSON formatted query.

1. Use the query builder

The best way to create the query object is to use the Query Builder found in the LightDB Stream section of the Golioth web console.

On the left you can see the selected fields: time, deviceId, and temp. Below that i have decided to filter the temp value to only temperatures above 44.

Now click the JSON button in the lower left. You will see the JSON appear. Use the “Copy” button in the upper right to copy the JSON to your clipboard. Important: always use the copy button to ensure you receive a clean copy of the JSON.

2. Place your JSON query in a file

Save your JSON data to a file. I have named mine myquery.json.

3. Use your query file with goliothctl

Pipe the contents of your JSON file into goliothctl, using the --in flag to make sure that data is used:

cat myquery.json | goliothctl stream query --in --interval 40h

I have found that there was only 1 reported reading in the last 40 hours where my ESP32C3 core temperature rose above 44 degrees.

Futher Reading

Blog post: Prototype your data outputs with the Golioth Query Builder

Known limitations

The goliothctl tool doesn’t offer the ability to select a time range. So if you wanted to query for last Tuesday between 13:00 and 15:00, this tool is not the right choice. Instead, use the Golioth Web Console, or take at look at our FAQ on using the Golioth REST API.

1 Like