OQL Reference

OQL is a pipeline language. Every query starts with a source and then applies zero or more stages.

source | stage | stage

Sources

Source	Data
spans	Individual spans.
traces	Trace summaries from trace_index.
logs	Log records.
metrics	Metric points and rollups.

Stages

Stage	Example
where	where service == "api" and duration > 250ms
stats	stats p95(duration), count() by http.route, bin(1m)
top	top 10 by p95
sort	sort duration desc
limit	limit 100
fields	fields time, service, body

Stage order is constrained. Filtering and projection happen before aggregation; top, sort, and limit shape results after aggregation or listing.

Predicates

Form	Example
Comparison	duration > 250ms
Equality	service == "api"
Inequality	status_code != "ok"
Regex	`body =~ “timeout
Negative regex	body !~ "debug"
In list	http.status in (502, 503, 504)
Not in list	http.method not in ("GET", "HEAD")
Exists	peer.service exists
Contains	body contains "timeout"
Starts with	url.path startswith "/v1/"
Boolean logic	a == 1 and (b == 2 or c == 3)

Literals

Literal	Example
String	"api"
Number	42, 3.14
Boolean	true, false
Duration	250ms, 1s, 5m, 2h, 1d
Bytes	4MiB, 1536KiB
Severity	trace, debug, info, warn, error, fatal

Backtick-quote reserved words or unusual field parts:

spans | where `limit` == 1

Aggregations

The accepted aggregation function set is closed:

Function	Arguments	Notes
count()	none	Count rows.
count_if(predicate)	predicate	Count rows matching a predicate.
count_distinct(field)	any field	Approximate distinct count.
sum(field)	numeric field	Sum.
avg(field)	numeric field	Average.
min(field)	numeric field	Minimum.
max(field)	numeric field	Maximum.
stddev(field)	numeric field	Sample standard deviation.
p50(field)	numeric field	TDigest quantile, histogram path for eligible metrics.
p75(field)	numeric field	TDigest quantile on raw data.
p90(field)	numeric field	TDigest quantile, histogram path for eligible metrics.
p95(field)	numeric field	TDigest quantile, histogram path for eligible metrics.
p99(field)	numeric field	TDigest quantile, histogram path for eligible metrics.
rate() or rate(field)	optional numeric field	Metrics-only, sole aggregation.
latest(field)	any field	Value with latest timestamp.
heatmap(field)	numeric field	Sole aggregation. Only bin() grouping is allowed.

Grouping

Use fields and optionally one time bin:

spans | stats count() by service, bin(1m)

bin(auto) picks a bucket width from a fixed ladder and keeps the bucket count under the query limit. Explicit bins below 1s are rejected.

Fields

Common fields:

Source	Fields
spans	time, duration, trace_id, span_id, parent_span_id, name, kind, status_code, status_message, service, scope_name, scope_version
traces	time, duration, span_count, error_count, root_service, root_name, trace_id, service
logs	time, observed_time, severity, severity_number, severity_text, body, body_kind, event_name, trace_id, span_id, service, scope_name, scope_version
metrics	time, start_time, name, unit, value, service, point_kind, temporality, is_monotonic, scope_name, scope_version

Promoted span attributes:

http.request.method
http.method
http.route
http.response.status_code
http.status_code
http.status
url.path
rpc.system
rpc.method
db.system.name
db.system
db.operation.name
db.operation
messaging.system
peer.service
exception.type
exception_type

Resource attributes use the resource. or res. prefix:

spans | where resource.k8s.namespace.name == "prod"
logs | where res.host.name == "node-a"

Unknown fields on spans, logs, and metrics resolve to telemetry attribute maps when the source supports attribute maps. Unknown fields on traces are rejected.

Limits

Limit	Value
Maximum parenthesis depth	64
Maximum in list values	4096
Maximum explicit limit	1000000
Query execution timeout	15s
Aggregate scan budget	4000000000 rows
List scan budget	1000000000 rows
Default row limit	10000
Top series limit	50
Auto-bin bucket target	up to 240 buckets