---
title: "Feature: #102194 - Introduce QueryBuilderPaginator"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:feature-102194-1772779432"
source: "Changelog/14.2/Feature-102194-QueryBuilderPaginator.rst"
typo3-version: "14.2"
typo3-major: 14
type: "feature"
issue: 102194
forge: "https://forge.typo3.org/issues/102194"
tags: ["Database", "PHP-API", "ext:core"]
rendered: "2026-09-20T18:31:11+00:00"
---

# Feature: #102194 - Introduce QueryBuilderPaginator {#feature-102194-1772779432}

See [forge#102194](https://forge.typo3.org/issues/102194)

## Description {#description}

A new `\TYPO3\CMS\Core\Pagination\QueryBuilderPaginator` is introduced to
enable pagination of
`QueryBuilder` instances.

The paginator implements the existing
`PaginatorInterface` and integrates
seamlessly with the existing
`SimplePagination` and
`SlidingWindowPagination` classes.

The paginated items are fetched only once per page request by storing the
result internally, avoiding double execution of the database statement.

The total item count is determined robustly using a common table expression
(CTE) wrapping the passed `QueryBuilder` instance. This approach correctly
handles advanced queries involving `UNION`, nested CTEs, window functions, and
grouping.

> [!NOTE]
> The `QueryBuilderPaginator` does
> **not** handle language overlays. Applying overlays to the result set can
> lead to unexpected item count differences between pages when some records
> are hidden after overlay processing. Use
> `QueryResultPaginator` or
> `ArrayPaginator` when language
> overlay handling is required.
>
> The paginator also takes **full control** over `LIMIT` and `OFFSET`
> and does not respect any existing limit or offset constraints on the
> passed `QueryBuilder` instance.

## Impact {#impact}

A new `QueryBuilderPaginator` is
available to paginate
`QueryBuilder` result sets using
the TYPO3 pagination API.

### Example {#example}

**EXT:my_extension/Classes/Controller/MyController.php**

```php
use TYPO3\CMS\Core\Pagination\QueryBuilderPaginator;
use TYPO3\CMS\Core\Pagination\SimplePagination;

$paginator = new QueryBuilderPaginator(
    queryBuilder: $queryBuilder,
    currentPageNumber: $currentPage,
    itemsPerPage: 10,
);
$pagination = new SimplePagination($paginator);

// Retrieve the items for the current page
$items = $paginator->getPaginatedItems();
```