You're viewing version 3.4 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
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 |