> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# top

> This page explains how to use the top operator function in APL.

The `top` operator in Axiom Processing Language (APL) allows you to retrieve the top N rows from a dataset based on specified criteria. It’s particularly useful when you need to analyze the highest values in large datasets or want to quickly identify trends, such as the highest request durations in logs or top error occurrences in traces. You can apply it in scenarios like log analysis, security investigations, or tracing system performance.

## For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    The `top` operator in APL is similar to `top` in Splunk SPL but allows greater flexibility in specifying multiple sorting criteria.

    <CodeGroup>
      ```sql Splunk example theme={null}
      index="sample_http_logs" | top limit=5 req_duration_ms
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | top 5 by req_duration_ms
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, the `TOP` operator is used with an `ORDER BY` clause to limit the number of rows. In APL, the syntax is similar but uses `top` in a pipeline and specifies the ordering criteria directly.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT TOP 5 req_duration_ms FROM sample_http_logs ORDER BY req_duration_ms DESC
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | top 5 by req_duration_ms
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
| top N by Expression [asc | desc]
```

### Parameters

* `N`: The number of rows to return.
* `Expression`: A scalar expression used for sorting. The type of the values must be numeric, date, time, or string.
* `[asc | desc]`: Optional. Use to sort in ascending or descending order. The default is descending.

### Returns

The `top` operator returns the top N rows from the dataset based on the specified sorting criteria.

## Use case examples

<Tabs>
  <Tab title="Log analysis">
    The `top` operator helps you find the HTTP requests with the longest durations.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | top 5 by req_duration_ms
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20top%205%20by%20req_duration_ms%22%7D)

    **Output**

    | \_time              | req\_duration\_ms | id  | status | uri              | method | geo.city | geo.country |
    | ------------------- | ----------------- | --- | ------ | ---------------- | ------ | -------- | ----------- |
    | 2024-10-01 10:12:34 | 5000              | 123 | 200    | /api/get-data    | GET    | New York | US          |
    | 2024-10-01 11:14:20 | 4900              | 124 | 200    | /api/post-data   | POST   | Chicago  | US          |
    | 2024-10-01 12:15:45 | 4800              | 125 | 200    | /api/update-item | PUT    | London   | UK          |

    This query returns the top 5 HTTP requests that took the longest time to process.
  </Tab>

  <Tab title="OpenTelemetry traces">
    The `top` operator is useful for identifying the spans with the longest duration in distributed tracing systems.

    **Query**

    ```kusto theme={null}
    ['otel-demo-traces']
    | top 5 by duration
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27otel-demo-traces%27%5D%20%7C%20top%205%20by%20duration%22%7D)

    **Output**

    | \_time              | duration | span\_id | trace\_id | service.name    | kind   | status\_code |
    | ------------------- | -------- | -------- | --------- | --------------- | ------ | ------------ |
    | 2024-10-01 10:12:34 | 300ms    | span123  | trace456  | frontend        | server | 200          |
    | 2024-10-01 10:13:20 | 290ms    | span124  | trace457  | cartservice     | client | 200          |
    | 2024-10-01 10:15:45 | 280ms    | span125  | trace458  | checkoutservice | server | 500          |

    This query returns the top 5 spans with the longest durations from the OpenTelemetry traces.
  </Tab>

  <Tab title="Security logs">
    The `top` operator is useful for identifying the most frequent HTTP status codes in security logs.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | summarize count() by status
    | top 3 by count_
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20summarize%20count\(\)%20by%20status%20%7C%20top%203%20by%20count_%22%7D)

    **Output**

    | status | count\_ |
    | ------ | ------- |
    | 200    | 500     |
    | 404    | 50      |
    | 500    | 20      |

    This query shows the top 3 most common HTTP status codes in security logs.
  </Tab>
</Tabs>

## List of related operators

* [order](/apl/tabular-operators/order-operator): Use when you need full control over row ordering without limiting the number of results.
* [summarize](/apl/tabular-operators/summarize-operator): Useful when aggregating data over fields and obtaining summarized results.
* [take](/apl/tabular-operators/take-operator): Returns the first N rows without sorting. Use when ordering isn’t necessary.