Used to compute multiple aggregate functions over the input.

ParameterTypeRequiredDefault ValueDescription
function[a]array of aggregate functionsoptional[b]count(as=_count) Specifies which aggregate functions to perform on each group.

[a] The parameter name function can be omitted.

[b] Optional parameters use their default value unless explicitly set.

Hide omitted argument names for this function

Show omitted argument names for this function

The stats() function is implicitly present in a fair number of places where a list of subaggregators is given - for example, groupBy(x, function=[min(y), max(y)]) is equivalent to groupBy(x, function=stats([min(y), max(y)])). This is how aggregator results are combined when using those other functions.

The output of stats() is:

  • The output combination is checked for fieldname collisions - and it is an error if a field is present in multiple outputs with conflicting values.

  • In case all subaggregators yield at most one row of output (this includes most numerical aggregators), the result will be one combined row.

  • When one or more of the subaggregators of stats() emit more than one result row, the total output is the Cartesian product of all of the subaggregators' outputs, except if any of the subaggregators outputs zero rows, it is taken as it is outputting a single empty row.

The stats() is also available as a shorthand syntax by writing a list of aggregators in square brackets:

logscale Syntax
...
| stats(function=[min(), max()])

Is equivalent to:

logscale Syntax
...
| [min(),max()]

This produces one row of data that contains both min and max results.

The following query is equivalent to just count():

logscale
stats(function=count())

stats() Examples

Click + next to an example below to get the full details.

Annotate Events With Aggregation - Example 1

Annotate events using stats() function and aggregation

Query
logscale
kvparse()| stats([
avg(x),
table([x])
])
Introduction

The stats() function can be used to compute multiple aggregate functions over the input. In this example, the stats() function is used with aggregation on the field x.

Example incoming data might look like this:

logscale
x=1
x=2
x=9
x=10

Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    kvparse()

    Parses the string into key value pairs.

  3. logscale
    | stats([
avg(x),
table([x])
])

    Computes the aggregate functions avg() and table() over the field x, and returns the results in a field named _avg and a field named x. Note that the table() function returns more rows as output, whereas the avg() function only returns 1 row.

  4. Event Result set.

Summary and Results

The query is used to compute multiple aggregate functions over an input.

Sample output from the incoming example data: 

"_avg","x"
"5.5","1"
"5.5","2"
"5.5","9"
"5.5","10"

Annotate Events With Aggregation - Example 2

Annotate events using stats() function and aggregation

Query
logscale
kvparse()| stats([
sum(x, as=sumX),
avg(y, as=avgY),
table([x, y])
])
Introduction

The stats() function can be used to compute multiple aggregate functions over the input. In this example, the stats() function is used with aggregation on the field x where one of the subaggregators (avg(y)) outputs zero rows.

The example shows what happens, when a subaggregator avg(y) does not produce an output.

Example incoming data might look like this:

logscale
"x=1 y=N/A"
"x=2 y=N/A"

Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    kvparse()

    Parses the string into key value pairs.

  3. logscale
    | stats([
sum(x, as=sumX),
avg(y, as=avgY),
table([x, y])
])

    Computes the aggregate functions sum(), avg() and table() over the fields x and y, and returns the results in a field named sumX, a field named x, and a field named y.

  4. Event Result set.

Summary and Results

The query is used to compute multiple aggregate functions over an input.

Sample output from the incoming example data: 

"sumX","x","y"
"3","1","N/A"
"3","2","N/A"

Annotate Events With Aggregation - Example 3

Annotate events using stats() function and aggregation

Query
logscale
kvparse()| stats([
table([x,y]),
table([z])
])
Introduction

The stats() function can be used to compute multiple aggregate functions over the input. In this example, the stats() function is used with aggregation on the fields x, y, and z, where all of the subaggregators output rows.

The example shows a Cartesian product where the output is all combinations of all results of the subaggregators

Example incoming data might look like this:

logscale
"x=1 y=10 z=100"
"x=2 y=20 z=200"

Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    kvparse()

    Parses the string into key value pairs.

  3. logscale
    | stats([
table([x,y]),
table([z])
])

    Computes the aggregate function table() over the fields x, y, and z, and returns the results - a combination of all outputs, also called the Cartesian product - in a field named x, a field named y, and a field named z. Note that since both subaggregators output multiple rows, the returned result is the Cartesian product, containing all combinations of the results from the subaggregators.

  4. Event Result set.

Summary and Results

The query is used to compute multiple aggregate functions over an input.

Sample output from the incoming example data: 

"x","y","z"
"1","10","100"
"1","10","200"
"2","20","100"
"2","20","200"