> 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/values.md).

# values

Use the `values()` function to collect all distinct (unique) values of a specified field across grouped rows within the `comp` stage and return them as an array. This is similar to `ARRAY_AGG(DISTINCT ...)` in SQL.

## Syntax

```sql
| comp values(<field>) [by <group_field1>, <group_field2>, ...] [as <alias>]
```

## Parameters

| Name          | Type   | Required | Description                                                                                          |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `field`       | any    | Yes      | The field whose distinct values will be collected into an array.                                     |
| `group_field` | any    | No       | One or more fields to group the results by. If omitted, all rows are treated as a single group.      |
| `alias`       | string | No       | An alias for the output field. If not specified, the output field name defaults to `values_<field>`. |

## Returns

**Type**: array

**Description**: The `values()` function returns an array containing all distinct (unique) values of the specified field within each group. NULL values may be excluded. The order of elements in the array is not guaranteed.

## Usage notes

* **Distinct values**: Unlike the `list()` function which collects all values including duplicates, `values()` returns only unique values.
* **Data types**: Works with any data type (string, numeric, datetime, etc.).
* **Null handling**: NULL values are typically excluded from the result array.
* **No ordering**: The order of elements in the resulting array is not guaranteed.
* **No grouping**: When used without a `by` clause, all rows are aggregated into a single group.
* **Use case**: Useful for finding all unique values of a field within groups, such as all unique users who accessed a resource.

## Examples

### Example 1: Distinct source IPs per destination

**Goal**: Find all unique source IP addresses that connected to each destination IP.

**XQL code**:

```sql
dataset = xdr_data
| comp values(action_local_ip) by action_remote_ip as unique_source_ips
```

**Explanation**: The `values()` function collects all distinct `action_local_ip` values for each unique `action_remote_ip`, eliminating duplicate IPs.

**Output**:

| ACTION\_REMOTE\_IP | UNIQUE\_SOURCE\_IPS           |
| ------------------ | ----------------------------- |
| 10.0.0.1           | \[192.168.1.10, 192.168.1.20] |
| 10.0.0.2           | \[192.168.1.30]               |

### Example 2: All unique usernames across events

**Goal**: Find all distinct usernames across all events.

**XQL code**:

```sql
dataset = xdr_data
| comp values(actor_effective_username) as unique_users
```

**Explanation**: Without a `by` clause, the `values()` function collects all distinct `actor_effective_username` values across the entire dataset.

**Output**:

| UNIQUE\_USERS                        |
| ------------------------------------ |
| \[admin, user1, user2, svc\_account] |

### Example 3: Distinct event types per host

**Goal**: Find all unique event types observed on each host.

**XQL code**:

```sql
dataset = xdr_data
| comp values(event_type) by agent_hostname as event_types, count(*) as total_events
```

**Explanation**: This query combines `values()` with `count()` to show both the distinct event types and the total event count per host.

**Output**:

| AGENT\_HOSTNAME | EVENT\_TYPES              | TOTAL\_EVENTS |
| --------------- | ------------------------- | ------------- |
| workstation-1   | \[NETWORK, PROCESS, FILE] | 150           |
| workstation-2   | \[NETWORK, REGISTRY]      | 85            |

## Related articles

* **Stages**: [`comp`](/xql-command-reference-guide/readme/stages/comp.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.md)
* **Functions**: [`list()`](/xql-command-reference-guide/readme/functions/list_with_comp_stage.md), [`count()`](/xql-command-reference-guide/readme/functions/count_with_comp_stage.md), [`count_distinct()`](/xql-command-reference-guide/readme/functions/count_distinct.md)
* **Datasets**: [`xdr_data`](https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.