Relationship Aggregates

✨ Overview

Relationship aggregates allow you to display data from related models using Eloquent's built-in aggregate methods. This is similar to Filament Tables' relationship support and works seamlessly with existing Laravel relationships.

1 Basic Relationships (hasOne/BelongsTo)

Use dot notation to access related model data. The table automatically joins the necessary tables:

// Display address from related Address model
Column::make('Address', 'address.address')
    ->sortable()
    ->searchable(),

// Nested relationships
Column::make('City', 'address.group.city.name')
    ->sortable(),

2 Counting Relationships

Use CountColumn to display the number of related records:

// Count all related records
CountColumn::make('Articles')
    ->setDataSource('articles')
    ->sortable(),

// Scoped counts have no column-level API in v3 -
// add them in builder() and render with label()
public function builder(): Builder
{
    return User::query()->withCount([
        'articles as published_articles_count' => fn($q) => $q->where('is_published', true),
    ]);
}

Column::make('Published')
    ->label(fn($row) => $row->published_articles_count . ' published'),

// Count belongsToMany relationship
CountColumn::make('Tags')
    ->setDataSource('tags')
    ->sortable(),

3 Displaying Relationship Collections

Show collections from hasMany or belongsToMany relationships:

// Display article titles (limit is applied inside data())
ArrayColumn::make('Articles')
    ->data(fn($value, $row) => $row->articles->take(3))
    ->outputFormat(fn($index, $value) => e($value->title))
    ->separator(' | '),

// Display tags with custom formatting
ArrayColumn::make('Tags')
    ->data(fn($value, $row) => $row->tags)
    ->outputFormat(fn($index, $value) => '<span>' . e($value->name) . '</span>')
    ->flexRow(['class' => 'flex-wrap gap-1']),

4 Sum Aggregate

Use SumColumn to total a column from related records. The package auto-registers withSum() on the builder for you. In the demo above, the "Published Sum" column sums the boolean is_published flag on the articles relation — the sum of a 0/1 column is the number of published articles:

// Sum a column on a relation (exposed on the row as articles_sum_is_published)
SumColumn::make('Published Sum')
    ->setDataSource('articles', 'is_published')
    ->sortable()
    ->footer(fn($rows) => 'Total: ' . ($rows->sum('articles_sum_is_published') ?? 0)),

// Scoped sums are not available on the column in v3 -
// use withSum() in builder() and render with label()

5 Average Aggregate

Use AvgColumn to calculate the average (withAvg() is auto-registered on the builder). The "Publish Rate" column above averages the boolean is_published flag and overrides the default output with label() to render a percentage:

// Average a column on a relation (exposed as articles_avg_is_published)
AvgColumn::make('Publish Rate')
    ->setDataSource('articles', 'is_published')
    ->sortable()
    // Optional: label() overrides the raw average with custom formatting
    ->label(fn($row) => round(($row->articles_avg_is_published ?? 0) * 100) . '%'),

6 Min/Max Aggregates

Not available in v3. There is no min/max aggregate column - only CountColumn, SumColumn and AvgColumn. Use Eloquent in builder() instead:

public function builder(): Builder
{
    return User::query()
        ->withMin('orders', 'created_at')
        ->withMax('orders', 'created_at');
}

Column::make('First Order')
    ->label(fn($row) => $row->orders_min_created_at ?? 'Never'),

Column::make('Last Order')
    ->label(fn($row) => $row->orders_max_created_at ?? 'Never'),

7 Column Naming Convention

Column names must follow Laravel's naming convention: