Skip to main content

query

Run a PPL query against a server, local files or standard input.

lynxdb query '<PPL query>' [flags]

Alias: q

Every query starts with a source, for example source=main, and continues with | command stages:

lynxdb query 'source=main level=ERROR | stats count() as errors by host | sort - errors'

Quote the query with single quotes so the shell leaves |, > and double-quoted strings alone. Several arguments are joined with spaces into one query.

Flags​

FlagShortDefaultModesDescription
--since-sserverRelative time range: 30s, 15m, 1h, 7d, 2w
--fromserverAbsolute start time (ISO 8601); needs --to
--toserverAbsolute end time (ISO 8601); needs --from
--timeout6mserverClient-side limit for the whole query, as a Go duration: 30s, 10m
--copyfalseserverCopy the result rows to the clipboard as TSV
--file-flocalLoad a file or glob pattern and query it in process
--rawfalselocalDo not detect a log format while loading
--sourcefile path or stdinlocalsource field of the loaded text lines
--sourcetypelocalsourcetype field of the loaded text lines
--output-oallWrite the result rows to a file instead of stdout
--analyzefalseallPrint an execution profile instead of the statistics line
--fail-on-emptyfalseallExit with code 6 when the query returns no rows
--explainfalseallPrint the compiled plans and exit without running the query

Flags marked "server" have no effect on a local query, and --copy fails with an error there. With --since, --from and --to absent, a server query covers all time unless the query sets its own range with earliest= and latest=.

A \G at the end of the query switches --format auto to vertical output, one field per line:

lynxdb query 'source=main level=ERROR | head 1 \G'

Server mode​

Without --file and with stdin attached to a terminal, lynxdb query sends the query to POST /api/v1/query on the server named by --server (see Query API).

lynxdb query 'source=main status>=500 | top 10 path' --since 24h
lynxdb query 'source=main | stats count() by host' \
--from 2026-01-15T00:00:00Z --to 2026-01-16T00:00:00Z
lynxdb q 'source=main | timechart span=5m count() by level' --since 1h

The server syncs the events ingested so far before it runs the query, so a query sees everything ingested before it. Every query runs on the server as a job. The server answers inline when the job finishes within its query.sync_timeout; otherwise it answers with the job handle, and the CLI polls the job and prints the result when it finishes, until --timeout expires. lynxdb jobs lists the jobs.

The CLI picks local mode whenever stdin is a pipe. A script that runs under a pipe, such as a CI step, keeps server mode by redirecting stdin: lynxdb query '...' < /dev/null.

Local mode: files and stdin​

With --file, or when stdin is a pipe, the CLI runs the query without a server:

  1. It compiles the query first, so a query that does not compile fails before any input is read.
  2. It opens a database of its own in a temporary directory and loads every line of the input into the index main.
  3. It runs the query in process with the same engine the server uses, prints the result, and removes the directory.
lynxdb query --file access.log 'source=main | stats count() by status'
lynxdb query --file '/var/log/app/*.log' 'source=main level=ERROR | stats count() by source'
cat app.log | lynxdb query 'source=main | where response_time > 500 | stats count() by path'
zcat archive.log.gz | lynxdb query 'source=main status>=500 | top 10 path'

--file takes a path or a glob pattern; quote a glob so the shell does not expand it. Using --file and piped stdin together is an error.

Lines load the way POST /api/v1/ingest/raw takes them:

  • A line that is a JSON object is stored as it is: its members become fields, and the first of the time fields it holds becomes its time. It has no _raw.

  • Any other line becomes an event with the line in _raw, the timestamp found in the line as its time (the load time when there is none), its key=value pairs as fields, and the fields source (the file path, stdin or --source) and sourcetype (--sourcetype, absent by default).

  • The CLI reads the first 20 lines to detect a log format. When it finds Apache/Nginx combined log format, syslog or Docker JSON logs, it extracts that format's fields from the text lines as well (for combined: client_ip, ident, user, timestamp, request, method, uri, protocol, status, bytes, referer, user_agent) and says so on stderr:

      ℹ Detected Combined (100% of lines); fields are extracted while loading. Use --raw to disable.

--raw turns format detection off; the timestamp and key=value extraction still apply. Detection runs on the first file that matches --file and applies to all of them. A line longer than 1 MiB stops the load with an error.

A local query prints statistics to stderr, so stdout carries only rows:

lynxdb query --file access.log --format csv 'source=main | stats count() by level' > levels.csv

Plans: --explain​

--explain compiles the query in the CLI and prints the logical plan, the optimized plan and the optimizer rules that fired. It reads no input and contacts no server.

lynxdb query --explain 'source=main level=ERROR | stats count() as n by host | sort - n | head 3'
Logical plan:
Limit(3)
└─ Sort(n DESC NULLS LAST)
└─ Project(n, host)
└─ Aggregate(n = count() BY host)
└─ Filter(level = "ERROR")
└─ Scan(main)

Optimized plan:
TopN(3, n DESC NULLS LAST)
└─ Project(n, host)
└─ Aggregate(n = count() BY host)
└─ Filter(level = "ERROR")
└─ Scan(main) columns=[_time, host, level] prune=level = "ERROR"

Optimizer rules:
prune-scan x1
sort-limit-to-topn x1

To see how the server plans a query, with its result type, cost class and the fields it reads, use lynxdb explain. Pipeline execution explains the operators in these plans.

Profiles: --analyze​

--analyze prints an execution profile to stderr after the rows, in place of the statistics line: the time spent in each phase and the total, and for a local query the rows loaded and returned.

lynxdb query 'source=main level=ERROR | stats count() by host' --analyze
lynxdb query --file access.log 'source=main level=ERROR | stats count() by host' --analyze
  ══════ Query Profile ══════

Phase Breakdown:
parse 1µs 0% █
exec 187µs 0% ████████████████████
serialize 80µs 0% ████████
──────────
total 39ms

Rows: 1,000 scanned → 5 results

With --format json, the profile is printed as JSON.

Errors​

A query that does not compile prints the query with a caret under the position and the compiler's message, then exits with code 4:

lynxdb query --file access.log 'source=main | where status >'
  source=main | where status >
^

✖ ERROR: syntax error at line 1, column 29: expected an expression

Unsupported commands and functions fail the same way, with a message that names what is missing. PPL errors lists every error code. Exit codes lists the other failures.

Output​

Rows go to stdout in the format chosen by --format; statistics and hints go to stderr.

  • On a terminal, auto prints a table, or a bare value for a single-column, single-row result, followed by a footer with the row count and the time the query took. --verbose adds the full statistics block.
  • When stdout is not a terminal, auto prints one JSON object per row and the statistics as one JSON line on stderr. --no-stats drops the statistics.
lynxdb query 'source=main | stats count() by host' --format csv > hosts.csv
lynxdb query 'source=main level=ERROR | fields _time, host, path' --since 1h | jq -r .path
lynxdb query 'source=main | stats count() as n by status | sort - n' --format table

Output Formats describes each format.

Scripting​

# Fail a CI step when errors appear
lynxdb query 'source=main level=ERROR' --since 15m --fail-on-empty --quiet < /dev/null > /dev/null \
&& echo "errors in the last 15 minutes"

# Pull rows from the server, then aggregate them locally
lynxdb query 'source=main status>=500 | fields _raw' --since 1h --format raw < /dev/null \
| lynxdb query 'source=main | stats count() by path'

# Copy a result to paste into a spreadsheet
lynxdb query 'source=main | stats count() by host' --copy

See also​