PQL - The PicoTorrent Query Language¶

PicoTorrent ships with an embedded query language (called PQL) which makes it possible to filter the torrent list view in order to quickly show relevant information.

The query language is somewhat based on SQL but is designed to make querying torrents easy. The building blocks of PQL are Types, Fields, Units and Operators.

Types¶

PQL supports two primitive and two compound types:

Primitive Types¶

NUMBER - signed integer or floating-point number;
STRING - doublequoted series of Unicode characters.

Compound Types¶

SIZE - consists of a NUMBER type value followed by zero or one size unit. See type examples;
SPEED - consists of a NUMBER type value followed by zero or one speed unit. See type examples.

Fields¶

These are the fields available to query:

dl (SPEED type) - the current downloading speed;
name (STRING type) - the name of the torrent as seen in the UI;
progress (NUMBER type) - the current progress in percents;
size (SIZE type) - the total wanted size - e.g. total size excluding skipped files;
status (STRING type) - the torrent current status. This field accepts the following string values:
- downloading;
- error;
- paused;
- queued - either for downloading or uploading;
- seeding;
- uploading;
ul (SPEED type) - the current uploading speed.

Units¶

PQL use the JEDEC Standard 100B.01 prefixes for its units of size and speed. The units are used unquoted and are case insensitive. They can be separated with an optional white space from the preceding numeric value.

Units of Size¶

Used in conjunction with the size field and together form SIZE type.

b - bytes, default unit of size if not other provided;
kb - Kilobytes;
mb - Megabytes;
gb - Gigabytes.

Units of Speed¶

Used in conjunction with dl and ul fields and together form SPEED type.

bps - bytes per second, default unit of speed if not other provided;
kbps - Kilobytes per second;
mbps - megabytes per second;
gbps - Gigabytes per second.

Operators¶

PQL supports a handful of operators to make filtering flexible.

Logical Operators¶

There are two logical operators:

and - Logical And;
or - Logical Or.

Comparison Operators¶

In PQL you can use 6 comparison operators:

< - less than;
<= - less than or equal to;
> - greater than;
>= - greater than or equal to;
= - equal;
~ - like. Case insensitive string matching.

Examples¶

Example of SIZE type with NUMBER value equal to 5 and size unit equal to kb.
```
5kb
```
Example of SPEED type NUMBER value equal to 10 and speed unit equal to kbps.
```
10kpbs
```
Torrents larger than 1GB.
```
size > 1gb
```
Torrents where the name contains ubuntu.
```
name ~ "ubuntu"
```
Torrents with either 1080p or 720p in the name.
```
name ~ "1080p" or name ~ "720p"
```
Torrents downloaded at least to 90%.
```
progress >= 90
```
Torrents larger than 1GB that are currently downloading.
```
size > 1gb and status = "downloading"
```
Torrents that are currently queued.
```
status = "queued"
```
Torrents that are downloading with more than 10 mbps.
```
dl > 10mpbs
```
Torrents that are uploading with more than 5 mbps.
```
ul > 5mpbs
```