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.
`profiles`	Folded profile stacks, one row per sampled call path.

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 \| deadline"`
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`, `is_error`, `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`
`profiles`	`time`, `service`, `profile_type`, `unit`, `value`, `trace_id`, `span_id`

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 on spans, logs, and metrics:

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

Unknown fields on spans, logs, metrics, and profiles resolve to telemetry attribute maps when the source supports attribute maps. Profiles only expose string attributes by bare key, such as host_name; resource. and res. prefixes are not valid on the profiles source. 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