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.

One line
{"level":"error","msg":"upstream timeout","service":"api","latency_ms":30004,"req":{"path":"/v1/checkout"}}
Terms that reach it
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.

POST /v1/sql
{
  "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.

← Back to the landing page