Limit Eager Loaded Relationships on Laravel Models

Introduction

Sometimes when you're eager loading relationships on Laravel models, you might want to limit the number of related models that are returned.

For example, on a blogging platform, you might want to load every author in the system along with three of their posts.

In older versions of Laravel, limiting eager loaded relationships was a bit of a fiddly task. I could never really find an elegant way to do it that felt right. So I usually installed Jonas Staudenmeir's (@staudenmeir) staudenmeir/eloquent-eager-limit package which adds this functionality.

However, at the beginning of this year, the core functionality behind that package was merged into the Laravel framework itself. So this means in Laravel 11, we can limit eager loaded relationships without needing to install any additional packages.

Let's take a look at an example.

Limiting Eager Loaded Relationships in Laravel

Let's say we have a blogging platform and we want to load every author in the system along with three of their posts.

We can achieve this using the limit method in the eager loading query:

use App\Models\Post;
use App\Models\Author;
use Illuminate\Contracts\Database\Eloquent\Builder;

$authors = Author::query()
    ->with([
        'posts' => fn (Builder $query): Builder => $query->limit(3),
    ])
    ->get();

As we can see in the code example above, we've defined that we want to eager load the posts relationship on the App\Models\Author model. In the eager loading query, we've used the limit method to specify that we only want to load three posts.

The Underlying SQL Queries

For anyone interested, the query above would generate two SQL queries.

The first query fetches the authors from the database:

SELECT * FROM `authors`

The second query fetches the three posts for each author (assuming we have 5 authors in the system):

SELECT *
FROM
    (
        SELECT
            *,
            row_number() OVER (PARTITION BY `posts`.`author_id`) AS `laravel_row`
        FROM `posts`
        WHERE `posts`.`author_id` IN (1, 2, 3, 4, 5)
    ) AS `laravel_table`
WHERE `laravel_row` <= 3
ORDER BY `laravel_row`