Implementation:Apache Paimon PagedList

Knowledge Sources	Apache_Paimon
Domains	Data Structures, Pagination
Last Updated	2026-02-08 00:00 GMT

Overview

PagedList is a generic container class that supports streaming data retrieval from paginated APIs.

Description

The PagedList class provides a standardized way to handle paginated data in Apache Paimon. It encapsulates a list of elements along with an optional token for retrieving the next page of results. This pattern is commonly used when working with external APIs or systems that return large result sets in chunks rather than all at once.

The class includes a utility method `listAllFromPagedApi` that automatically iterates through all pages by following the next page tokens, collecting all elements into a single list. This eliminates the need for manual pagination logic when the caller needs all results.

PagedList was introduced in version 1.1.0 to provide consistent pagination support across Paimon's various API integrations, particularly useful for catalog operations and metadata retrieval that may involve large datasets.

Usage

Use PagedList when implementing or consuming paginated APIs within Paimon. It's particularly useful for operations that retrieve lists of databases, tables, or other metadata objects where the full result set might be too large to return in a single response. The class simplifies both the producer side (returning paginated results) and consumer side (collecting all results) of paginated operations.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/PagedList.java

Signature

public class PagedList<T> {
    private final List<T> elements;
    @Nullable private final String nextPageToken;

    public PagedList(List<T> elements, @Nullable String nextPageToken)
    public List<T> getElements()
    @Nullable public String getNextPageToken()
    public static <T> List<T> listAllFromPagedApi(Function<String, PagedList<T>> pagedApi)
}

Import

import org.apache.paimon.PagedList;

I/O Contract

Inputs

Name	Type	Required	Description
elements	List<T>	Yes	The list of elements for this page
nextPageToken	String	No	Token to retrieve the next page; null if this is the last page
pagedApi	Function<String, PagedList<T>>	Yes	Function that takes a page token and returns the next page of results

Outputs

Name	Type	Description
elements	List<T>	The elements contained in this page
nextPageToken	String	Token for the next page, or null if no more pages exist
allElements	List<T>	Complete list of all elements across all pages (from listAllFromPagedApi)

Usage Examples

// Creating a PagedList response
List<Table> tables = fetchTablesFromMetastore(0, 100);
String nextToken = hasMoreTables ? "token_123" : null;
PagedList<Table> pagedResponse = new PagedList<>(tables, nextToken);

// Consuming a single page
List<Table> currentPage = pagedResponse.getElements();
String token = pagedResponse.getNextPageToken();

// Fetching all pages automatically
List<Table> allTables = PagedList.listAllFromPagedApi(pageToken -> {
    return catalogApi.listTables(database, pageToken);
});

// Example paged API implementation
public PagedList<Database> listDatabases(String pageToken) {
    int pageSize = 50;
    int offset = pageToken == null ? 0 : Integer.parseInt(pageToken);
    List<Database> databases = fetchDatabases(offset, pageSize);
    String nextToken = databases.size() == pageSize
        ? String.valueOf(offset + pageSize)
        : null;
    return new PagedList<>(databases, nextToken);
}

Related Pages

• Principle:Apache_Paimon_REST_Catalog_Protocol