diff --git a/data-explorer/kusto/query/top-hitters-operator.md b/data-explorer/kusto/query/top-hitters-operator.md index 6330ef21ea..016c8a324a 100644 --- a/data-explorer/kusto/query/top-hitters-operator.md +++ b/data-explorer/kusto/query/top-hitters-operator.md @@ -1,9 +1,9 @@ --- title: top-hitters operator description: Learn how to use the top-hitters operator to return an approximation for the most popular distinct values in the input. -ms.reviewer: alexans +ms.reviewer: zivc ms.topic: reference -ms.date: 04/06/2025 +ms.date: 05/18/2026 --- # top-hitters operator @@ -13,9 +13,10 @@ Returns an approximation for the most popular distinct values, or the values with the largest sum, in the input. > [!NOTE] -> `top-hitters` uses an approximation algorithm optimized for performance -> when the input data is large. -> The approximation is based on the [Count-Min-Sketch](https://en.wikipedia.org/wiki/Count%E2%80%93min_sketch) algorithm. +> The `top-hitters` operator uses an approximation algorithm that's optimized for performance when the input data is large. +> The approximation is based on the [Count-Min-Sketch](https://en.wikipedia.org/wiki/Count%E2%80%93min_sketch) algorithm. +> +> This operator is non-deterministic. Running it twice over the same data doesn't guarantee the same results. ## Syntax @@ -27,17 +28,17 @@ with the largest sum, in the input. | Name | Type | Required | Description | |--|--|--|--| -| *T* | `string` | :heavy_check_mark: | The input tabular expression.| +| *T* | `tabular expression` | :heavy_check_mark: | The input tabular expression.| | *NumberOfValues* | int, long, or real | :heavy_check_mark: | The number of distinct values of *ValueExpression*.| -| *ValueExpression* | `string` | :heavy_check_mark: | An expression over the input table *T* whose distinct values are returned.| -| *SummingExpression* | `string` | | If specified, a numeric expression over the input table *T* whose sum per distinct value of *ValueExpression* establishes which values to emit. If not specified, the count of each distinct value of *ValueExpression* is used instead.| +| *ValueExpression* | `scalar` | :heavy_check_mark: | An expression over the input table *T* whose distinct values are returned.| +| *SummingExpression* | `long` or `real` | | If specified, a numeric expression over the input table *T* whose sum per distinct value of *ValueExpression* establishes which values to emit. If not specified, the count of each distinct value of *ValueExpression* is used instead.| > [!NOTE] -> * When you include *SummingExpression* in the syntax, the query is equivalent to: +> * When you include *SummingExpression* in the syntax, the query approximates the value of: > > `T | summarize S = sum(SummingExpression) by ValueExpression | top NumberOfValues by S desc` > -> * When you don't include *SummingExpression* in the syntax, the query is equivalent to: +> * When you don't include *SummingExpression* in the syntax, the query approximates the value of: > > `T | summarize C = count() by ValueExpression | top NumberOfValues by C desc` @@ -48,7 +49,7 @@ The examples in this section show how to use the syntax to help you get started. [!INCLUDE [help-cluster-note](../includes/help-cluster-note.md)] -### Get top 2 events by totals ### +### Get top two events by totals ### This example summarizes storm event data by calculating the total number of events for each event type. The query then selects the top two event types with the highest total number of events. @@ -72,7 +73,7 @@ StormEvents ### Get most frequent items -This example shows how to find the top-5 types of storms. +This example shows how to find the top five types of storms. :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] @@ -96,7 +97,7 @@ StormEvents ### Get top hitters based on column value -This example shows how to find the States with the most *Thunderstorm Wind* events. +This example shows how to find the states with the most *Thunderstorm Wind* events. :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] @@ -123,3 +124,27 @@ StormEvents | VIRGINIA | 482 | | KANSAS | 476 | | OHIO | 455 | + +### Get top hitters by summed value + +This example finds the event types with the highest total property damage, using `DamageProperty` as the summing expression. + +:::moniker range="azure-data-explorer" +> [!div class="nextstepaction"] +> Run the query +::: moniker-end + +```kusto +StormEvents +| top-hitters 5 of EventType by DamageProperty +``` + +**Output** + +| EventType | approximate_sum_DamageProperty | +|---|---| +| Flood | 1,124,327,850 | +| Flash Flood | 626,659,030 | +| Tornado | 492,562,280 | +| Hail | 479,070,850 | +| Thunderstorm Wind | 221,037,650 |