> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/min_by.md).

# min\_by

Use the `min_by()` function to return the value of one expression corresponding to the minimum value of another expression within a group.

## Syntax

```sql
min_by(<return_expression>, <sort_expression>)
```

## Parameters

| Name                | Type                              | Required | Description                                                                                                                                            |
| ------------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `return_expression` | any                               | Yes      | The expression whose value is returned. This is the value you want to retrieve.                                                                        |
| `sort_expression`   | integer, float, string, timestamp | Yes      | The expression used to determine the minimum. The row with the lowest value of this expression determines which `return_expression` value is returned. |

## Returns

**Type**: Same as `return_expression` type

**Description**: The `min_by()` function returns the value of `return_expression` from the row where `sort_expression` has its minimum value within the group. If the input is `null`, the function may skip null values.

## Usage notes

* **Input type**: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
* **Aggregation Function**: `min_by()` is an aggregation function and must be used with the `comp` stage or within a grouping context.
* **Null Handling**: Rows where `sort_expression` is `null` are typically ignored when determining the minimum.
* **Tie Breaking**: If multiple rows share the same minimum `sort_expression` value, the function returns the `return_expression` value from one of those rows (the specific row is not guaranteed).
* **Relationship to max\_by()**: The `min_by()` function is the counterpart of `max_by()`, which returns the value corresponding to the maximum.
* **Common Use Cases**: This function is used to find associated values at the point of minimum, such as finding the user with the lowest score, the timestamp of the earliest event, or the source of the smallest transaction.

## Examples

### Example 1: Find the event with the lowest numeric value

**Goal**: Retrieve the event ID associated with the minimum numeric value in the dataset.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| comp min_event = min_by(event_id, numeric_value)
| fields min_event
```

**Explanation**: The `min_by()` function finds the row with the lowest `numeric_value` and returns the corresponding `event_id`. This is useful for identifying which event had the minimum value.

**Output**:

| MIN\_EVENT |
| ---------- |
| 104        |

### Example 2: Find the earliest event details per category

**Goal**: For each event category, find the event ID of the earliest event.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| comp earliest_event = min_by(event_id, _time) by event_type
| fields event_type, earliest_event
| limit 3
```

**Explanation**: This query groups records by `event_type` and for each group, returns the `event_id` of the row with the earliest `_time` value. This identifies the first event in each category.

**Output**:

| EVENT\_TYPE | EARLIEST\_EVENT |
| ----------- | --------------- |
| login       | 101             |
| logout      | 103             |
| error       | 105             |

### Example 3: Find the source with the shortest duration

**Goal**: Identify which source host had the shortest duration event.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| comp shortest_source = min_by(source_name, duration_seconds)
| fields shortest_source
```

**Explanation**: The `min_by()` function finds the row with the lowest `duration_seconds` and returns the corresponding `source_name`, identifying which source experienced the shortest event.

**Output**:

| SHORTEST\_SOURCE |
| ---------------- |
| server-01        |

## Related articles

* **Stages**: [`comp`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/comp.md), [`fields`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/fields.md), [`limit`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/limit.md)
* **Functions**: [`max_by`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/max_by.md), [`least`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/least.md), [`first`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/first.md), [`last`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/last.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/min_by.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
