Skip to main content
Lists answer which; aggregates answer how many. Add aggregate to a query and it returns one row per group instead of one row per record. How many hosts have each port open?

aggregate

A map of names you choose to { "fn", "field"?, "where"? }. Up to eight per query. An aggregate name cannot also be a group key.

Conditional aggregates

Give an aggregate its own where and it only counts the rows that match. One query then returns a whole matrix, every column computed over the same rows. Open findings per host, with a column per severity:
The query’s where applies first, then each aggregate’s own filter. An aggregate filter takes everything a where takes, including nested groups and relation tests.

groupBy

Up to three group keys. A key is a field marked groupable in Resources and fields, of the resource or of a related row:
Without groupBy, the query returns one row of totals:

having: filter the groups

where filters records before they are counted; having filters the groups after. Its fields are your group keys and aggregate names, and it takes the same shape as where (groups, not). Hosts with at least one critical or high finding:
having accepts eq, neq, in and notIn on every key, and gt, gte, lt, lte on numbers and times. Counts are compared as numbers ("value": "0"), group keys against their own type (an enum value, a port…).

Time series

Buckets

A time field groups by period with a bucket: hour, day, week or month.
A time field without a bucket cannot be a group key.

Filling empty buckets

By default a day with nothing in it simply has no row, which leaves holes in a chart. Add "fill": true and the query returns every bucket of the window, with 0 for the empty ones:
  • fill needs a window (the series spans it) and exactly one group key, a time with a bucket.
  • Rows come in time order, and limit defaults to the number of buckets.
  • count, countDistinct and sum read 0 in an empty bucket; min, max and avg read null.
  • The series must fit in the row limit: 14 days by day is fine, a year by hour is not. Use a larger bucket or a shorter window.

Time zones

Buckets are cut in UTC unless the batch says otherwise. A day in Hanoi starts seven hours before a day in UTC, so a daily chart for a team there should ask for its own zone:
timezone takes any IANA name (Europe/Paris, America/New_York, UTC…) and applies to every bucket of the batch. Times in the response stay ISO 8601 instants: the bucket of 7 November in Hanoi comes back as 2026-11-06T17:00:00.000Z.

Ordering and size

  • orderBy names a group key or an aggregate name: { "field": "hosts", "dir": "desc" }. Default: the first aggregate, descending (time order for a filled series); ties follow the group keys.
  • limit caps the number of groups (default 50).
  • An aggregate query takes no select, include, cursor or withTotal.

Rollups: instant counts for large workspaces

The rollups resource holds counts that OASM recomputes every 15 minutes over each service’s latest HTTP response. Reading them is instant whatever the size of the workspace.
Rollups are workspace-wide: they cannot be read inside a project, and they lag the live data by up to 15 minutes. For exact or filtered counts, aggregate the live resource instead.