---
title: "Partitions — Metrics for Laravel | Roundly"
description: "Grouped breakdowns for pie and bar charts — largest first, capped to the top N with an “Other” bucket, and mapped to display labels."
url: https://roundly-consulting.com/open-source/docs/metrics-for-laravel/partitions
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Metrics for Laravel](https://roundly-consulting.com/open-source/docs/metrics-for-laravel.md)

# Partitions

A partition groups rows by a column and aggregates each group — the data behind a pie or bar chart. Groups are ordered largest first:

```php
use App\Models\User;
use RoundlyConsulting\Metrics\Facades\Metrics;

Metrics::partition()->count(User::query(), 'plan')->toArray();
// result => ['partitions' => ['pro' => 120.0, 'free' => 80.0, ...]]   // largest first
```

sum(), average(), max() and min() take the same arguments — group by one column and aggregate another:

```php
// Revenue per country this month
Metrics::partition()->sum(Order::query(), 'country', 'total')->range('MTD')->toArray();
```

## Top N and the “Other” bucket

Cap a partition to its largest groups and roll the rest into a single bucket, so a chart stays readable:

```php
Metrics::partition()
    ->count(User::query(), 'country')
    ->limit(5)                       // 5 groups + "Other"
    ->otherLabel('Elsewhere')        // optional; defaults to the translatable "Other"
    ->toArray();
// result => ['partitions' => ['DE' => 120.0, ..., 'Elsewhere' => 35.0]]
```

The bucket is the rest rolled up with the metric’s own aggregate: summed for count() and sum(), the largest value for max(), the smallest for min(), and the average of all the remaining rows (not of the group averages) for average(). A real group whose key equals the bucket’s label is never one of the top N — it joins the bucket, so no group is overwritten.

The default label comes from metrics.partition.other\_label (“Other”) and runs through Laravel’s translator; otherLabel() overrides it per metric.

## The NULL group

```php
// Without a value column, count() counts rows — the NULL group is keyed ''
Metrics::partition()->count(User::query(), 'plan')->toArray();
// result => ['partitions' => ['pro' => 120.0, 'free' => 80.0, '' => 12.0]]
```

The NULL group and an empty-string group share the key '', so they are merged into one group with the metric’s aggregate — as the “Other” bucket is — instead of one overwriting the other, and the merged group is ranked by its merged value. A boolean column is keyed 0 / 1 on every database. The query’s own orderBy() is ignored: groups are always ranked by their aggregate.

## Custom labels

Map raw group keys — a country code, a foreign-key id — to display labels with labelUsing(). Raw keys stay under partitions, and the labels appear under an additional labels key. Labels are resolved on every read, never cached, and the “Other” bucket keeps its own label and is never passed to the resolver:

```php
Metrics::partition()
    ->count(User::query(), 'country_id')
    ->labelUsing(fn (int|string $key): string => Country::name($key))
    ->toArray();
// result => ['partitions' => ['1' => 40.0, ...], 'labels' => ['1' => 'Germany', ...]]
```

## Reading the result

- partitions() — group key → value.
- keys() — the raw group keys, regardless of any label resolver.
- labels() — the resolved labels when a resolver is set, otherwise the raw keys.
- values() — the values, in order.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/metrics-for-laravel.md)