Skip to content

Backend (base)

pylpg.backend.base

Abstract base class for database backends.

Classes:

Name Description
Backend

Abstract base class that all database backends must implement.

Backend

Bases: ABC

Abstract base class that all database backends must implement.

Backends handle all direct database operations: CRUD for nodes and relationships, batch operations, traversal, and query execution.

Methods:

Name Description
deserialize_node

Return a node record as a dict of its properties.
deserialize_relationship

Return a relationship record as a dict of its properties.
result_set_limit

Maximum number of rows a single query may return.
traverse_batch

Traverse from many source nodes at once.

deserialize_node abstractmethod 

deserialize_node(record: Any) -> dict[str, Any]

Return a node record as a dict of its properties.

The dict also carries _labels and _database_id.

Source code in src/pylpg/backend/base.py 
30
31
32
33
34
35
36
@abc.abstractmethod
def deserialize_node(self, record: typing.Any) -> dict[str, typing.Any]:
    """Return a node record as a dict of its properties.

    The dict also carries `_labels` and `_database_id`.
    """
    ...

deserialize_relationship abstractmethod 

deserialize_relationship(record: Any) -> dict[str, Any]

Return a relationship record as a dict of its properties.

The dict also carries _database_id, _start_id and _end_id. The record must come from a matched pattern, not from a path.

Source code in src/pylpg/backend/base.py 
38
39
40
41
42
43
44
45
@abc.abstractmethod
def deserialize_relationship(self, record: typing.Any) -> dict[str, typing.Any]:
    """Return a relationship record as a dict of its properties.

    The dict also carries `_database_id`, `_start_id` and `_end_id`.
    The record must come from a matched pattern, not from a path.
    """
    ...

result_set_limit 

result_set_limit() -> int | None

Maximum number of rows a single query may return.

Returns None when the backend imposes no limit. Backends that silently truncate oversized result sets (FalkorDB caps at RESULTSET_SIZE, 10000 by default) must report their limit here so traverse_batch can split batches instead of losing rows.

Source code in src/pylpg/backend/base.py 
85
86
87
88
89
90
91
92
93
def result_set_limit(self) -> int | None:
    """Maximum number of rows a single query may return.

    Returns None when the backend imposes no limit. Backends that
    silently truncate oversized result sets (FalkorDB caps at
    `RESULTSET_SIZE`, 10000 by default) must report their limit here
    so `traverse_batch` can split batches instead of losing rows.
    """
    return None

traverse_batch 

traverse_batch(source_ids: list[Any], relationship_type: str, direction: Direction) -> list[dict[str, Any]]

Traverse from many source nodes at once.

Splits the batch and retries whenever a result set comes back at the backend's row limit, since such a result set may have been silently truncated.

Source code in src/pylpg/backend/base.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def traverse_batch(
    self,
    source_ids: list[typing.Any],
    relationship_type: str,
    direction: "pylpg.relationship.Direction",
) -> list[dict[str, typing.Any]]:
    """Traverse from many source nodes at once.

    Splits the batch and retries whenever a result set comes back at
    the backend's row limit, since such a result set may have been
    silently truncated.
    """
    limit = self.result_set_limit()
    rows: list[dict[str, typing.Any]] = []
    pending = [list(source_ids)]
    while pending:
        chunk = pending.pop()
        if not chunk:
            continue
        chunk_rows = self._traverse_batch_chunk(
            source_ids=chunk,
            relationship_type=relationship_type,
            direction=direction,
        )
        if limit is not None and len(chunk_rows) >= limit:
            if len(chunk) == 1:
                raise ValueError(
                    f"Node {chunk[0]} has at least {limit} '{relationship_type}' "
                    f"relationships, which reaches this backend's result set "
                    f"limit of {limit} rows. The result would be silently "
                    f"truncated. Raise the backend's limit (for FalkorDB: "
                    f"GRAPH.CONFIG SET RESULTSET_SIZE) to traverse this node."
                )
            middle = len(chunk) // 2
            pending.append(chunk[:middle])
            pending.append(chunk[middle:])
            continue
        rows.extend(chunk_rows)
    return rows