This page explains how to use the topkif aggregation in APL.
The topkif aggregation in Axiom Processing Language (APL) allows you to identify the top k values based on a specified field, while also applying a filter on another field. Use topkif when you want to find the most significant entries that meet specific criteria, such as the top-performing queries from a particular service, the most frequent errors for a specific HTTP method, or the highest latency requests from a specific country.
Use topkif when you need to focus on the most important filtered subsets of data, especially in log analysis, telemetry data, and monitoring systems. This aggregation helps you quickly zoom in on significant values without scanning the entire dataset.
The topkif aggregation in APL is a statistical aggregation that returns estimated results. The estimation provides the benefit of speed at the expense of precision. This means that topkif is fast and light on resources even on large or high-cardinality datasets but does not provide completely accurate results.
For completely accurate results, use the top operator together with a filter.
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.
Usage
Syntax
Parameters
Field: The field or expression to rank the results by.k: The number of top results to return.Condition: A logical expression that specifies the filtering condition.
Returns
A subset of the original dataset containing the top k values based on the specified field, after applying the filter condition.
Use case examples
Use topkif when analyzing HTTP logs to find the top 5 most frequent HTTP status codes for GET requests.
Query
Output
| status | count_ |
|---|---|
| 200 | 900 |
| 404 | 250 |
| 500 | 100 |
| 301 | 90 |
| 302 | 60 |
This query groups GET requests by HTTP status and returns the 5 most frequent statuses.
Use topkif when analyzing HTTP logs to find the top 5 most frequent HTTP status codes for GET requests.
Query
Output
| status | count_ |
|---|---|
| 200 | 900 |
| 404 | 250 |
| 500 | 100 |
| 301 | 90 |
| 302 | 60 |
This query groups GET requests by HTTP status and returns the 5 most frequent statuses.
Use topkif in OpenTelemetry traces to find the top five services for server.
Query
Output
| service.name | count_ |
|---|---|
| frontend-proxy | 99,573 |
| frontend | 91,800 |
| product-catalog | 29,696 |
| image-provider | 25,223 |
| flagd | 10,336 |
This query shows the top five services filtered to server.
Use topkif in security log analysis to find the top 5 cities generating GET HTTP requests.
Query
Output
| geo.city | count_ |
|---|---|
| New York | 300 |
| London | 250 |
| Paris | 200 |
| Tokyo | 180 |
| Berlin | 160 |
This query returns the top 5 cities generating the most GET HTTP requests.
List of related aggregations
- topk: Returns the top
kresults without filtering. Use topk when you do not need to restrict your analysis to a subset. - top: Returns the top results based on a field with accurate results. Use top when precision is important.
- sort: Sorts the dataset based on one or more fields. Use sort if you need full ordered results.
- extend: Adds calculated fields to your dataset, useful before applying topkif to create new fields to rank.
- count: Counts occurrences in the dataset. Use count when you only need counts without focusing on the top entries.`