> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Counting and grouping

> Turn an Attack Surface Query into numbers: groupBy, count, countDistinct, sum, min, max, avg, conditional aggregates, having, time series and time zones

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?*

```json theme={null}
{
  "from": "services",
  "groupBy": ["port"],
  "aggregate": { "hosts": { "fn": "countDistinct", "field": "host.id" } },
  "orderBy": [{ "field": "hosts", "dir": "desc" }],
  "limit": 20
}
```

```json theme={null}
{ "rows": [ { "port": 443, "hosts": 118 }, { "port": 80, "hosts": 69 }, { "port": 8080, "hosts": 33 } ] }
```

## aggregate

A map of names you choose to `{ "fn", "field"?, "where"? }`. Up to **eight** per query.

| `fn` | Field | Result |
| - | - | - |
| `count` | none | number of rows in the group |
| `count` | a field | rows where that field has a value |
| `countDistinct` | a field | distinct values (`host.id` counts hosts, not services) |
| `sum` | number | total |
| `avg` | number | average |
| `min`, `max` | number, time, text or enum | smallest / largest value |

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:*

```json theme={null}
{
  "from": "vulnerabilities",
  "groupBy": ["host.value"],
  "where": { "logic": "and", "items": [{ "field": "isOpen", "op": "eq", "value": "true" }] },
  "aggregate": {
    "open": { "fn": "count" },
    "critical": { "fn": "count", "where": { "logic": "and", "items": [{ "field": "severity", "op": "eq", "value": "critical" }] } },
    "high": { "fn": "count", "where": { "logic": "and", "items": [{ "field": "severity", "op": "eq", "value": "high" }] } },
    "maxCvss": { "fn": "max", "field": "cvssScore" }
  },
  "orderBy": [{ "field": "critical", "dir": "desc" }]
}
```

```json theme={null}
{ "rows": [
  { "host": { "value": "api.example.com" }, "open": 7, "critical": 2, "high": 3, "maxCvss": 9.8 },
  { "host": { "value": "shop.example.com" }, "open": 4, "critical": 1, "high": 0, "maxCvss": 9.1 }
] }
```

The query's `where` applies first, then each aggregate's own filter. An aggregate filter takes everything a [`where`](https://docs.oasm.io/attack-surface-query/filtering) takes, including nested groups and relation tests.

## groupBy

Up to three group keys. A key is a field marked *groupable* in [Resources and fields](https://docs.oasm.io/attack-surface-query/resources.md), of the resource or of a related row:

```json theme={null}
{ "from": "hosts", "groupBy": ["target.value", "kind"], "aggregate": { "n": { "fn": "count" } } }
```

Without `groupBy`, the query returns one row of totals:

```json theme={null}
{ "from": "vulnerabilities",
  "aggregate": { "open": { "fn": "count" }, "maxCvss": { "fn": "max", "field": "cvssScore" } },
  "where": { "logic": "and", "items": [{ "field": "isOpen", "op": "eq", "value": "true" }] } }
```

## 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:*

```json theme={null}
{
  "from": "vulnerabilities",
  "groupBy": ["host.value"],
  "aggregate": {
    "critical": { "fn": "count", "where": { "logic": "and", "items": [{ "field": "severity", "op": "eq", "value": "critical" }] } },
    "high": { "fn": "count", "where": { "logic": "and", "items": [{ "field": "severity", "op": "eq", "value": "high" }] } }
  },
  "having": { "logic": "or", "items": [
    { "field": "critical", "op": "gt", "value": "0" },
    { "field": "high", "op": "gt", "value": "0" }
  ] }
}
```

`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`.

```json theme={null}
{
  "window": { "since": "now-30d" },
  "queries": {
    "hostsPerDay": {
      "from": "hosts",
      "groupBy": [{ "field": "firstSeen", "bucket": "day" }],
      "aggregate": { "n": { "fn": "count" } },
      "limit": 31
    }
  }
}
```

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:

```json theme={null}
{
  "window": { "since": "now-14d" },
  "queries": {
    "newPortsPerDay": {
      "from": "services",
      "groupBy": [{ "field": "firstSeen", "bucket": "day" }],
      "aggregate": { "n": { "fn": "count" } },
      "fill": true
    }
  }
}
```

```json theme={null}
{ "rows": [
  { "firstSeen": "2026-11-06T00:00:00.000Z", "n": 0 },
  { "firstSeen": "2026-11-07T00:00:00.000Z", "n": 12 },
  { "firstSeen": "2026-11-08T00:00:00.000Z", "n": 0 },
  "…"
] }
```

* `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:

```json theme={null}
{
  "window": { "since": "now-14d" },
  "options": { "timezone": "Asia/Ho_Chi_Minh" },
  "queries": { "newPortsPerDay": { "...": "..." } }
}
```

`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.

| `metric` | `key` is | `value` is |
| - | - | - |
| `port` | a port number | services with that port open |
| `technology` | a technology name | services running it |
| `webserver` | a `Server` header | services returning it |
| `statusCode` | an HTTP status code | services returning it |
| `tlsVersion` | a TLS version | services negotiating it |

```json theme={null}
{ "from": "rollups", "select": ["key", "value", "computedAt"],
  "where": { "logic": "and", "items": [{ "field": "metric", "op": "eq", "value": "technology" }] },
  "limit": 20 }
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.