From 15ceed7f05b87bb50b039ec1ccb8c4a461e81086 Mon Sep 17 00:00:00 2001
From: Mano Toth <mano@axiom.co>
Date: Thu, 9 Jan 2025 14:16:16 +0100
Subject: [PATCH 1/4] Add arg_min, arg_max

---
 apl/aggregation-function/arg-max.mdx          | 158 ++++++++++++++++++
 apl/aggregation-function/arg-min.mdx          | 146 ++++++++++++++++
 .../statistical-functions.mdx                 |   2 +
 mint.json                                     |   2 +
 4 files changed, 308 insertions(+)
 create mode 100644 apl/aggregation-function/arg-max.mdx
 create mode 100644 apl/aggregation-function/arg-min.mdx

diff --git a/apl/aggregation-function/arg-max.mdx b/apl/aggregation-function/arg-max.mdx
new file mode 100644
index 0000000..7e6db69
--- /dev/null
+++ b/apl/aggregation-function/arg-max.mdx
@@ -0,0 +1,158 @@
+---
+title: arg_max
+description: 'This page explains how to use the arg_max aggregation in APL.'
+---
+
+The `arg_max` aggregation in APL helps you identify the record with the maximum value for a specific numeric field and return one or more additional fields from that record. Use `arg_max` when you want to determine key details associated with a record having the maximum value, such as the longest request duration, highest transaction amount, or most significant span duration.
+
+This aggregation is particularly useful in scenarios like:
+
+- Pinpointing the slowest HTTP requests in log data.
+- Identifying the longest span durations in OpenTelemetry traces.
+- Highlighting the highest severity security alerts in logs.
+
+## 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">
+
+In Splunk SPL, you use `stats` with a combination of `max` and `by` clauses to achieve similar results. APL provides a dedicated `arg_max` aggregation that simplifies this process.
+
+<CodeGroup>
+```sql Splunk example
+| stats max(req_duration_ms) as max_duration by id, uri
+```
+
+```kusto APL equivalent
+['sample-http-logs']
+| summarize arg_max(req_duration_ms, id, uri)
+```
+</CodeGroup>
+
+</Accordion>
+<Accordion title="ANSI SQL users">
+
+In ANSI SQL, you typically use a subquery to find the maximum value and then join it back to the original table to retrieve additional fields. APL’s `arg_max` provides a more concise and efficient alternative.
+
+<CodeGroup>
+```sql SQL example
+WITH MaxValues AS (
+    SELECT id, MAX(req_duration_ms) as max_duration
+    FROM sample_http_logs
+    GROUP BY id
+)
+SELECT logs.id, logs.uri, MaxValues.max_duration
+FROM sample_http_logs logs
+JOIN MaxValues
+ON logs.id = MaxValues.id;
+```
+
+```kusto APL equivalent
+['sample-http-logs']
+| summarize arg_max(req_duration_ms, id, uri)
+```
+</CodeGroup>
+
+</Accordion>
+</AccordionGroup>
+
+## Usage
+
+### Syntax
+
+```kusto
+| summarize arg_max(numeric_field, field1[, field2, ...])
+```
+
+### Parameters
+
+| Parameter        | Description                                                                         |
+|------------------|-------------------------------------------------------------------------------------|
+| `numeric_field`  | The numeric field whose maximum value determines the selected record.             |
+| `field1, field2` | The additional fields to retrieve from the record with the maximum numeric value. |
+
+### Returns
+
+`arg_max` returns a row for each group (or the entire dataset if no grouping is specified), containing the fields specified in the query.
+
+## Use case examples
+
+<Tabs>
+<Tab title="Log analysis">
+
+Find the slowest HTTP request for each URI in the `['sample-http-logs']` dataset.
+
+**Query**
+
+```kusto
+['sample-http-logs']
+| summarize arg_max(req_duration_ms, method) by uri
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_max(req_duration_ms%2C%20method)%20by%20uri%22%7D)
+
+**Output**
+
+| uri               | method | req_duration_ms |
+|-------------------|--------|-----------------|
+| /home             | GET    | 1200            |
+| /api/products     | POST   | 2500            |
+
+This query identifies the slowest HTTP request for each URI along with the corresponding method.
+
+</Tab>
+<Tab title="OpenTelemetry traces">
+
+Identify the span with the longest duration for each service in the `['otel-demo-traces']` dataset.
+
+**Query**
+
+```kusto
+['otel-demo-traces']
+| summarize arg_max(duration, span_id, trace_id) by ['service.name']
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20arg_max(duration%2C%20span_id%2C%20trace_id)%20by%20%5B'service.name'%5D%22%7D)
+
+**Output**
+
+| service.name       | span_id  | trace_id  | duration |
+|--------------------|----------|-----------|----------|
+| frontend           | span123  | trace456  | 3s       |
+| checkoutservice    | span789  | trace012  | 5s       |
+
+This query identifies the span with the longest duration for each service, returning the `span_id`, `trace_id`, and `duration`.
+
+</Tab>
+<Tab title="Security logs">
+
+Find the highest status code for each country in the `['sample-http-logs']` dataset.
+
+**Query**
+
+```kusto
+['sample-http-logs']
+| summarize arg_max(toint(status), uri) by ['geo.country']
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_max(toint(status)%2C%20uri)%20by%20%5B'geo.country'%5D%22%7D)
+
+**Output**
+
+| geo.country  | uri               | status |
+|--------------|-------------------|--------|
+| USA          | /admin            | 500    |
+| Canada       | /dashboard        | 503    |
+
+This query identifies the URI with the highest status code for each country.
+
+</Tab>
+</Tabs>
+
+## List of related aggregations
+
+- [arg_min](/apl/aggregation-function/arg-min): Retrieves the record with the minimum value for a numeric field.
+- [max](/apl/aggregation-function/max): Retrieves the maximum value for a numeric field but does not return additional fields.
+- [percentile](/apl/aggregation-function/percentile): Provides the value at a specific percentile of a numeric field.
\ No newline at end of file
diff --git a/apl/aggregation-function/arg-min.mdx b/apl/aggregation-function/arg-min.mdx
new file mode 100644
index 0000000..d8a738f
--- /dev/null
+++ b/apl/aggregation-function/arg-min.mdx
@@ -0,0 +1,146 @@
+---
+title: arg_min
+description: 'This page explains how to use the arg_min aggregation in APL.'
+---
+
+The `arg_min` aggregation in APL allows you to identify the row in a dataset where a specific numeric field has the minimum value. You can use this to retrieve other associated fields in the same row, making it particularly useful for pinpointing details about the smallest value in large datasets. Typical use cases include identifying the shortest request duration in web logs, the fastest span duration in OpenTelemetry traces, or the lowest security risk score in logs.
+
+## 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">
+
+In Splunk SPL, achieving similar functionality involves using the `stats` command with the `values` or `first` functions after sorting by the desired field. In APL, `arg_min` simplifies this by directly providing the row with the minimum value for a given field.
+
+<CodeGroup>
+```sql Splunk example
+| stats min(req_duration_ms) as minDuration by id
+| where req_duration_ms=minDuration
+```
+
+```kusto APL equivalent
+['sample-http-logs']
+| summarize arg_min(req_duration_ms, id, uri)
+```
+</CodeGroup>
+
+</Accordion>
+<Accordion title="ANSI SQL users">
+
+In ANSI SQL, achieving similar functionality often requires a combination of `MIN`, `GROUP BY`, and `JOIN` to retrieve the associated fields. APL's `arg_min` eliminates the need for multiple steps by directly returning the row with the minimum value.
+
+<CodeGroup>
+```sql SQL example
+SELECT id, uri
+FROM sample_http_logs
+WHERE req_duration_ms = (
+    SELECT MIN(req_duration_ms)
+    FROM sample_http_logs
+);
+```
+
+```kusto APL equivalent
+['sample-http-logs']
+| summarize arg_min(req_duration_ms, id, uri)
+```
+</CodeGroup>
+
+</Accordion>
+</AccordionGroup>
+
+## Usage
+
+### Syntax
+
+```kusto
+| summarize arg_min(numeric_field, field1, ..., fieldN)
+```
+
+### Parameters
+
+- `numeric_field`: The numeric field to evaluate for the minimum value.
+- `field1, ..., fieldN`: Additional fields to return from the row with the minimum value.
+
+### Returns
+
+A single row containing the minimum value of the numeric field and the corresponding values of the specified additional fields.
+
+## Use case examples
+
+<Tabs>
+<Tab title="Log analysis">
+
+You can use `arg_min` to identify the HTTP request with the shortest duration and its associated details.
+
+**Query**
+
+```kusto
+['sample-http-logs']
+| summarize arg_min(req_duration_ms, uri, method)
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_min(req_duration_ms%2C%20uri%2C%20method)%22%7D)
+
+**Output**
+
+| req_duration_ms | uri                | method |
+|-----------------|--------------------|--------|
+| 12              | /api/login         | POST   |
+
+This query identifies the shortest HTTP request duration and provides details about the request.
+
+</Tab>
+<Tab title="OpenTelemetry traces">
+
+Use `arg_min` to find the span with the shortest duration and retrieve its associated details.
+
+**Query**
+
+```kusto
+['otel-demo-traces']
+| summarize arg_min(duration, trace_id, span_id, ['service.name'], kind)
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20arg_min(duration%2C%20trace_id%2C%20span_id%2C%20%5B'service.name'%5D%2C%20kind)%22%7D)
+
+**Output**
+
+| duration | trace_id   | span_id    | service.name       | kind     |
+|----------|------------|------------|--------------------|----------|
+| 00:00:01 | abc123     | span456    | frontend           | server   |
+
+This query identifies the span with the shortest duration along with its metadata.
+
+</Tab>
+<Tab title="Security logs">
+
+Find the lowest status code for each country in the `['sample-http-logs']` dataset.
+
+**Query**
+
+```kusto
+['sample-http-logs']
+| summarize arg_min(toint(status), uri) by ['geo.country']
+```
+
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_min(toint(status)%2C%20uri)%20by%20%5B'geo.country'%5D%22%7D)
+
+**Output**
+
+| geo.country  | uri               | status |
+|--------------|-------------------|--------|
+| USA          | /admin            | 200    |
+| Canada       | /dashboard        | 201    |
+
+This query identifies the URI with the lowest status code for each country.
+
+</Tab>
+</Tabs>
+
+## List of related aggregations
+
+- [arg_max](/apl/aggregation-function/arg-max): Returns the row with the maximum value for a numeric field, useful for finding peak metrics.
+- [min](/apl/aggregation-function/min): Returns only the minimum value of a numeric field without additional fields.
+- [percentile](/apl/aggregation-function/percentile): Provides the value at a specific percentile of a numeric field.
\ No newline at end of file
diff --git a/apl/aggregation-function/statistical-functions.mdx b/apl/aggregation-function/statistical-functions.mdx
index dbb71c3..867b7bc 100644
--- a/apl/aggregation-function/statistical-functions.mdx
+++ b/apl/aggregation-function/statistical-functions.mdx
@@ -10,6 +10,8 @@ The table summarizes the aggregation functions available in APL. Use all these a
 
 | Function               | Description                                                                                                   |
 | -------------------------------     | ----------------------------------------------------------------------------------------------------------------- |
+| [arg_min](/apl/aggregation-function/arg-min)                                        | Returns the row containing the minimum value of a numeric field.                                                                        |
+| [arg_max](/apl/aggregation-function/arg-max)                                        | Returns the row containing the maximum value of a numeric field                                                                        |
 | [avg](/apl/aggregation-function/avg)                                        | Returns an average value across the group.                                                                        |
 | [avgif](/apl/aggregation-function/avgif)                                    | Calculates the average value of an expression in records for which the predicate evaluates to true.                          |
 | [count](/apl/aggregation-function/count)                                    | Returns a count of the group without/with a predicate.                                                            |
diff --git a/mint.json b/mint.json
index b73f078..ce1c374 100644
--- a/mint.json
+++ b/mint.json
@@ -398,6 +398,8 @@
           "icon": "sigma",
           "pages": [
             "apl/aggregation-function/statistical-functions",
+            "apl/aggregation-function/arg-min",
+            "apl/aggregation-function/arg-max",
             "apl/aggregation-function/avg",
             "apl/aggregation-function/avgif",
             "apl/aggregation-function/count",

From c34e35391ac8178a4cf48c8d72c17b4bc9ca4323 Mon Sep 17 00:00:00 2001
From: Mano Toth <tothmano@gmail.com>
Date: Wed, 22 Jan 2025 15:03:20 +0100
Subject: [PATCH 2/4] Implement review

---
 apl/aggregation-function/arg-max.mdx | 20 ++++++++--------
 apl/aggregation-function/arg-min.mdx | 34 ++++++++++++++++------------
 2 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/apl/aggregation-function/arg-max.mdx b/apl/aggregation-function/arg-max.mdx
index 7e6db69..947bcbf 100644
--- a/apl/aggregation-function/arg-max.mdx
+++ b/apl/aggregation-function/arg-max.mdx
@@ -3,9 +3,9 @@ title: arg_max
 description: 'This page explains how to use the arg_max aggregation in APL.'
 ---
 
-The `arg_max` aggregation in APL helps you identify the record with the maximum value for a specific numeric field and return one or more additional fields from that record. Use `arg_max` when you want to determine key details associated with a record having the maximum value, such as the longest request duration, highest transaction amount, or most significant span duration.
+The `arg_max` aggregation in APL helps you identify the row with the maximum value for an expression and return additional fields from that record. Use `arg_max` when you want to determine key details associated with a row where the expressions evaluates to the maximum value. If you group your data, `arg_max` finds the row within each group where a particular expression evaluates to the maximum value.
 
-This aggregation is particularly useful in scenarios like:
+This aggregation is particularly useful in scenarios like the following:
 
 - Pinpointing the slowest HTTP requests in log data.
 - Identifying the longest span durations in OpenTelemetry traces.
@@ -18,7 +18,7 @@ If you come from other query languages, this section explains how to adjust your
 <AccordionGroup>
 <Accordion title="Splunk SPL users">
 
-In Splunk SPL, you use `stats` with a combination of `max` and `by` clauses to achieve similar results. APL provides a dedicated `arg_max` aggregation that simplifies this process.
+Splunk SPL doesn’t have an equivalent to `arg_max`. You can use `stats` with a combination of `max` and `by` clauses to evaluate the maximum value of a single numberic field. APL provides a dedicated `arg_max` aggregation that evaluates expressions.
 
 <CodeGroup>
 ```sql Splunk example
@@ -63,35 +63,35 @@ ON logs.id = MaxValues.id;
 ### Syntax
 
 ```kusto
-| summarize arg_max(numeric_field, field1[, field2, ...])
+| summarize arg_max(expression, field1[, field2, ...])
 ```
 
 ### Parameters
 
 | Parameter        | Description                                                                         |
 |------------------|-------------------------------------------------------------------------------------|
-| `numeric_field`  | The numeric field whose maximum value determines the selected record.             |
+| `expression`  | The expression whose maximum value determines the selected record.             |
 | `field1, field2` | The additional fields to retrieve from the record with the maximum numeric value. |
 
 ### Returns
 
-`arg_max` returns a row for each group (or the entire dataset if no grouping is specified), containing the fields specified in the query.
+Returns a row where the expression evaluates to the maximum value for each group (or the entire dataset if no grouping is specified), containing the fields specified in the query.
 
 ## Use case examples
 
 <Tabs>
 <Tab title="Log analysis">
 
-Find the slowest HTTP request for each URI in the `['sample-http-logs']` dataset.
+Find the slowest path for each HTTP method in the `['sample-http-logs']` dataset.
 
 **Query**
 
 ```kusto
 ['sample-http-logs']
-| summarize arg_max(req_duration_ms, method) by uri
+| summarize arg_max(req_duration_ms, uri) by method
 ```
 
-[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_max(req_duration_ms%2C%20method)%20by%20uri%22%7D)
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_max(req_duration_ms%2C%20uri)%20by%20method%22%7D)
 
 **Output**
 
@@ -100,7 +100,7 @@ Find the slowest HTTP request for each URI in the `['sample-http-logs']` dataset
 | /home             | GET    | 1200            |
 | /api/products     | POST   | 2500            |
 
-This query identifies the slowest HTTP request for each URI along with the corresponding method.
+This query identifies the slowest path for each HTTP method.
 
 </Tab>
 <Tab title="OpenTelemetry traces">
diff --git a/apl/aggregation-function/arg-min.mdx b/apl/aggregation-function/arg-min.mdx
index d8a738f..aea3dd2 100644
--- a/apl/aggregation-function/arg-min.mdx
+++ b/apl/aggregation-function/arg-min.mdx
@@ -3,7 +3,13 @@ title: arg_min
 description: 'This page explains how to use the arg_min aggregation in APL.'
 ---
 
-The `arg_min` aggregation in APL allows you to identify the row in a dataset where a specific numeric field has the minimum value. You can use this to retrieve other associated fields in the same row, making it particularly useful for pinpointing details about the smallest value in large datasets. Typical use cases include identifying the shortest request duration in web logs, the fastest span duration in OpenTelemetry traces, or the lowest security risk score in logs.
+The `arg_min` aggregation in APL allows you to identify the row in a dataset where an expression evaluates to the minimum value. You can use this to retrieve other associated fields in the same row, making it particularly useful for pinpointing details about the smallest value in large datasets. If you group your data, `arg_min` finds the row within each group where a particular expression evaluates to the minimum value.
+
+This aggregation is particularly useful in scenarios like the following:
+
+- Pinpointing the shortest request duration in web logs.
+- Identifying the fastest span duration in OpenTelemetry traces.
+- Highlighting or the lowest security risk score in logs.
 
 ## For users of other query languages
 
@@ -12,7 +18,7 @@ If you come from other query languages, this section explains how to adjust your
 <AccordionGroup>
 <Accordion title="Splunk SPL users">
 
-In Splunk SPL, achieving similar functionality involves using the `stats` command with the `values` or `first` functions after sorting by the desired field. In APL, `arg_min` simplifies this by directly providing the row with the minimum value for a given field.
+Splunk SPL doesn’t have an equivalent to `arg_min`. You can use `stats` with a combination of `values` and `first` clauses to evaluate the minimum value of a single numberic field. APL provides a dedicated `arg_min` aggregation that evaluates expressions.
 
 <CodeGroup>
 ```sql Splunk example
@@ -55,55 +61,55 @@ WHERE req_duration_ms = (
 ### Syntax
 
 ```kusto
-| summarize arg_min(numeric_field, field1, ..., fieldN)
+| summarize arg_min(expression, field1, ..., fieldN)
 ```
 
 ### Parameters
 
-- `numeric_field`: The numeric field to evaluate for the minimum value.
+- `expression`: The expression to evaluate for the minimum value.
 - `field1, ..., fieldN`: Additional fields to return from the row with the minimum value.
 
 ### Returns
 
-A single row containing the minimum value of the numeric field and the corresponding values of the specified additional fields.
+Returns a row where the expression evaluates to the minimum value for each group (or the entire dataset if no grouping is specified), containing the fields specified in the query.
 
 ## Use case examples
 
 <Tabs>
 <Tab title="Log analysis">
 
-You can use `arg_min` to identify the HTTP request with the shortest duration and its associated details.
+You can use `arg_min` to identify the path with the shortest duration and its associated details for each method.
 
 **Query**
 
 ```kusto
 ['sample-http-logs']
-| summarize arg_min(req_duration_ms, uri, method)
+| summarize arg_min(req_duration_ms, uri) by method
 ```
 
-[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_min(req_duration_ms%2C%20uri%2C%20method)%22%7D)
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20arg_min(req_duration_ms%2C%20uri)%20by%20method%22%7D)
 
 **Output**
 
 | req_duration_ms | uri                | method |
 |-----------------|--------------------|--------|
-| 12              | /api/login         | POST   |
+| 0.1              | /api/login         | POST   |
 
-This query identifies the shortest HTTP request duration and provides details about the request.
+This query identifies the paths with the shortest duration for each method and provides details about the path.
 
 </Tab>
 <Tab title="OpenTelemetry traces">
 
-Use `arg_min` to find the span with the shortest duration and retrieve its associated details.
+Use `arg_min` to find the span with the shortest duration for each service and retrieve its associated details.
 
 **Query**
 
 ```kusto
 ['otel-demo-traces']
-| summarize arg_min(duration, trace_id, span_id, ['service.name'], kind)
+| summarize arg_min(duration, trace_id, span_id, kind) by ['service.name']
 ```
 
-[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20arg_min(duration%2C%20trace_id%2C%20span_id%2C%20%5B'service.name'%5D%2C%20kind)%22%7D)
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20arg_min(duration%2C%20trace_id%2C%20span_id%2C%20kind)%20by%20%5B'service.name'%5D%22%7D)
 
 **Output**
 
@@ -111,7 +117,7 @@ Use `arg_min` to find the span with the shortest duration and retrieve its assoc
 |----------|------------|------------|--------------------|----------|
 | 00:00:01 | abc123     | span456    | frontend           | server   |
 
-This query identifies the span with the shortest duration along with its metadata.
+This query identifies the span with the shortest duration for each service along with its metadata.
 
 </Tab>
 <Tab title="Security logs">

From 4e0e7fe17004532e46bf05e8fbe4bbbfb53c8115 Mon Sep 17 00:00:00 2001
From: Mano Toth <tothmano@gmail.com>
Date: Wed, 22 Jan 2025 15:12:28 +0100
Subject: [PATCH 3/4] Fixes

---
 apl/aggregation-function/arg-max.mdx               | 8 ++++----
 apl/aggregation-function/arg-min.mdx               | 6 +++---
 apl/aggregation-function/statistical-functions.mdx | 4 ++--
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/apl/aggregation-function/arg-max.mdx b/apl/aggregation-function/arg-max.mdx
index 947bcbf..9105c57 100644
--- a/apl/aggregation-function/arg-max.mdx
+++ b/apl/aggregation-function/arg-max.mdx
@@ -3,13 +3,13 @@ title: arg_max
 description: 'This page explains how to use the arg_max aggregation in APL.'
 ---
 
-The `arg_max` aggregation in APL helps you identify the row with the maximum value for an expression and return additional fields from that record. Use `arg_max` when you want to determine key details associated with a row where the expressions evaluates to the maximum value. If you group your data, `arg_max` finds the row within each group where a particular expression evaluates to the maximum value.
+The `arg_max` aggregation in APL helps you identify the row with the maximum value for an expression and return additional fields from that record. Use `arg_max` when you want to determine key details associated with a row where the expression evaluates to the maximum value. If you group your data, `arg_max` finds the row within each group where a particular expression evaluates to the maximum value.
 
 This aggregation is particularly useful in scenarios like the following:
 
-- Pinpointing the slowest HTTP requests in log data.
-- Identifying the longest span durations in OpenTelemetry traces.
-- Highlighting the highest severity security alerts in logs.
+- Pinpoint the slowest HTTP requests in log data.
+- Identify the longest span durations in OpenTelemetry traces.
+- Highlight the highest severity security alerts in logs.
 
 ## For users of other query languages
 
diff --git a/apl/aggregation-function/arg-min.mdx b/apl/aggregation-function/arg-min.mdx
index aea3dd2..fbeb20e 100644
--- a/apl/aggregation-function/arg-min.mdx
+++ b/apl/aggregation-function/arg-min.mdx
@@ -7,9 +7,9 @@ The `arg_min` aggregation in APL allows you to identify the row in a dataset whe
 
 This aggregation is particularly useful in scenarios like the following:
 
-- Pinpointing the shortest request duration in web logs.
-- Identifying the fastest span duration in OpenTelemetry traces.
-- Highlighting or the lowest security risk score in logs.
+- Pinpoint the shortest request duration in web logs.
+- Identify the fastest span duration in OpenTelemetry traces.
+- Highlight the lowest security risk score in logs.
 
 ## For users of other query languages
 
diff --git a/apl/aggregation-function/statistical-functions.mdx b/apl/aggregation-function/statistical-functions.mdx
index 867b7bc..411043c 100644
--- a/apl/aggregation-function/statistical-functions.mdx
+++ b/apl/aggregation-function/statistical-functions.mdx
@@ -10,8 +10,8 @@ The table summarizes the aggregation functions available in APL. Use all these a
 
 | Function               | Description                                                                                                   |
 | -------------------------------     | ----------------------------------------------------------------------------------------------------------------- |
-| [arg_min](/apl/aggregation-function/arg-min)                                        | Returns the row containing the minimum value of a numeric field.                                                                        |
-| [arg_max](/apl/aggregation-function/arg-max)                                        | Returns the row containing the maximum value of a numeric field                                                                        |
+| [arg_min](/apl/aggregation-function/arg-min)                                        | Returns the row where an expression evaluates to the minimum value.                                                                        |
+| [arg_max](/apl/aggregation-function/arg-max)                                        | Returns the row where an expression evaluates to the maximum value.                                                                        |
 | [avg](/apl/aggregation-function/avg)                                        | Returns an average value across the group.                                                                        |
 | [avgif](/apl/aggregation-function/avgif)                                    | Calculates the average value of an expression in records for which the predicate evaluates to true.                          |
 | [count](/apl/aggregation-function/count)                                    | Returns a count of the group without/with a predicate.                                                            |

From adf15fb672de2a025ccb2a15bc34e6367c97638f Mon Sep 17 00:00:00 2001
From: Mano Toth <tothmano@gmail.com>
Date: Thu, 23 Jan 2025 12:01:59 +0100
Subject: [PATCH 4/4] Implement review

---
 apl/aggregation-function/arg-max.mdx | 6 +++---
 apl/aggregation-function/arg-min.mdx | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/apl/aggregation-function/arg-max.mdx b/apl/aggregation-function/arg-max.mdx
index 9105c57..e73fcbb 100644
--- a/apl/aggregation-function/arg-max.mdx
+++ b/apl/aggregation-function/arg-max.mdx
@@ -7,9 +7,9 @@ The `arg_max` aggregation in APL helps you identify the row with the maximum val
 
 This aggregation is particularly useful in scenarios like the following:
 
-- Pinpoint the slowest HTTP requests in log data.
-- Identify the longest span durations in OpenTelemetry traces.
-- Highlight the highest severity security alerts in logs.
+- Pinpoint the slowest HTTP requests in log data and retrieve associated details (like URL, status code, and user agent) for the same row.
+- Identify the longest span durations in OpenTelemetry traces with additional context (like span name, trace ID, and attributes) for the same row.
+- Highlight the highest severity security alerts in logs along with relevant metadata (such as alert type, source, and timestamp) for the same row.
 
 ## For users of other query languages
 
diff --git a/apl/aggregation-function/arg-min.mdx b/apl/aggregation-function/arg-min.mdx
index fbeb20e..bc73da3 100644
--- a/apl/aggregation-function/arg-min.mdx
+++ b/apl/aggregation-function/arg-min.mdx
@@ -7,9 +7,9 @@ The `arg_min` aggregation in APL allows you to identify the row in a dataset whe
 
 This aggregation is particularly useful in scenarios like the following:
 
-- Pinpoint the shortest request duration in web logs.
-- Identify the fastest span duration in OpenTelemetry traces.
-- Highlight the lowest security risk score in logs.
+- Pinpoint the shortest HTTP requests in log data and retrieve associated details (like URL, status code, and user agent) for the same row.
+- Identify the fastest span durations in OpenTelemetry traces with additional context (like span name, trace ID, and attributes) for the same row.
+- Highlight the lowest severity security alerts in logs along with relevant metadata (such as alert type, source, and timestamp) for the same row.
 
 ## For users of other query languages