top and bottom

The top and bottom operators list the search results of the most common values for the specified field. The resulting values are listed in tabular format from the highest count value to the lowest.

The fields can be event fields, available in the application menu. If multiple fields are specified, you need to separate the field names with white space or a comma.

As a convenience, top and bottom operators are included in out-of-the-box system searches. These system searches contain a query plus specific criteria.

• top

• bottom

• Syntax

• Parameters

• How Do I Use This?

top

The top operator provides the most common values for the specified field(s). The values are listed from the highest count value to the lowest.

bottom

The bottom operator provides the least common values for the specified field(s). The values are listed from the lowest count value to the highest. The rare operator can be used as an alias to bottom.

Syntax

…| top [N] field1 [,field2, field3]                           

where:

• [ ] indicates optional input you may enter.

• Italicized characters indicate where a user can enter customfield information.

• Only N is optional. N limits the matches to the top n values for the specified fields. One (1) field is required, but you can specify a maximum of five (5) integers, separated by commands.

• If you do not specify N, the default value is 500.

• If included, N should be between one (1) and the search results limit.

• The operator performs a standard count (*) to retrieve the number of events.

• No search operator other than "where" can be used in a query after the top/bottom operator is used.

• Queries that use the top/bottom search operator along with fields that begin with "Device" may fail completely or partially. To avoid this behavior, select the field from the drop-down options that are available as you enter the query. This also applies to fields that are not editable.

• Aliases that contain special characters have the following syntax restrictions:

  Special Characters	Restrictions	Examples
  *, -	Do not need to be enclosed in single/double quotes when they are reused and the search works as expected.	Destination port <> null | rename Destination Port as 'D*P' | rename Source Port as 'S*P' | top 10 D*P , S*P
  @, #, +, ?, /, ^, [], {}, _ , *, ., ~, $, %	Do not need to be enclosed in single/double quotes when they are reused and the search works as expected.	Destination port <> null | rename Destination Port as 'D#P' | top D#P
  &, !, =, <, >, +, |	Need to be enclosed in single/double quotes when they are reused and the search works as expected.	Destination port <> null | rename Destination Port as 'D=P' | top 'D=P'
  \	When a backslash is used in an alias name, add an additional backslash \ to escape the character. It does not need to be enclosed in single/double quotes when it is reused and the search runs as expected. The outcome field name should show only one backslash.	Destination port <> null | rename Destination Port as 'D\\P' | top D\\P

Parameters

The parameters are N and a list of comma-separated fields.

For the top operator, when multiple fields are specified, the count of unique sets for all of the fields is listed from the highest to lowest count. For the bottom operator, the fields are listed from the lowest to the highest count.

How Do I Use This?

The top operator is used to limit the matches to the top N values for the specified fields. Likewise, the bottom operator is used to limit the matches to the bottom N values for the specified fields. The default count number is 500 unless you specify a value for N. Here are a few examples:

• You want to limit your results to the 1,000 most common event categories.

  …| top 1000 deviceEventCategory

• You want to limit your search for the top 5 event categories.

  …| top 5 categories

• You want to see all products from a specific vendor that are sending the least number of events.

  deviceVendor = Vendor| bottom 10 deviceProduct

• See the "rare" user action in the organization happening using the HTTPS protocol.

  protocol=https | rare requestuseragent

For information about other operators, functions, and syntax requirements, see Use an Operator in the Query.