SRQL Reference

SRQL (ServiceRadar Query Language) is a compact key:value language for querying devices, events, logs, flows, and telemetry. This page is the complete reference: grammar, queryable entities, filterable fields, operators, time syntax, and aggregation.

New to SRQL? Start with the SRQL Tutorial for a guided walkthrough, or jump to the SRQL Cookbook for ready-made recipes.

Overview

SRQL is parsed and executed by the Rust-based SRQL engine (rust/srql). The engine parses the key:value syntax into a query AST, plans it against ServiceRadar's streaming schema, translates it to PostgreSQL via Diesel, and returns consistently shaped JSON results.

Use SRQL to:

• Select a data domain with in:<entity>.
• Filter with key:value pairs, wildcards, lists, ranges, and negation.
• Scope to a time window with time:.
• Shape results with sort:, limit:, and pagination cursors.
• Summarize with stats: aggregations or bucket: downsampling.

Query structure

A query is a whitespace-separated list of tokens. Every token is either the in: selector, a reserved keyword (time, sort, limit, stats, etc.), or a key:value filter. Tokens may appear in any order, but every query must include exactly one in: selector.

in:<entity> [key:value ...] [time:<window>] [sort:<field>[:dir]] [limit:<n>] [stats:<expr>]

Example:

in:devices vendor_name:Cisco hostname:%core% time:last_7d sort:last_seen:desc limit:20

Tokenization rules

• Tokens are separated by whitespace.
• Wrap values containing spaces in quotes: vendor_name:"Axis Communications". Single quotes, double quotes, and backticks are all accepted.
• Parentheses ( ) and brackets [ ] group list and range values; whitespace inside them does not split the token.
• Keys are case-insensitive and lowercased before matching.

The in: selector

in:<entity> chooses which data domain to query. The entity name is case-insensitive, and most entities accept several aliases (for example in:devices and in:device are equivalent).

See Queryable entities for the full list of entities, aliases, and fields.

Operators

SRQL infers the operator from the value you write.

Form	Operator	SQL behavior
field:value	equals	=
!field:value	not equals	<>
field:%text%	contains	ILIKE (case-insensitive)
!field:%text%	does not contain	NOT ILIKE
field:(a,b,c)	one of	IN (...)
!field:(a,b,c)	none of	NOT IN (...)
field:>n	greater than	>
field:>=n	greater than or equal	>=
field:<n	less than	<
field:<=n	less than or equal	<=

Notes:

• Negation applies to the key, written as !key:value. Writing key:!value is not supported.
• AND is implicit: listing multiple filters means all of them must match.
• OR for a single field is the list form field:(a,b). There is no general OR keyword across different fields.
• Ranges are expressed by repeating a numeric field with two comparison bounds: usage_percent:>80 usage_percent:<95.
• List filters accept at most 200 values.

Wildcards

% is the wildcard character for string matching. It matches any run of characters and emits a case-insensitive ILIKE (or NOT ILIKE when negated).

in:devices hostname:router-%      # starts with "router-"
in:devices hostname:%.lab          # ends with ".lab"
in:devices hostname:%core%         # contains "core"

A value with no % is matched for exact equality.

Time scoping

Use time: (alias timeFrame:) to constrain time-series queries. If you omit a time window, the engine applies a default window.

Relative windows

time:last_<number><unit> — units are m (minutes), h (hours), d (days), and y (years).

in:events time:last_30m
in:logs time:last_24h
in:flows time:last_7d

Shortcuts

in:events time:today
in:events time:yesterday

Absolute ranges

Bracket syntax [start,end] accepts RFC 3339 timestamps. Leave a side blank for an open-ended range.

in:events time:[2026-01-01T00:00:00Z,2026-01-02T00:00:00Z]
in:events time:[2026-01-01T00:00:00Z,]      # open end
in:events time:[,2026-01-02T00:00:00Z]      # open start

Limits

Most queries are capped at a 90-day time range. Aggregated metric queries (a metric entity combined with stats: or bucket:) may span a longer window because they are served from pre-computed hourly rollups.

Sorting and pagination

• sort:<field>[:asc|:desc] — orders results. Direction defaults to desc. Multiple sort keys are comma-separated: sort:time:desc,bytes_total. order: is an accepted alias for sort:.
• limit:<n> — caps the number of rows. Must be a positive integer; the engine enforces a configured maximum.
• Pagination is cursor-based. Each response includes next_cursor / prev_cursor values that callers pass back to page through results.

Aggregation with stats

stats: collapses rows into summary values.

stats:<function>(<field>) as <alias> [by <field>]

• Functions: count, sum, avg, min, max.
• count() takes no field; the others require one.
• as <alias> names the result column.
• by <field> groups results (the SQL GROUP BY).
• Combine multiple aggregations with commas: stats:"count() as total, avg(value) as average".

in:devices stats:count() as total by type
in:cpu_metrics time:last_24h stats:avg(usage_percent) as avg_cpu
in:flows time:last_1h stats:sum(bytes_total) as bytes by src_ip sort:bytes:desc

Downsampling with bucket

For time-series charts, bucket: groups rows into fixed time buckets.

• bucket:<duration> — bucket width using s|m|h|d suffixes (e.g. bucket:5m).
• agg:<function> — bucket aggregation: avg (default), min, max, sum, count, or rate (per-second rate of change for counters).
• series:<field> — splits buckets into one series per distinct value.
• value_field:<field> — which numeric field to aggregate.

in:timeseries_metrics time:last_7d bucket:5m agg:avg series:metric_name
in:flows time:last_1h bucket:5m agg:sum value_field:bytes_total

Queryable entities

Target data with in:<entity>. Each entity exposes its own set of filterable fields; using a field that the entity does not support returns an unsupported filter field error naming the offending field.

Entity (in:)	Aliases	Description
devices	device, device_inventory	Device inventory and current state
events	activity	Normalized OCSF events and activity
logs	—	Application and system logs (OpenTelemetry)
flows	flow, network_activity	NetFlow / network activity records
services	service	Observed services and their availability
gateways	gateway	Gateway/agent operational state
interfaces	interface, discovered_interfaces	Discovered network interfaces (time-series)
bmp_events	bmp_event, bmp_routing_events	BGP Monitoring Protocol (BMP) routing events
alerts	alert	Generated alerts
cpu_metrics	cpu	CPU utilization time-series
memory_metrics	memory	Memory utilization time-series
disk_metrics	disk	Disk utilization time-series
process_metrics	processes	Per-process CPU/memory time-series
timeseries_metrics	timeseries	Generic time-series metrics (incl. SNMP)
snmp_metrics	snmp	SNMP-collected metrics
rperf_metrics	rperf	rperf network performance metrics (shares the time-series schema)
otel_metrics	metrics	OpenTelemetry span-derived metrics
traces	otel_traces, trace_spans	OpenTelemetry trace spans

The engine also exposes specialized entities — device graph (device_graph), device updates (device_updates), Wi-Fi site mapping (wifi_sites, wifi_access_points, …), virtualization (virtualization_hosts, virtualization_guests, …), and field-survey datasets. They use the same key:value grammar described above.

Filterable fields by entity

Each subsection lists the fields you can filter and sort on for that entity. The subsection heading matches the in: name used to select the entity.

devices

Field	Aliases	Description
device_id	uid	Unique device identifier
hostname		Device hostname (supports wildcards)
ip		IP address — supports wildcards, CIDR (10.0.0.0/8), and ranges (10.0.0.10-10.0.0.50)
mac		MAC address (normalized; supports wildcards)
gateway_id	gateway	Associated gateway ID
agent_id		Associated agent ID
type	device_type	Device type
type_id		Numeric device type ID
vendor_name	vendor	Device vendor
model		Device model
risk_level	risk	Risk classification
is_available	available	Currently reachable (true/false)
is_active	active	Lifecycle state (true/false)
discovery_sources		Sources that discovered the device (array; list form)
tags		Device tags (array; list form). Sub-key form: tags.<key>:<value>
metadata.<key>		Match an arbitrary metadata key, e.g. metadata.integration_type:armis

Sortable fields include hostname, ip, first_seen / first_seen_time, last_seen / last_seen_time, and type_id.

Control tokens: include_inactive:true returns devices regardless of lifecycle state; include_deleted:true includes soft-deleted records.

events

Field	Aliases	Description
id		Event identifier
device_id	uid, source_device_uid	Associated device
class_uid		OCSF class UID
category_uid		OCSF category UID
type_uid		OCSF type UID
activity_id		Activity ID
activity_name		Activity name
severity_id		Numeric severity ID
severity		Severity label
message	short_message	Event message
log_name		Log name or subject
log_provider		Log provider
log_level		Log level
status		Status label
status_id		Numeric status ID
status_code		Status code
status_detail		Status detail
trace_id		OpenTelemetry trace ID
span_id		OpenTelemetry span ID

Sortable fields: time (aliases event_timestamp, timestamp).

logs

Field	Aliases	Description
id		Log record identifier
device_id	uid, source_device_uid	Associated device
gateway_id		Associated gateway ID
agent_id		Associated agent ID
trace_id		OpenTelemetry trace ID
span_id		OpenTelemetry span ID
service_name	service	Emitting service
service_version		Service version
service_instance		Service instance identifier
source		Log source
scope_name		Instrumentation scope name
scope_version		Instrumentation scope version
severity_text	severity, level	Severity text (e.g. error, warn)
severity_number		Numeric severity
body	message	Log message body

Sortable fields: timestamp, severity_number.

flows

Field	Aliases	Description
device_id		Associated device
src_endpoint_ip	src_ip	Source IP (supports wildcards)
dst_endpoint_ip	dst_ip	Destination IP (supports wildcards)
src_cidr		Source CIDR containment match
dst_cidr		Destination CIDR containment match
src_endpoint_port	src_port	Source port
dst_endpoint_port	dst_port	Destination port
protocol_name		Protocol name
protocol_num	proto	Protocol number
protocol_group	proto_group	Protocol group
direction		Flow direction
flow_source	collector	Originating collector
app		Derived application classification label
sampler_address		Flow exporter / sampler address
exporter_name		Resolved exporter name
in_if_name		Ingress interface name
out_if_name		Egress interface name
in_if_speed_bps		Ingress interface speed (bps)
out_if_speed_bps		Egress interface speed (bps)

Sortable fields: time, bytes_total, packets_total, bytes_in, bytes_out, packets_in, packets_out.

services

Field	Aliases	Description
service_name	name	Service name
service_id	uid	Service identifier
service_type	type	Service type
gateway_id		Associated gateway ID
agent_id		Associated agent ID
partition		Partition identifier
message		Status message
available		Availability (true/false)

Sortable fields: timestamp / last_seen, service_name / name, service_type / type.

gateways

Field	Description
gateway_id	Gateway identifier
status	Gateway status
component_id	Component identifier
registration_source	Registration source
spiffe_identity	SPIFFE identity
created_by	Creator identifier
is_healthy	Health status (true/false)

Sortable fields: last_seen, first_seen, first_registered, gateway_id, status, agent_count, checker_count, updated_at.

interfaces

Interface observations are stored as time-series data. Use latest:true to return the most recent record per interface.

Field	Aliases	Description
device_id		Device identifier
device_ip	ip	Device IP address
interface_uid		Stable interface identifier (per device)
gateway_id		Associated gateway ID
agent_id		Associated agent ID
if_name		Interface name
if_descr	description	Interface description
if_alias		Interface alias
if_index		Interface index (ifIndex)
if_type		Interface type identifier (ifType)
if_type_name		Interface type (human-readable)
interface_kind		Classification (physical, virtual, loopback, tunnel, …)
if_phys_address	mac	Physical (MAC) address
if_admin_status	admin_status	Administrative status
if_oper_status	oper_status, status	Operational status
if_speed	speed, speed_bps	Interface speed
mtu		Interface MTU
duplex		Interface duplex
ip_addresses	ip_address	IP addresses assigned to the interface (list form)

Sortable fields: timestamp, device_ip, device_id, interface_uid, if_name, if_descr, if_index, if_type, if_type_name, interface_kind, speed_bps, mtu.

bmp_events

in:bmp_events is how you query BGP routing data — peer events and prefix advertisements collected via the BGP Monitoring Protocol (BMP).

Field	Description
id	Event identifier
event_type	BMP event type
router_id	Reporting router ID
router_ip	Reporting router IP
peer_ip	BGP peer IP
peer_asn	BGP peer ASN (numeric)
local_asn	Local ASN (numeric)
prefix	Advertised/withdrawn prefix
message	Event message
raw_data	Raw event payload
severity_id	Numeric severity ID

Sortable fields: time (aliases event_timestamp, timestamp), created_at, severity_id.

alerts

Field	Description
id	Alert identifier
title	Alert title
description	Alert description
severity	Alert severity
status	Alert status
source_type	Source type
source_id	Source identifier
device_uid	Associated device
agent_uid	Associated agent
metric_name	Metric that triggered the alert
comparison	Comparison operator used
acknowledged_by	Who acknowledged the alert
resolved_by	Who resolved the alert
escalation_reason	Escalation reason

Sortable fields: triggered_at / timestamp, severity, status, title.

cpu_metrics

Field	Description
gateway_id	Associated gateway ID
agent_id	Associated agent ID
host_id	Host identifier
device_id	Device identifier
partition	Partition identifier
cluster	Cluster name
label	Label
core_id	CPU core identifier
usage_percent	CPU usage percentage
frequency_hz	CPU frequency in Hz

Sortable fields: timestamp, usage_percent, gateway_id, device_id, host_id, partition, core_id.

memory_metrics

Field	Description
gateway_id	Associated gateway ID
agent_id	Associated agent ID
host_id	Host identifier
device_id	Device identifier
partition	Partition identifier
usage_percent	Memory usage percentage
total_bytes	Total memory in bytes
used_bytes	Used memory in bytes
available_bytes	Available memory in bytes

Sortable fields: timestamp, usage_percent, gateway_id, device_id, host_id.

disk_metrics

Field	Description
gateway_id	Associated gateway ID
agent_id	Associated agent ID
host_id	Host identifier
device_id	Device identifier
partition	Partition identifier
mount_point	Filesystem mount point
device_name	Device name
usage_percent	Disk usage percentage
total_bytes	Total disk space in bytes
used_bytes	Used disk space in bytes
available_bytes	Available disk space in bytes

Sortable fields: timestamp, usage_percent, gateway_id, device_id, host_id, mount_point.

process_metrics

Field	Description
gateway_id	Associated gateway ID
agent_id	Associated agent ID
host_id	Host identifier
device_id	Device identifier
partition	Partition identifier
pid	Process ID
name	Process name
status	Process status
start_time	Process start time
cpu_usage	Process CPU usage
memory_usage	Process memory usage

Sortable fields: timestamp, cpu_usage, memory_usage, pid, name.

timeseries_metrics

in:timeseries_metrics (and the snmp_metrics / rperf aliases that share this schema) cover generic time-series data, including SNMP counters.

Field	Description
gateway_id	Associated gateway ID
agent_id	Associated agent ID
metric_name	Name of the metric
metric_type	Type of metric
device_id	Device identifier
target_device_ip	Target device IP address
partition	Partition identifier
if_index	Interface index
value	Metric value

Sortable fields: timestamp, gateway_id, metric_name, metric_type, device_id, value.

otel_metrics

Field	Aliases	Description
trace_id		OpenTelemetry trace ID
span_id		Span identifier
service_name	service	Emitting service
span_name		Span name
span_kind		Span kind
metric_type	type	Metric type
component		Component name
level		Level
http_method		HTTP method
http_route		HTTP route
http_status_code		HTTP status code
grpc_service		gRPC service name
grpc_method		gRPC method name
grpc_status_code		gRPC status code
is_slow		Slow-request flag (true/false)

Sortable fields: timestamp, service_name / service, metric_type / type.

traces

Field	Aliases	Description
trace_id		OpenTelemetry trace ID
span_id		Span identifier
parent_span_id		Parent span identifier
service_name		Emitting service
service_version		Service version
service_instance		Service instance identifier
scope_name		Instrumentation scope name
scope_version		Instrumentation scope version
name	span_name	Span name
status_message		Status message
status_code		Numeric status code
kind	span_kind	Span kind (integer)

Sortable fields: timestamp, start_time_unix_nano, end_time_unix_nano, service_name.

Error handling

Message	Cause / fix
queries must include an in:<entity> token	Add an in:<entity> selector.
unsupported entity '<x>'	The entity name is not recognized. See Queryable entities.
unsupported filter field	The field is not valid for the chosen entity. Check Filterable fields by entity.
unsupported time token / invalid time literal	The time: value is malformed. Use last_<n><unit>, today/yesterday, or [start,end].
time range cannot exceed 90 days	Narrow the window, or use a metric entity with stats:/bucket: for longer ranges.
invalid limit / limit must be a positive integer	limit: requires a positive integer.
expected scalar value / expected list value	Operator/value mismatch — e.g. a list value where a scalar is expected.

See also

• SRQL Tutorial — step-by-step introduction for new users.
• SRQL Cookbook — task-oriented copy-paste recipes.