top
Description
Finds the most common values for the fields in the field list. Calculates a count and a percentage of the frequency the values occur in the events. If the <by-clause> is included, the results are grouped by the field you specify in the <by-clause>.
Syntax
top [<N>] [<top-options>...] <field-list> [<by-clause>]
Required arguments
- <field-list>
- Syntax: <field>, <field>, ...
- Description: Comma-delimited list of field names.
Optional arguments
- <N>
- Syntax: <int>
- Description: The number of results to return.
- Default: 10
- <top-options>
- Syntax: countfield=<string> | limit=<int> | otherstr=<string> | percentfield=<string> | showcount=<bool> | showperc=<bool> | useother=<bool>
- Description: Options for the
top
command. See Top options.
- <by-clause>
- Syntax: BY <field-list>
- Description: The name of one or more fields to group by.
Top options
- countfield
- Syntax: countfield=<string>
- Description: For each value returned by the
top
command, the results also return a count of the events that have that value. This argument specifies the name of the field that contains the count. The count is returned by default. If you do not want to return the count of events, specifyshowcount=false
. - Default: count
- limit
- Syntax: limit=<int>
- Description: Specifies how many results to return. To return all values, specify zero ( 0 ). Specifying
top limit=<int>
is the same as specifyingtop N
. - Default: 10
- otherstr
- Syntax: otherstr=<string>
- Description: If
useother=true
, a row representing all other values is added to the results. Useotherstr=<string>
to specify the name of the label for the row. - Default: OTHER
- percentfield
- Syntax: percentfield=<string>
- Description: For each value returned by the
top
command, the results also return a percentage of the events that have that value. This argument specifies the name of the field that contains the percentage. The percentage is returned by default. If you do not want to return the percentage of events, specifyshowperc=false
. - Default: percent
- showcount
- Syntax: showcount=<bool>
- Description: Specify whether to create a field called "count" (see "countfield" option) with the count of that tuple.
- Default: true
- showperc
- Syntax: showperc=<bool>
- Description: Specify whether to create a field called "percent" (see "percentfield" option) with the relative prevalence of that tuple.
- Default: true
- useother
- Syntax: useother=<bool>
- Description: Specify whether or not to add a row that represents all values not included due to the limit cutoff.
- Default: false
Usage
The top
command is a transforming command. See Command types.
Default fields
When you use the top
command, two fields are added to the results: count
and percent
.
Field | Description |
---|---|
count
|
The number of events in your search results that contain the field values that are returned by the top command. See the countfield and showcount arguments.
|
percent
|
The percentage of events in your search results that contain the field values that are returned by the top command. See the percentfield and showperc arguments.
|
Default maximum number of results
By default the top
command returns a maximum of 50,000 results.
This maximum is controlled by the maxresultrows
setting in the [top]
stanza in the limits.conf file. Increasing this limit can result in more memory usage.
Only users with file system access, such as system administrators, can edit the configuration files. Never change or copy the configuration files in the default directory. The files in the default directory must remain intact and in their original location. Make the changes in the local directory.
See How to edit a configuration file.
If you have Splunk Cloud Platform, you need to file a Support ticket to change this limit.
Lexicographic order of results
In searches that use the limit
option with multiple sets of field lists, only the last lexicographical value of the <field-list>
is returned in the search results. For example, in the following search, Orlando
is the only location
field that is returned because it's the last value when sorted lexicographically.
| makeresults
| eval location="Orlando Dallas Atlanta"
| makemv location
| mvexpand location
| eval user="Alex Kai Morgan"
| makemv user
| mvexpand user
| top limit=1 location by user
The search results look something like this.
user | location | count | percent |
---|---|---|---|
Alex | Orlando | 1 | 33.333333 |
Kai | Orlando | 1 | 33.333333 |
Morgan | Orlando | 1 | 33.333333 |
Examples
Example 1: Return the 20 most common values for a field
This search returns the 20 most common values of the "referer" field. The results show the number of events (count) that have that a count of referer, and the percent that each referer is of the total number of events.
sourcetype=access_* | top limit=20 referer
Example 2: Return top values for one field organized by another field
This search returns the top "action" values for each "referer_domain".
sourcetype=access_* | top action by referer_domain
Because a limit is not specified, this returns all the combinations of values for "action" and "referer_domain" as well as the counts and percentages:
Example 3: Returns the top product purchased for each category
This example uses the sample dataset from the Search Tutorial and a field lookup to add more information to the event data.
After you configure the field lookup, you can run this search using the time range, All time. |
This search returns the top product purchased for each category. Do not show the percent field. Rename the count field to "total".
sourcetype=access_* status=200 action=purchase | top 1 productName by categoryId showperc=f countfield=total
See also
tojson | transaction |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!