OQL Basics

OQL is a piped query language. Data queries start with GET; metadata lookups start with SHOW.

GET logs | RANGE 15m | FILTER severity = 'ERROR' | SORT timestamp DESC | LIMIT 50
SHOW logs attributes

Keywords are case-insensitive. Identifiers and string values are case-sensitive. String literals use single quotes.

Datasets

Dataset	Meaning
logs	Log records.
metrics	Metric points and histogram payloads.
traces	Persisted root trace summaries.
spans	Individual spans in the traces database.

Pipeline Order

Data queries use this order:

GET -> RANGE -> FILTER -> STATS -> BY -> HAVING -> PICK -> SORT -> LIMIT

RANGE is required for GET queries. LIMIT, when present, must be last. After PICK, only SORT and LIMIT may follow.

Use FILTER for both core fields and dynamic OpenTelemetry attributes. Commas inside a FILTER are treated as AND.

GET logs
| RANGE 1h
| FILTER severity = 'ERROR', service = 'checkout-api', http.status_code >= 500
| SORT timestamp DESC
| LIMIT 100

Ranges

GET metrics | RANGE 15m
GET traces | RANGE 1h
GET logs | RANGE 7d

Absolute ranges are also supported:

GET logs | RANGE '2026-07-09T10:00:00Z' TO '2026-07-09T11:00:00Z'

Supported duration units are ns, ms, s, m, h, d, and w. Integer and exact decimal durations are accepted in ranges and BY ... EVERY.

Common Operators

Operator	Example
= / !=	FILTER service = 'api'
> / >= / < / <=	FILTER trace_duration > 500ms
IN (...)	FILTER severity IN ('ERROR', 'WARN')
LIKE / NOT LIKE	FILTER message LIKE '%timeout%'
ILIKE / NOT ILIKE	FILTER message ILIKE '%timeout%'
GLOB / NOT GLOB	FILTER http.route GLOB '/api/*'
IS NULL / IS NOT NULL	FILTER trace_id IS NOT NULL

Boolean operators AND, OR, and parentheses are supported.

Aggregation

Use STATS for aggregation and BY for grouping. EVERY adds time buckets.

GET logs
| RANGE 1h
| STATS count() -> count
| BY severity EVERY 1m
| SORT time_bucket ASC

Supported aggregate functions include count(), count_distinct(field), avg(field), sum(field), min(field), and max(field).

Metadata Queries

SHOW queries are useful for discovering metric names and filter attributes. They may optionally include one RANGE stage.

SHOW logs attributes
SHOW logs attribute_values('service.name')
SHOW metrics
SHOW metrics attributes | RANGE 1h
SHOW traces attributes
SHOW spans attributes

Only RANGE may follow SHOW.

Query API

The dashboard also exposes a general-purpose OQL endpoint:

curl -s -X POST http://localhost:8080/api/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"GET logs | RANGE 15m | LIMIT 10"}'

Successful responses are JSON arrays of row objects. Invalid queries return HTTP 400 with an error field.