Search
The rQL reference
One language, two places it runs: the server compiles it to a predicate over the live ingest stream, and to a scan over Parquet for history. There is one parser behind both, so a query means the same thing either way.
Terms
| Form | Matches |
|---|---|
| k=v | Equality. service=api |
| k:v | Case-insensitive substring. path:/health |
| k:~re | Regular expression. req.path:~"^/v1/" |
| k>n | Comparison, with <, >= and <= as well. latency_ms>500 |
| k=* | The key exists at all. trace_id=* |
| k=null | It does not. |
| timeout | A bare word is full text across the message and the original line. Quote it to match a phrase. |
Combining
Terms are ANDed unless you write OR. - and
NOT negate the term they precede, and parentheses group.
level>=ERROR service=api "connection timeout"
-path:/health AND (region=us-east-1 OR region=us-west-2)
latency_ms>500 req.path:~"^/v1/"
trace_id=*
Severity
level compares by severity, not alphabetically —
level>=ERROR matches FATAL too, which is what you meant. It holds
whatever the door it came through supplied: a JSON level key, an OTLP
severity number, or a syslog priority. The same query works across all of them
without anyone writing a parser.
Types
Values are coerced to the column's type. Quoting suppresses that, which is how you reach a string that looks like a number.
status=200 the number
status="200" the string
Fields
The envelope is always there — timestamp, stream, level, message, host, sequence and the original line. Everything else is whatever your logs happened to contain: each root-level JSON key becomes its own typed column, and nested objects are kept as JSON you can path into.
{"level":"error","msg":"upstream timeout","service":"api","latency_ms":30004,"req":{"path":"/v1/checkout"}}
level>=ERROR the envelope's severity
service=api a promoted column
latency_ms>30000 the number, compared
req.path:/checkout into the nested object
"upstream timeout" the text of the line
Two files written a week apart with completely different keys reconcile by name at read time, so a field that only started appearing yesterday is still queryable across the whole range.
Time range
The range is the partition pruner, not decoration. It is always applied — a query
without one gets the last 24 hours injected — and every response reports the window
it used along with how many files and rows the query implied reading, so a slow
search can explain itself. Durations take d and w as well
as Go's own units, because --retention 720h is nobody's idea of clear.
SQL
When rQL runs out, post SQL. logs is a view over the pruned files, and
the query runs read-only in a DuckDB sandbox that can see nothing but your data
directory. On a server started with --auth-token, this route wants the
token like every other one: Authorization: Bearer …, or
X-Rtail-Token for clients that reserve the first.
{
"sql": "SELECT a_service, count(*) n, quantile_cont(a_latency_ms, 0.95) p95 FROM logs WHERE level = 'ERROR' GROUP BY 1 ORDER BY n DESC",
"from": "-6h"
}
Keyboard
| / or ⌘K | Focus the query editor. |
| ⌘⏎ | Run it. Plain ⏎ is a newline — it is an editor. |
| j / k | Move between events. |
| ⎋ | Collapse everything. |