> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nexthink-query-language-nql/nql-keywords/nql-summarize-by.md).

# NQL summarize by

The `summarize by` statement condenses the information into aggregated results grouped by properties or time interval.

## Grouping by property <a href="#nqlsummarizeby-groupingbyproperty" id="nqlsummarizeby-groupingbyproperty"></a>

Enter the field name after `by` to create a breakdown by a property. Enter additional field names separated by a comma to create more breakdown dimensions.

{% hint style="info" %}
The `summarize by` clause does not support grouping by properties with the following numeric data types:

* Date time, for example `last_seen`
* Byte, for example `hardware.memory`
  {% endhint %}

To group by a time interval instead of a property, refer to [Grouping by period](#nqlsummarizeby-groupingbyperiod).

### Syntax <a href="#nqlsummarizeby-syntax" id="nqlsummarizeby-syntax"></a>

{% code overflow="wrap" lineNumbers="true" %}

```
...
| summarize <new metric name> = <metric>.<aggregation function> by <field_1>, <field_2> ...
```

{% endcode %}

### Examples <a href="#nqlsummarizeby-example" id="nqlsummarizeby-example"></a>

Display the average Confluence backend page load time per device in the last 7 days.

{% code overflow="wrap" lineNumbers="true" %}

```
web.page_views during past 7d
| where application.name == "Confluence"
| summarize backendTime = page_load_time.backend.avg() by device.name
| list device.name, backendTime
| sort backendTime desc
```

{% endcode %}

<table data-search="false"><thead><tr><th>Device name</th><th>backendTime</th></tr></thead><tbody><tr><td>device-10d267d2</td><td>508.2 ms</td></tr><tr><td>device-d1d5abc9</td><td>498.9 ms</td></tr><tr><td>device-5117c4c3</td><td>432.1 ms</td></tr><tr><td>device-16834449</td><td>431.9 ms</td></tr><tr><td>device-b634ce84</td><td>429.4 ms</td></tr><tr><td>device-731db075</td><td>349.8 ms</td></tr><tr><td>device-7fb313ef</td><td>293.9 ms</td></tr><tr><td>device-a834a720</td><td>277.6 ms</td></tr><tr><td>…</td><td>…</td></tr></tbody></table>

Rank the public IP addresses that the highest number of devices present. Devices that share an address usually reach the internet through the same egress point, such as a corporate firewall or a proxy service. A shift in these clusters indicates a change in the network.

{% hint style="info" %}
Grouping by an IP address field groups by the exact address value. The system does not support grouping by an IP range.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```
devices
| summarize total = count() by public_ip.ip_address
| sort total desc
```

{% endcode %}

| Public IP address | total |
| ----------------- | ----- |
| 203.0.113.17      | 1,284 |
| 203.0.113.42      | 976   |
| 198.51.100.8      | 412   |
| 198.51.100.63     | 87    |
| …                 | …     |

List the URLs that generate the most web errors, broken down by error code, in the last 7 days. Grouping by an integer field such as `code` returns one row per distinct value.

{% code overflow="wrap" lineNumbers="true" %}

```
web.errors during past 7d
| summarize total = number_of_errors.sum() by code, url
| sort total desc
```

{% endcode %}

| code | url                                  | total |
| ---- | ------------------------------------ | ----- |
| 503  | <https://intranet.example.com/api>   | 2,140 |
| 404  | <https://intranet.example.com/help>  | 1,509 |
| 500  | <https://portal.example.com/login>   | 883   |
| 403  | <https://portal.example.com/reports> | 216   |
| …    | …                                    | …     |

## Grouping by period <a href="#nqlsummarizeby-groupingbyperiod" id="nqlsummarizeby-groupingbyperiod"></a>

The `summarize by` statement when used in combination with a time period, groups the metric values into time buckets.

### Syntax <a href="#nqlsummarizeby-syntax.1" id="nqlsummarizeby-syntax.1"></a>

{% code overflow="wrap" lineNumbers="true" %}

```
...
| summarize <new metric name> = <metric>.<aggregation function> by <time period>
```

{% endcode %}

Valid period values are:

* `15 min` `30 min` `45 min` …\
  The value must be a multiple of 15.
* `1 h` `2 h` `3 h` ...\
  The value must be a whole number.
* `1 d` `2 d` `3 d` ...\
  The value must be a whole number.

### Example <a href="#nqlsummarizeby-example.1" id="nqlsummarizeby-example.1"></a>

Display daily number of crashes in the last 7 days in chronological order.

{% code overflow="wrap" lineNumbers="true" %}

```
execution.crashes during past 7d
| summarize total_number_of_crashes = count() by 1d
| sort start_time asc
```

{% endcode %}

<table data-search="false"><thead><tr><th>start_time</th><th>end_time</th><th>bucket_duration</th><th>number_of_crashes</th></tr></thead><tbody><tr><td>2021-03-05<br>00:00:00</td><td>2021-03-06<br>00:00:00</td><td>1 d</td><td>758</td></tr><tr><td>2021-03-06<br>00:00:00</td><td>2021-03-07<br>00:00:00</td><td>1 d</td><td>700</td></tr><tr><td>2021-03-07<br>00:00:00</td><td>2021-03-08<br>00:00:00</td><td>1 d</td><td>954</td></tr><tr><td>2021-03-08<br>00:00:00</td><td>2021-03-09<br>00:00:00</td><td>1 d</td><td>493</td></tr><tr><td>2021-03-09<br>00:00:00</td><td>2021-03-10<br>00:00:00</td><td>1 d</td><td>344</td></tr><tr><td>2021-03-10<br>00:00:00</td><td>2021-03-11<br>00:00:00</td><td>1 d</td><td>765</td></tr><tr><td>2021-03-11<br>00:00:00</td><td>2021-03-12<br>00:00:00</td><td>1 d</td><td>857</td></tr></tbody></table>

## Grouping by property and period <a href="#nqlsummarizeby-groupingbypropertyandperiod" id="nqlsummarizeby-groupingbypropertyandperiod"></a>

Combine properties and time period to generate time buckets with additional breakdowns. You can use multiple fields, but only one time period selector. The sequence of items is arbitrary; the time period selector can be positioned anywhere within the list of fields.

### Syntax <a href="#nqlsummarizeby-syntax.2" id="nqlsummarizeby-syntax.2"></a>

{% code overflow="wrap" lineNumbers="true" %}

```
...
| summarize <new metric name> = <metric>.<aggregation function> by <field_1>, <field_2>, ... <time period>, ...
```

{% endcode %}

### Example <a href="#nqlsummarizeby-example.2" id="nqlsummarizeby-example.2"></a>

Display daily number of crashes in the last 30 days broken down by operating system platform and sorted starting from the highest number of crashes.

{% code overflow="wrap" lineNumbers="true" %}

```
execution.crashes during past 30d
| summarize total_number_of_crashes = count() by 1d, device.operating_system.platform 
| sort total_number_of_crashes desc
```

{% endcode %}

<table data-search="false"><thead><tr><th>Device platform</th><th>start_time</th><th>end_time</th><th>bucket_duration</th><th>number_of_crashes</th></tr></thead><tbody><tr><td>Windows</td><td>2021-12-07<br>00:00:00</td><td>2021-12-08<br>00:00:00</td><td>1 d</td><td>690</td></tr><tr><td>Windows</td><td>2021-12-08<br>00:00:00</td><td>2021-12-09<br>00:00:00</td><td>1 d</td><td>533</td></tr><tr><td>macOS</td><td>2021-12-20<br>00:00:00</td><td>2021-12-21<br>00:00:00</td><td>1 d</td><td>511</td></tr><tr><td>Windows</td><td>2021-12-17<br>00:00:00</td><td>2021-12-18<br>00:00:00</td><td>1 d</td><td>493</td></tr><tr><td>Windows</td><td>2021-12-08<br>00:00:00</td><td>2021-12-09<br>00:00:00</td><td>1d</td><td>356</td></tr><tr><td>macOS</td><td>2021-12-20<br>00:00:00</td><td>2021-12-21<br>00:00:00</td><td>1d</td><td>325</td></tr><tr><td>…</td><td>…</td><td>…</td><td>…</td><td>…</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nexthink-query-language-nql/nql-keywords/nql-summarize-by.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.