fieldsummary command overview, syntax, and usage

The SPL2 fieldsummary command calculates summary statistics for one or more fields in your events. The summary information is displayed as a results table.

How the SPL2 fieldsummary command works

The SPL2 fieldsummary command calculates summary statistics, such as the count, maximum value, minimum value, mean, and standard deviation for the fields in your search results. These summary statistics are displayed in a table for each field in your results or for the fields you specify with the fieldsummary command.

For example, suppose you have the following visitor_log information:

hour	visitor_count
0800	0
0900	212
1000	367
1100	489
1200	624
1300	609
1400	492
1500	513
1600	367
1700	337
1800	104

To return summary statistics for all of the fields in your search results, add the fieldsummary command to the end of your search:

FROM visitor_log | fieldsummary

The result looks similar to this:

field	count	distinct_ count	is_ exact	max	mean	min	numeric_ count	stdev	values
hour	11	11	0	1800	1300	800	11	331.6	[{"value":"1000","count":1},{"value":"1100","count":1},{"value":"1200","count":1},{"value":"1300","count":1},{"value":"1400","count":1},{"value":"1500","count":1},{"value":"1600","count":1},{"value":"1700","count":1},{"value":"1800","count":1},{"value":"800","count":1}]
visitor_ count	11	10	1	624	374	0	11	201.1	[{"value":"367","count":2},{"value":"0","count":1},{"value":"104","count":1},{"value":"212","count":1},{"value":"337","count":1},{"value":"489","count":1},{"value":"492","count":1},{"value":"513","count":1},{"value":"609","count":1},{"value":"624","count":1}]

Insights into the summary fields

The fieldsummary command returns 10 fields with summary information.

Looking at the results shown in the previous example, notice a few things about these results:

values field

• The entries in the values field are organized by count in descending order. You can see this clearly in the visitor_count row. The value "367" has a count of "2". All of the other values have a count of "1". Even though there are 11 values, only 10 are returned. This is because the default for the maxvals argument is 10.
• When the entries in the values field have the same count, the entries are organized by value in lexicographical order. You can see this clearly in the hours row. The values that start with 1, such as "1000" come before values that start with 8 or 9, such as "800". The value "900" is not returned because only the first 10 values are returned by default. For more information, see Lexicographical order in the SPL2 Search Manual.

distinct_count field

• This field shows the count of different values in a field in the search results. For the hours row, there are 10 different values for the hours in the day. For the visitor_count row, there are 9 different values for the number of visitors. The value "367" appears for both the 1000 hour and the 1600 hour.

is_exact field

• This field specifies whether the count is an exact count or an approximate count of the distinct values in a field. The value "1" indicates that the count is exact. The value "0" indicates that the count is an approximate count. The maxvals argument controls whether the count is exact or approximate. In this search, the maxvals argument is not specified so the default value for the maxvals argument is used. The default value for the maxvals argument is 10.

For more information about the fields returned from the fieldsummary command, see fieldsummary command usage.

Optional arguments

There are two optional arguments that you can use with the fieldsummary command, maxvals and fields.

You can use the maxvals argument to specify how many distinct values you want returned from the search. If not specified, a maximum of 10 values is returned.

You can use the fields argument to specify which fields you want summary information for. If not specified, summary information is returned for all of the fields in your search results.

Syntax

The required syntax is in bold.

fieldsummary

[maxvals=<unsigned_int>]

[fields="["<wc-field-list>"]" ]

Required arguments

fieldsummary

Syntax: fieldsummary

Description: Returns the distinct values for every field in your events, unless you specify fields that you want summary information for by using the fields arguments. By default, the fieldsummary command returns a maximum of 10 distinct values. Use the maxvals argument to specify a different maximum.

Optional arguments

maxvals

Syntax: maxvals=<unsigned_int>

Description: Specifies the maximum distinct values to return for each field. This can't be a negative number. If you set maxvals = 0, all available distinct values for each field are returned, which can impact search performance.

Default: 10

fields

Syntax: fields=[ <wc-field>, <wc-field> ...]

Description: A single field name or a comma-delimited list of field names. The field names must be enclosed in square brackets ( [ ] ). You can use the asterisk ( * ) as a wildcard to specify a list of fields with similar names. For example, if you want to specify all fields that start with "value", you can use a wildcard such as value*.

Usage

The fieldsummary command displays the summary information in a results table. The following information appears in the results table:

Summary field name	Description
field	The field name in the event.
count	The number of events or results with that field.
distinct_count	The number of unique values in the field.
is_exact	Whether or not the count of the distinct field values is exact. If the number of distinct values of the field exceeds the maxvals value, then fieldsummary stops retaining all the distinct values and computes an approximate distinct count instead of an exact one. 1 means the distinct count is exact; 0 means the distinct count is not exact.
max	If the field is numeric, the maximum of its value.
mean	If the field is numeric, the mean of its values.
min	If the field is numeric, the minimum of its values.
numeric_count	The count of numeric values in the field. The count doesn't include null values.
stdev	If the field is numeric, the standard deviation of its values.
values	The distinct values of the field and count of each value. The values are sorted first by highest count and then by distinct value, in ascending order.

Differences between SPL and SPL2

Default maximum values returned has changed

The default number of distinct values returned for a field is different in SPL2:

Version	Value
SPL	100
SPL2	10

Field argument syntax is different

The field argument in SPL2 has a different syntax than in SPL:

Version	Syntax	Example
SPL	wc-field-list A single field name or a space-delimited list of field names.	| fieldsummary action pid quantity
SPL2	field=[<field-list>] A single field name or a comma-delimited list of field names. The field names must be enclosed in square brackets [ ] .	| fieldsummary fields=[action, pid, quantity]

See also

fieldsummary command

fieldsummary command examples