You can use fctl to query data from the Formant cloud. This is useful to script data download from the cloud to a file on your computer.

Query command syntax and flags

You can query data using the following syntax:

fctl query <flags>

You'll want to narrow down your query to the data set you're interested in. Use the following flags to filter your query.

🚧
Running fctl query alone, without filtering your query, may return an extremely large data set. Filtering your query with flags is highly recommended.

Flag	Usage
`-a`, `--aggregate`	Aggregate level for your query. Valid inputs: `year`, `month`, `week`, `day`, `hour`, `minute`, `second`.
`-c`, `--concat`	Used in conjunction with `--download`. If the downloaded file is a video, concatenates the downloaded video files to a single file.
`-d`, `--device`	Name of the device whose stream data you want to query.
`--download`	Download query results to a file. Only works for the following data types: video, pointcloud, image, file. To download video, make sure FFmpeg is installed. Video files are downloaded in three-second chunks. To stitch these three-second chunks into a single, continuous video file, use the `--concat` flag. You can download other file types using command line syntax such as `>`. See the Examples section for more details.
`--start`	Start time of the data range you want to query, in RFC3339 format (`YYYY-MM-DDThh:mm:ss`, e.g. `2024-02-05T15:28:00`).
`--end`	End time of the data range you want to query, in RFC3339 format (`YYYY-MM-DDThh:mm:ss`, e.g. `2024-02-05T15:29:00`).
`-f`, `--follow`	Execute this command periodically (every 3 seconds).
`-h`, `--help`	Display detailed help for `fctl query` command.
`-o`, `--output`	Output format. Valid inputs: `json`,`csv`,`table`
`--seek`	Seek back in time until data is found.
`-s`, `--stream`	Name of the stream whose data you want to query.
`-t`, `--tags` string	Set of tags you want to query. (e.g. `"k1:v1,v2;k2:v3"`)
`--type`	Stream type you want to query.

Examples

Query one stream across all devices

Let's use $.agent.health as an example. We will query all data from $.agent.health, across all devices, over the last two hours:

fctl query --stream $.agent.health --start 2024-02-05T13:51:00 --end 2024-02-05T15:51:00

Our result will look like this:

  2024-02-05T08:57:48.534-05:00 | walter      | $.agent.health | health | {"clockSkewMs":1,"status":"operational"}     | {"manufacturer":"boston-dynamics","type":"spot"}  
  2024-02-05T08:57:49.535-05:00 | walter      | $.agent.health | health | {"clockSkewMs":1,"status":"operational"}     | {"manufacturer":"boston-dynamics","type":"spot"}  
  2024-02-05T08:57:50.537-05:00 | walter      | $.agent.health | health | {"clockSkewMs":1,"status":"operational"}     | {"manufacturer":"boston-dynamics","type":"spot"}  
  2024-02-05T08:57:51.538-05:00 | walter      | $.agent.health | health | {"clockSkewMs":1,"status":"operational"}     | {"manufacturer":"boston-dynamics","type":"spot"}

Query by tags

Suppose we want to query all data tagged device-type: spot or device-type: fido over the last two hours. Our query will look like this:

fctl query --tags 'device-type:spot,fido' --start 2024-02-05T13:51:00 --end 2024-02-05T15:51:00

Query video from one device

📘
To download and concatenate video files, you must first install FFmpeg.

Suppose we have a device called my-device and a video stream called video-1. We want to download 15 seconds of video data from yesterday, and merge the downloaded video to a single file. Our query will look like this:

fctl query --device my-device --stream video-1 --start 2024-02-04T15:56:00 --end 2024-02-04T15:56:15 --download --concat

Our output will be a file in the following directory:

./<device_name>/<stream_name>/<timestamp-of-first-datapoint>_concat.mp4

Save JSON query result to file

Suppose we want to query two hours of data from a stream called stream-1, get its output in JSON format, and save that to a new file called output.json. Our query will look like this:

fctl query --stream stream-1 --start 2024-02-05T14:02:00 --end 2024-02-05T16:02:00 --output json > output.json

Download files uploaded to image, pointcloud, or streams

Suppose we want to download all files uploaded to a stream called bags related to a device called my-device. Our query will look like this:

fctl query --device my-device --stream bags --download

Our output will be a set of files in the following directory:

./device_name>/<stream_name>/<files>