stats search command

This search command creates an aggregate representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified. The command also supports the optional group by parameter, to apply aggregate functions on the distinct value of a specified field. For example, you can plot the aggregate count of data occurring from a particular host depending on the data-collector names. Similarly, you can run other aggregate functions such as sum, avg, min, and max to find the sum, average, minimum (smallest), and maximum (highest) values of a field.

Additionally, you can perform the following functions:

• Limit the number of results: You can limit the results displayed by using the limit parameter.
• Sort the results: You can sort the results in an ascending or descending way based on one of the following options:
  • One of the aggregate functions that you specify.
  • The group by parameter that you specify.

This command is similar to the timechart command, except that it does not represent data on the basis of a specified time span; instead, it provides an aggregate representation.

In the preceding syntax, the following definitions apply:

• + indicates one or more similar expressions separated by a comma (,) or space.

• <aggregate-function> refers to the aggregate function used for creating the chart; for example, count, sum, or average.

  The following table describes the aggregate functions that can be used in the command syntax:

  Function	Syntax	Description
  Count	count (<field>)	Uses field name as an argument and returns the number of occurrences of that field in the search results.
  Sum	sum (<field>)	Uses field name as an argument and returns the sum of values of that field in the search results.
  Average	avg (<field>)	Uses field name as an argument and returns the average of values of that field in the search results.
  Minimum	min (<field>)	Uses field name as an argument and returns the smallest value of that field in the search results.
  Maximum	max (<field>)	Uses field name as an argument and returns the highest value of that field in the search results.
  Standard deviation	stddev (<field>)	Uses field name as an argument and returns the standard deviation of the values of that field in the search results.
  where, <field> can be a field name or a tag name

• [as <alias>] refers to the as parameter used for optionally renaming a field with an alternate field name (an alias).
• [by <field>] refers to a group by parameter that is optionally used in conjunction with the aggregate functions, to group the result set by the specified field.
• [limit=<int>] refers to the limit parameter that can be optionally used to limit the number of results by the integer value specified. <int> refers to the integer value that represents the maximum number of results to return. This parameter must be used in conjunction with the aggregate functions and the by parameter. If you specify both the limit parameter and the sortby parameter, then you must specify the limit parameter only after the sortby parameter.

• [sortby=<option>] refers to the sortby parameter that can be optionally used to sort the results displayed by using one of the following options:

  • One of the aggregate functions that you specify.
  • The group by parameter that you specify.

  This parameter must be used in conjunction with the aggregate functions and the by parameter. By default, this parameter sorts results in the ascending order based on the by parameter field.

  If you want to sort results in the ascending way, it is optional to specify ASC after specifying the sortby parameter. However, if you want to sort results in the descending way, you must specify DESC after specifying the sortby parameter.

  The following table provides the syntax and examples for sorting results:

  Sorting order	Syntax	Example
  (Default) Ascending	sortby=<option> ASC	sortby count(HOST) ASC
  Descending	sortby=<option> DESC	sortby count(HOST) DESC

Short examples

Example 2: Return the number of occurrences of the RequestType field grouped by the ClientIp field.

Example 3: Return the number of occurrences of the events field and the sum of the values of the bytes-read field in the search results.

... | stats count(events) as Count, sum(bytes-read) as Total 

Example 5: Return the sum of values and the average of values of the ResponseSize field, grouped by the ClientIp field, and sorted by the aggregate function for average.