timeaggs
Description
Performs search and generates an array of data distributed along a timeline using the internal mechanisms of the storage system.
The timeaggs command can only be used in a query if it's preceded by other commands that also work with internal storage mechanisms, such as source, search, and peval. This condition must also be met for all subqueries within the query.
Syntax
timeaggs [<composite>] [<span>] [<timefield>] [<limit>] [<useother>] <functions-expression> ["," <functions-expression>] [<by_expression>]
Required Arguments
functions-expression You must use at least one of the following functions:
| Parameter | Syntax | Description |
|---|---|---|
count | count | count(<field>) | Counts the number of events containing a field. If no field is specified, counts the total number of events. |
avg | avg(<field>) | Calculates the average value of a given field. |
dc | dc(<field>) | Computes the number of unique values in a given field. |
max | max(<field>) | Computes the maximum value in a given field. |
min | min(<field>) | Computes the minimum value in a given field. |
sum | sum(<field>) | Computes the sum of the values in a given field. |
Optional Arguments
| Parameter | Syntax | Default | Description |
|---|---|---|---|
span | span=<span> | see predefined span values | Defines the interval for distribution of segments. |
timefield | timefield=<field> | @timestamp | Name of the field containing the timestamp. |
composite | composite=<boolean> | false | Allows for scrolling in aggregations and obtaining all possible segments (buckets) through multiple queries (similar to scroll in stats). Can only be applied when grouping (by fields). The number of segments (buckets) returned in the response is fixed at 1000. |
limit | limit=<int> | 10 | The maximum number of unique by_field values that can be used in the column names of the result. Remaining values will be merged into the OTHER field. |
useother | useother=<boolean> | true | If set to false, the limit parameter is ignored. |
by_expression | by <field> | The field name used for grouping values. |
The following time formats are allowed: (+|-)<int>(s|m|h|d|w|month):
- s/sec/secs/second/seconds - seconds
- m/min/mins/minute/minutes - minutes
- h/hr/hrs/hour/hours - hours
- d/day/days - days
- w/week/weeks - weeks
- mon/month/months - months
span valuesIf no span parameter is specified for the time field, default parameters will apply.
Here's the list of predefined parameters:
| Time Interval | span |
|---|---|
| last 15 minutes | 10 seconds |
| last 60 minutes | 1 minute |
| last 4 hours | 5 minutes |
| last 24 hours | 30 minutes |
| last 7 days | 1 day |
| last 30 days | 1 day |
| last year | 1 month |
compositeThe composite argument is available when querying OpenSearch.
keyword in OpenSearchAggregations in OpenSearch perform statistical operations on numeric fields or text fields of the keyword type. Thus, for text fields, you need to append <fieldname>.keyword, and this is necessary both in specified fields and by fields. For example:
... | timeaggs avg(user.keyword), earliest(country.keyword) by event.keyword, user_count
Query Examples
... | timeaggs span=1h avg(msgNums) by user.keyword
... | timeaggs span=15m avg(log.offset) by source.keyword
... | timeaggs composite=true span=3h count, max(log.offset)