top
The top command finds the most common combination of values across all fields specified in the field list.
The top command is not rewritten to query domain-specific language (DSL). It is only executed on the coordinating node.
Syntax
The top command has the following syntax:
top [N] [top-options] <field-list> [by-clause]
Parameters
The top command supports the following parameters.
| Parameter | Required/Optional | Description |
|---|---|---|
<N> | Optional | The number of results to return. Default is 10. |
top-options | Optional | showcount: Whether to create a field in the output that represents a count of the tuple of values. Default is true.countfield: The name of the field that contains the count. Default is count.usenull: Whether to output null values. Default is the value of plugins.ppl.syntax.legacy.preferred. |
<field-list> | Required | A comma-delimited list of field names. |
<by-clause> | Optional | One or more fields to group the results by. |
Example 1: Display counts in the default count column
The following query finds the most common gender values:
source=accounts
| top gender
By default, the top command automatically includes a count column showing the frequency of each value:
| gender | count |
|---|---|
| M | 3 |
| F | 1 |
Example 2: Find the most common values without the count display
The following query uses showcount=false to hide the count column in the results:
source=accounts
| top showcount=false gender
The query returns the following results:
| gender |
|---|
| M |
| F |
Example 3: Rename the count column
The following query uses the countfield parameter to specify a custom name (cnt) for the count column instead of the default count:
source=accounts
| top countfield='cnt' gender
The query returns the following results:
| gender | cnt |
|---|---|
| M | 3 |
| F | 1 |
Example 4: Limit the number of returned results
The following query returns the top 1 most common gender value:
source=accounts
| top 1 showcount=false gender
The query returns the following results:
| gender |
|---|
| M |
Example 5: Group the results
The following query uses the by clause to find the most common age within each gender group and show it separately for each gender:
source=accounts
| top 1 showcount=false age by gender
The query returns the following results:
| gender | age |
|---|---|
| F | 28 |
| M | 32 |
Example 6: Specify null value handling
The following query specifies usenull=false to exclude null values:
source=accounts
| top usenull=false email
The query returns the following results:
| count | |
|---|---|
| amberduke@pyrami.com | 1 |
| daleadams@boink.com | 1 |
| hattiebond@netagy.com | 1 |
The following query specifies usenull=true to include null values in the results:
source=accounts
| top usenull=true email
The query returns the following results:
| count | |
|---|---|
| null | 1 |
| amberduke@pyrami.com | 1 |
| daleadams@boink.com | 1 |
| hattiebond@netagy.com | 1 |