pyoq-sql 1.0.2__py3-none-any.whl

pyoq/fetching/nesting.py

@@ -0,0 +1,183 @@
+"""Building the collection one resolved fetch asks for.
+
+A resolved plan says which relation is fetched, how, in what order, how many
+rows of it to keep, and what each of those rows carries. This turns one of
+those into the node a compiler renders, which is the only place that knows
+both what a relation is and what a collection looks like.
+
+Nothing here reaches a database. It builds a node, the way every other builder
+in this toolkit does.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyoq.errors import FetchPlanError
+from pyoq.fetching.tables import TableBinding, TableNames
+from pyoq.query.fields import family_for_type
+from pyoq.query.nodes import (
+    BinaryNode,
+    BinaryOperator,
+    CollectionEntry,
+    CollectionJoinNode,
+    CollectionNode,
+    CollectionOrderNode,
+    VariadicNode,
+    VariadicOperator,
+)
+
+if TYPE_CHECKING:
+    from pyoq.query.nodes import ExpressionNode, FieldNode
+    from pyoq.relations.fetching import FetchJoin
+    from pyoq.relations.model import TypedRelation
+    from pyoq.relations.planning import ResolvedFetch
+    from pyoq.schema.models import Identifier
+
+
+def collection_for(
+    fetch: ResolvedFetch,
+    carrying: tuple[Identifier, ...],
+    /,
+    *,
+    parent: TableBinding | None = None,
+    names: TableNames | None = None,
+) -> CollectionNode:
+    """The collection a resolved fetch describes, as a node a dialect renders.
+
+    ``carrying`` names the columns of the related table each row holds. They
+    are given rather than derived because a caller asks for the columns it
+    wants, and a collection that carried every column would read more than was
+    asked for.
+
+    ``parent`` is the appearance the collection correlates to, and ``names``
+    hands out the appearances it reads itself. A collection may read the table
+    its parent is reading, so both sides need names of their own or the
+    correlation compares a table with itself and gathers nothing.
+    """
+    if not carrying:
+        message = (
+            "a collection carries at least one column of "
+            f"{fetch.relation.target.table.name.value!r}"
+        )
+        raise FetchPlanError(message)
+    source = parent or TableBinding(fetch.relation.source.table)
+    naming = names or TableNames(_named_by(fetch, source))
+    related = naming.next(fetch.relation.target.table)
+    entries = tuple(
+        CollectionEntry(name.value, _field(related, name)) for name in carrying
+    )
+    bound = tuple(
+        (join, naming.next(join.relation.target.table)) for join in fetch.joins
+    )
+    joined = tuple(_join(join, binding, related) for join, binding in bound)
+    carried = tuple(
+        CollectionEntry(_joined_key(binding, name), _field(binding, name))
+        for join, binding in bound
+        for name in join.carrying
+    )
+    return CollectionNode(
+        table=related.table.name.value,
+        entries=entries + carried,
+        condition=_correlation(fetch.relation, source, related),
+        orders=tuple(
+            CollectionOrderNode(_field(related, column), descending=descending)
+            for column, descending in _ordered(fetch)
+        ),
+        schema=_named(related.table.schema),
+        catalog=_named(related.table.catalog),
+        alias=related.alias,
+        joins=joined,
+        limit=fetch.limit,
+    )
+
+
+def _ordered(fetch: ResolvedFetch) -> tuple[tuple[Identifier, bool], ...]:
+    """The order terms, each of which has to name a column to be built.
+
+    A term ordered by an expression carries the name a plan reports it under
+    and not the expression itself, so nothing here can write one out. That is
+    a plan a caller resolves themselves rather than one this builds wrongly.
+    """
+    written: list[tuple[Identifier, bool]] = []
+    for term in fetch.order_by:
+        if term.column is None:
+            message = (
+                f"the collection of {fetch.relation.target.table.name.value!r} "
+                f"is ordered by {term.name!r}, which is an expression rather "
+                "than a column, so this cannot build it"
+            )
+            raise FetchPlanError(message)
+        written.append((term.column, term.descending))
+    return tuple(written)
+
+
+def _named_by(fetch: ResolvedFetch, source: TableBinding) -> frozenset[str]:
+    """What the tables of this collection are already called.
+
+    A caller who builds a collection on its own hands over no schema, so what
+    can be reserved is what the fetch itself names: the table it correlates
+    to, the table it reads, and the tables it reads alongside. A caller with a
+    schema passes the naming in, and that one reserves all of it.
+    """
+    return frozenset(
+        {source.qualifier, fetch.relation.target.table.name.value}
+        | {join.relation.target.table.name.value for join in fetch.joins}
+    )
+
+
+def _joined_key(binding: TableBinding, column: Identifier) -> str:
+    """What a joined column is called in a row of the collection.
+
+    Qualified by the appearance it came from rather than by its table, because
+    a collection may join one table twice and a row cannot carry one key
+    twice. This is how the collection encodes its row, not a name a caller
+    reads: what a caller reads is the row the executor hands back.
+    """
+    return f"{binding.qualifier}.{column.value}"
+
+
+def _join(
+    join: FetchJoin,
+    binding: TableBinding,
+    parent: TableBinding,
+) -> CollectionJoinNode:
+    return CollectionJoinNode(
+        table=binding.table.name.value,
+        condition=_correlation(join.relation, parent, binding),
+        schema=_named(binding.table.schema),
+        catalog=_named(binding.table.catalog),
+        alias=binding.alias,
+    )
+
+
+def _correlation(
+    relation: TypedRelation,
+    source: TableBinding,
+    target: TableBinding,
+) -> ExpressionNode:
+    """What ties one appearance of a relation to the other, column by column."""
+    matched = tuple(
+        BinaryNode(
+            BinaryOperator.EQUAL,
+            _field(target, target_column),
+            _field(source, source_column),
+        )
+        for source_column, target_column in zip(
+            relation.source.columns, relation.target.columns, strict=True
+        )
+    )
+    if len(matched) == 1:
+        return matched[0]
+    return VariadicNode(VariadicOperator.AND, matched)
+
+
+def _field(binding: TableBinding, column: Identifier) -> FieldNode:
+    return binding.field(column, family_for_type(object))
+
+
+def _named(value: Identifier | None) -> str | None:
+    return None if value is None else value.value
+
+
+__all__ = ("collection_for",)