# group\_by

Groups an array of objects by a property value. Returns an array of groups, each with a `name` (the property value) and `items` (array of matching objects).

```liquid
{% assign grouped = products | group_by: "vendor" %}
{% for group in grouped %}
  {% log group.name | append: ": " | append: group.items.size | append: " products" %}
{% endfor %}
```

#### Syntax

```liquid
{{ array | group_by: property }}
```

| Parameter  | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `array`    | Array of objects to group                                               |
| `property` | Property name to group by (supports nested properties via dot notation) |

#### Return Value

Returns an array of group objects:

| Property | Type  | Description                                          |
| -------- | ----- | ---------------------------------------------------- |
| `name`   | any   | The property value shared by all items in this group |
| `items`  | Array | Array of items that have this property value         |

#### Examples

**Group orders by status:**

```liquid
{% assign grouped = orders | group_by: "financial_status" %}
{% for group in grouped %}
  {% log group.name | append: ": " | append: group.items.size | append: " orders" %}
{% endfor %}
```

Output:

```
paid: 42 orders
pending: 7 orders
refunded: 3 orders
```

**Group products by vendor and process each group:**

```liquid
{% assign by_vendor = products | group_by: "vendor" %}
{% for group in by_vendor %}
  {% log "Processing vendor: " | append: group.name %}
  {% for product in group.items %}
    {% log "  - " | append: product.title %}
  {% endfor %}
{% endfor %}
```

**Group by nested property:**

```liquid
{% assign by_country = orders | group_by: "shipping_address.country" %}
{% for group in by_country %}
  {% log group.name | append: ": " | append: group.items.size | append: " orders" %}
{% endfor %}
```

**Count items per group:**

```liquid
{% assign by_type = products | group_by: "product_type" %}
{% for group in by_type %}
  {% if group.items.size > 10 %}
    {% log group.name | append: " has " | append: group.items.size | append: " products" %}
  {% endif %}
{% endfor %}
```

#### Notes

* Groups are returned in the order their keys are first encountered
* Supports dot notation for nested properties: `"node.status"`, `"address.city"`
* For grouping with complex expressions, use `group_by_exp`
* For faster performance with direct key access, use `group_by_property` or `group_by_fast`
* See also: `group_by_exp`, `group_by_property`, `group_by_fast`


---

# Agent Instructions: 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:

```
GET https://docs.datajet-app.com/liquid/filters/group_by.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.