Features¶
One page, whatever the storage¶
It was extracted from a production application that reads part of its data from PostgreSQL and part of it from a Neo4j knowledge graph, and exposes both through the same REST API. FastAPI pagination libraries cover SQLAlchemy well and graph stores not at all, so each backend ended up with its own page format and the frontend had to special case them. Pulling the page object out into a library forced a single contract on both sides.
That contract is Page, a generic Pydantic model:
| Field | Type | Content |
|---|---|---|
items |
list[M] |
the items of the requested page |
item_count |
int |
the number of items matching the filters, on every page |
page_count |
int |
item_count divided by items_by_page, rounded up |
current_page |
int |
the page that was asked for, starting at 1 |
items_by_page |
int |
the page size that was asked for |
previous_page_url |
str or None |
the query string of the previous page, None on the first page |
next_page_url |
str or None |
the query string of the next page, None on the last page |
The reference gives the exact rules for each field.
Typed from the call to the schema¶
Each entry point is generic over the model it reads:
paginate(model=Book, ...)fromfastapi_object_pagination.sqlmodelreturns aPage[Book];paginate(model=Person, ...)andpaginate_related(model=Person, ...)fromfastapi_object_pagination.neontologyreturn aPage[Person];- with
serializer=to_person_out, the same Neontology calls return aPage[PersonOut], the type the serializer returns.
The package ships its type information (py.typed), so mypy checks the value an endpoint returns against its declared Page[...], and FastAPI turns that declaration into an OpenAPI schema named after the item type (Page_Book_), with items typed as Book.
Two backends, one vocabulary¶
| SQLModel | Neontology | |
|---|---|---|
| Import | fastapi_object_pagination.sqlmodel |
fastapi_object_pagination.neontology |
| Entry points | paginate |
paginate, paginate_related |
| Runs on | an AsyncSession you pass in |
the Neontology connection of the application |
| Filter keys | "field__lookup" |
(NodeClass, "field__lookup") |
| Ordering | paginate |
paginate_related |
| Serializer | no | both entry points |
The SQLModel and Neontology pages show each backend in an application.
Django style filters¶
Both backends take the same lookups, written after a double underscore: exact, iexact, contains, icontains, startswith, istartswith, endswith, iendswith, gt, gte, lt, lte, in and isnull. A key without a lookup means exact. Every filter narrows the count as well as the items, and several filters are combined with AND.
SQLModel keys are field names ("author__iexact"). Neontology keys are (node_class, field_lookup) tuples, because a Cypher query can match several labels at once and filter on any of them.
On PostgreSQL, the in lookup compiles to = ANY(...), with the whole list bound as one array parameter, instead of IN (...), which plans better on long lists. Other dialects keep IN.
The filters page gives the SQL and the Cypher each lookup becomes.
Ordering¶
ordering is a list of field names, applied in order, each one descending when it starts with -: ["-year", "title"] sorts the most recent books first, and books of the same year by title.
Pages across relationships¶
paginate_related pages the nodes of one label that take part in a list of relationships, and filters on any label those relationships reach: the employees of a company, the people living in a city. It counts and returns each node once, however many relationships match it.
Serializers¶
A Neontology page can carry an API model rather than the node that was queried: pass serializer, a function from the node to a Pydantic model, and each item is converted before the page is built. The counts and the URLs do not change, and the page is typed on what the serializer returns.
Optional backends¶
Pydantic is the only required dependency. Each backend is an extra, sqlmodel or neontology, and importing a backend whose extra is missing fails at once with the command that installs it:
ImportError: ORM 'neontology' needs extra dependencies. Please run: uv add 'fastapi-object-pagination[neontology]'
rather than with a bare ModuleNotFoundError from deep inside the call stack. The sqlmodel extra also installs sqlalchemy[asyncio], which brings the greenlet package an AsyncSession cannot run without.
Compatibility¶
| Python | 3.11, 3.12, 3.13 |
| Pydantic | 2.x |
| SQLModel | 0.0.25 or later, with an async engine |
| Neontology | 2.2.2 or later |
The test suite runs on each of these Python versions.