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>

👋
If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].