### group

Supported in:

    group(field1, field2, field3, ...)

#### Description

Group fields of a similar type into a placeholder variable.

In UDM search, [grouped
fields](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search#search_grouped_fields) are used to search across multiple fields of a similar type. The group
function is similar to grouped fields except that it lets you select which fields you want
grouped together to trigger a detection. You can use the group function for gathering information about a specific entity (for example, a hostname, IP address, or userid) across different [Noun types](https://docs.cloud.google.com/chronicle/docs/reference/udm-field-list#noun).

> [!NOTE]
> **Note:** For search, you can use grouped fields in the `events` section, but not in the `match` and `outcome` sections. For more details, [`events` section syntax](https://docs.cloud.google.com/chronicle/docs/yara-l/events-syntax), [`match` section syntax](https://docs.cloud.google.com/chronicle/docs/yara-l/match-syntax), and [`outcome` section syntax](https://docs.cloud.google.com/chronicle/docs/yara-l/outcome-syntax).

- Parameter type: `Event type`

- Return type: `Grouped event fields`

#### Code samples

**Example: Aggregate and count IP addresses**

Group all IP addresses together and provide a descending count of the most prevalent IP addresses in the time range scanned.

    $ip = group(principal.ip, about.ip, target.ip)
    $ip != ""
    match:
      $ip

    outcome:
      $count = count_distinct(metadata.id)

    order:
      $count desc

**Example: Count distinct events for each IP address**

In the following example, the `group()` function gathers all the IP addresses
found in the `principal.ip`, `target.ip`, and `src.ip` fields across all events
that triggered the detection. The IP addresses are then added to the placeholder
variable `$ip`. The rule then matches the IP address and returns a count of
distinct events for each unique IP address.

    $ip = group(detection.collection_elements.references.event.principal.ip, detection.collection_elements.references.event.target.ip, detection.collection_elements.references.event.src.ip)
    $ip != ""

    match:
      $ip

    outcome:
      $count = count_distinct(detection.id)

    order:
      $count desc

    // Detection1: principal.ip = 1.1.1.1
    // Detection2: src.ip = 1.1.1.1, target.ip = 2.2.2.2
    // Detection3: target.ip = 1.1.1.1
    // Detection4: principal.ip = 2.2.2.2

Result:

| `$ip` | `$count` |
|---|---|
| 1.1.1.1 | 3 |
| 2.2.2.2 | 2 |