Skip to main content

Your First Query

LynxDB queries are written in OpenSearch PPL, the Piped Processing Language. A query names an index, then passes rows through commands separated by |, left to right.

The examples run over lines such as:

2025-01-15T08:00:00.105Z host=web-03 level=ERROR method=GET path=/api/v1/users status=502 user=grace response_time=786 bytes=32228 msg="GET /api/v1/users completed"

Run them on a file with lynxdb query --file access.log '<query>', or on a server with lynxdb query '<query>'.

Every query starts with a source. Terms after it keep only matching events:

source=main error
source=main "connection refused"
source=main level=ERROR host=web-*
source=main status>=500
source=main level IN (WARN, ERROR) NOT host=api-01

A bare word matches a whole token of the raw text, ignoring case. A field comparison such as level=ERROR is exact and case-sensitive. See Search semantics.

Filter with where​

Search terms belong to the source command. Later in the pipeline, filter with where and an expression:

source=main | where status >= 500 AND response_time > 700
source=main | where like(path, '/api/v1/auth%')
source=main | where level = "ERROR" OR status = 503

Aggregate with stats​

source=main | stats count()
source=main level=ERROR | stats count() as errors by host
source=main | stats count() as requests, avg(response_time) as avg_ms, p95(response_time) as p95_ms by host

Name an aggregate with as so later commands can refer to it. Unnamed, the column is called count().

Sort and limit​

source=main level=ERROR | stats count() as errors by path | sort - errors | head 3
errors,path
40,/api/v1/users
38,/api/v1/orders
35,/api/v1/search

sort - errors sorts descending; sort errors ascending. top 3 path returns the three most frequent values with their counts.

Choose columns​

source=main | fields host, status, msg
source=main | fields - _raw
source=main | rename response_time as rt

Compute fields with eval​

source=main
| stats count() as total, count(eval(status >= 500)) as errors by path
| eval error_pct = round(errors * 100.0 / total, 1)
| sort - error_pct
| head 3
error_pct,errors,path,total
25.5,28,/api/v1/users,110
24.8,25,/api/v1/health,101
22.5,27,/api/v1/orders,120

Write spaces around - and * in arithmetic: bytes * 8, not bytes*8. Integer division truncates, so multiply by 100.0 for a percentage.

Count over time​

source=main | timechart span=1m count() by level
source=main | stats count() by span(_time, 5m), host

See Time series.

Extract fields​

parse pulls fields out of text with named regular expression groups:

source=main
| parse msg '(?<verb>[A-Z]+) (?<route>\S+) completed'
| stats count() as n by verb
| sort - n
n,verb
260,PUT
251,GET
249,DELETE
240,POST

rex, grok and spath cover other cases; see Field Extraction.

Quick reference​

CommandPurposeExample
source=Read an index, search termssource=main level=ERROR
whereFilter rowswhere status >= 500
statsAggregatestats count() as n by host
evalCompute fieldseval kb = bytes / 1024.0
sortOrder rowssort - n
headLimit rowshead 10
fieldsKeep or drop columnsfields host, status
renameRename a columnrename response_time as rt
top / rareMost and least frequent valuestop 10 path
dedupKeep the first row per valuededup host
timechartAggregate over time bucketstimechart span=5m count() by level
parseExtract with a regexparse msg '(?<verb>[A-Z]+) .*'

Next steps​