Skip to content

Neontology

The Neontology backend pages the nodes of a label stored in Neo4j or Memgraph, and returns the same Page as the SQLModel backend.

Install and connect

$ pip install 'fastapi-object-pagination[neontology]'

The library runs its queries on the connection Neontology already holds: initialise Neontology once when the application starts, as its documentation explains. Nothing is passed to the pagination functions.

The models

The examples on this page use two labels and one relationship:

from neontology import BaseNode, BaseRelationship


class Person(BaseNode):
    __primarylabel__: str = "Person"
    __primaryproperty__: str = "name"

    name: str
    city: str


class Company(BaseNode):
    __primarylabel__: str = "Company"
    __primaryproperty__: str = "name"

    name: str


class WorksFor(BaseRelationship):
    __relationshiptype__: str = "WORKS_FOR"

    source: Person
    target: Company

A page of nodes

from fastapi import FastAPI

from fastapi_object_pagination import Page
from fastapi_object_pagination.neontology import paginate

from .models import Person

app = FastAPI()


@app.get("/people")
async def list_people(current_page: int = 1, items_by_page: int = 10) -> Page[Person]:
    return await paginate(
        model=Person,
        current_page=current_page,
        items_by_page=items_by_page,
    )

paginate asks Neontology for the number of Person nodes, then for the requested page, with SKIP and LIMIT. With three people in the graph, GET /people?items_by_page=2 returns:

{
  "items": [
    {"name": "Ada", "city": "London"},
    {"name": "Alan", "city": "London"}
  ],
  "item_count": 3,
  "page_count": 2,
  "current_page": 1,
  "items_by_page": 2,
  "previous_page_url": null,
  "next_page_url": "?current_page=2&items_by_page=2"
}

An API model in the page

When the page should carry something else than the node, pass a serializer: a function from the node to a Pydantic model. Each node of the page goes through it, and the page is typed on what it returns, here Page[PersonOut]:

from fastapi import FastAPI
from pydantic import BaseModel

from fastapi_object_pagination import Page
from fastapi_object_pagination.neontology import paginate

from .models import Person

app = FastAPI()


class PersonOut(BaseModel):
    label: str


def to_person_out(person: Person) -> PersonOut:
    return PersonOut(label=f"{person.name} ({person.city})")


@app.get("/people/labels")
async def list_labels(
    current_page: int = 1, items_by_page: int = 10
) -> Page[PersonOut]:
    return await paginate(
        model=Person,
        current_page=current_page,
        items_by_page=items_by_page,
        serializer=to_person_out,
    )

The counts and the URLs are those of the nodes: only the items change. serializer is a keyword argument, on paginate and on paginate_related.

Nodes connected to another label

paginate_related pages the nodes of a label that take part in a list of relationships, and accepts filters on every label those relationships reach. The employees of a company:

from fastapi import FastAPI

from fastapi_object_pagination import Page
from fastapi_object_pagination.neontology import paginate_related

from .models import Company, Person, WorksFor

app = FastAPI()


@app.get("/companies/{company}/employees")
async def list_employees(
    company: str, current_page: int = 1, items_by_page: int = 10
) -> Page[Person]:
    return await paginate_related(
        model=Person,
        relationships=[WorksFor],
        current_page=current_page,
        items_by_page=items_by_page,
        filters={(Company, "name__iexact"): company},
        ordering=["name"],
    )

For GET /companies/Acme/employees?current_page=3 it sends two queries, one for the page and one for the count:

MATCH (person:Person)
MATCH (person:Person)-[:WORKS_FOR]-(company:Company)
WHERE toLower(company.name) = toLower($filter_company_name_iexact)
RETURN DISTINCT person
ORDER BY person.name ASC SKIP $skip LIMIT $limit

MATCH (person:Person)
MATCH (person:Person)-[:WORKS_FOR]-(company:Company)
WHERE toLower(company.name) = toLower($filter_company_name_iexact)
RETURN COUNT(DISTINCT person)
  • Each relationship class becomes a MATCH between its source and target labels, in either direction.
  • Every node is bound to its label in lower case (person, company), so a filter on (Company, "name__iexact") reads company.name, and the clauses join on the labels they share.
  • RETURN DISTINCT and COUNT(DISTINCT ...) return and count each person once, however many relationships match them.
  • Values are sent as query parameters ($filter_company_name_iexact, $skip, $limit).
  • ordering sorts on properties of the paginated node.

Filtering a single label

Filters on paginate, in version 0.1.1

paginate hands its filters to Neontology's own match_nodes and get_count, which expect plain keys ({"city__iexact": "Paris"}), while its signature declares (node class, field) keys like paginate_related. With the declared keys, the query Neontology builds is invalid. Until this is fixed, filter a single label with paginate_related and an empty list of relationships, as below.

from fastapi import FastAPI

from fastapi_object_pagination import Page
from fastapi_object_pagination.neontology import paginate_related

from .models import Person

app = FastAPI()


@app.get("/people")
async def list_people(
    city: str, current_page: int = 1, items_by_page: int = 10
) -> Page[Person]:
    return await paginate_related(
        model=Person,
        relationships=[],
        current_page=current_page,
        items_by_page=items_by_page,
        filters={(Person, "city__iexact"): city},
        ordering=["name"],
    )

With no relationship, the query matches the label alone:

MATCH (person:Person)
WHERE toLower(person.city) = toLower($filter_person_city_iexact)
RETURN DISTINCT person
ORDER BY person.name ASC SKIP $skip LIMIT $limit

The calls

await paginate(
    model=Person,
    current_page=1,
    items_by_page=10,
    filters=None,
    serializer=None,
)

await paginate_related(
    model=Person,
    relationships=[WorksFor],
    current_page=1,
    items_by_page=10,
    filters=None,
    ordering=None,
    serializer=None,
)
Argument Default Meaning
model the Neontology node class to page, and the type of the items without a serializer
relationships paginate_related only: the relationship classes the nodes must take part in, possibly empty
current_page 1 the page to return, starting at 1
items_by_page 10 the size of a page
filters None a dictionary of (NodeClass, "field__lookup"): value filters, see filters
ordering None paginate_related only: property names of model, each descending when it starts with -
serializer None a function from a node to the Pydantic model the page carries

Good to know

  • The queries are synchronous. paginate and paginate_related are coroutines, like the SQLModel paginate, but Neontology talks to the database through the synchronous Neo4j driver: the event loop waits while the graph answers.
  • Property names are written into the Cypher text. Values are parameters, but the field names of the filters and of the ordering are not: build them in your code, never from what a client sends.
  • One variable per label. A relationship between two nodes of the same label, such as (:Person)-[:KNOWS]-(:Person), binds both ends to person, and only matches a node related to itself.
  • An unknown lookup is an equality. Where the SQLModel backend raises ValueError, paginate_related compares with = when the lookup after __ is not one it knows.