pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/select.py

@@ -0,0 +1,793 @@
+"""Typed immutable SELECT query construction."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import TYPE_CHECKING, Generic, TypeVar, cast, overload
+
+from pyoq.errors import QueryStateError, QueryValidationError
+from pyoq.query.expressions import Condition, Expression, require_boolean
+from pyoq.query.nodes import (
+    BinaryNode,
+    BinaryOperator,
+    BoundValueNode,
+    ExistsNode,
+    ExpressionNode,
+    FieldNode,
+    ScalarFamily,
+    VariadicNode,
+    VariadicOperator,
+)
+from pyoq.query.projections import Projection, order_node, projection_node
+from pyoq.query.raw import NodeProvider
+from pyoq.query.select_nodes import (
+    JoinKind,
+    JoinNode,
+    LockNode,
+    LockStrength,
+    LockWait,
+    OrderNode,
+    ProjectionNode,
+    QueryNode,
+    SelectNode,
+    SetNode,
+    SetOperator,
+    SourceNode,
+)
+from pyoq.query.sources import (
+    ColumnedTable,
+    CommonTable,
+    SourceBase,
+    Subquery,
+    TableLike,
+    common_table,
+    resolve_source,
+    subquery_source,
+    table_source,
+    write_target,
+)
+from pyoq.query.windows import WindowSpecification
+
+if TYPE_CHECKING:
+    from pyoq.descriptors import RelationshipDescriptor
+    from pyoq.query.writes import ColumnReference
+
+
+ResultRow = TypeVar("ResultRow")
+Value1 = TypeVar("Value1")
+Value2 = TypeVar("Value2")
+Value3 = TypeVar("Value3")
+Value4 = TypeVar("Value4")
+Value5 = TypeVar("Value5")
+Value6 = TypeVar("Value6")
+Value7 = TypeVar("Value7")
+Value8 = TypeVar("Value8")
+
+
+class Query(Generic[ResultRow]):
+    __slots__ = ("_node",)
+    _node: QueryNode
+
+    def __init__(self, node: QueryNode) -> None:
+        object.__setattr__(self, "_node", node)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "queries are immutable"
+        raise AttributeError(message)
+
+    @property
+    def node(self) -> QueryNode:
+        return self._node
+
+    def as_subquery(self, alias: str, /) -> Subquery[ResultRow]:
+        return cast(Subquery[ResultRow], subquery_source(self.node, alias))
+
+    def as_lateral(self, alias: str, /) -> Subquery[ResultRow]:
+        """A subquery that may read the rows to its left, row by row.
+
+        Not every dialect has one, so a dialect without it refuses the query
+        rather than evaluating the subquery once and quietly meaning
+        something else.
+        """
+        return cast(
+            Subquery[ResultRow],
+            subquery_source(self.node, alias, lateral=True),
+        )
+
+    def as_common_table(
+        self,
+        name: str,
+        /,
+        *,
+        columns: tuple[str, ...] = (),
+        recursive: bool = False,
+    ) -> CommonTable[ResultRow]:
+        if columns and len(columns) != _projection_count(self.node):
+            message = "common table column count must match its projection count"
+            raise QueryValidationError(message)
+        return cast(
+            CommonTable[ResultRow],
+            common_table(
+                name,
+                self.node,
+                columns=columns,
+                recursive=recursive,
+            ),
+        )
+
+    def order_by(self, *terms: object) -> Query[ResultRow]:
+        if not terms:
+            message = "ORDER BY requires at least one term"
+            raise QueryValidationError(message)
+        nodes = tuple(order_node(term) for term in terms)
+        return self._replace_order(nodes)
+
+    def limit(self, value: int, /) -> Query[ResultRow]:
+        return self._replace_limit(_page_value(value, "limit"))
+
+    def offset(self, value: int, /) -> Query[ResultRow]:
+        return self._replace_offset(_page_value(value, "offset"))
+
+    def union(self, other: Query[ResultRow], /) -> SetQuery[ResultRow]:
+        return self._set(SetOperator.UNION, other)
+
+    def union_all(self, other: Query[ResultRow], /) -> SetQuery[ResultRow]:
+        return self._set(SetOperator.UNION_ALL, other)
+
+    def intersect(self, other: Query[ResultRow], /) -> SetQuery[ResultRow]:
+        return self._set(SetOperator.INTERSECT, other)
+
+    def except_(self, other: Query[ResultRow], /) -> SetQuery[ResultRow]:
+        return self._set(SetOperator.EXCEPT, other)
+
+    def _set(
+        self,
+        operator: SetOperator,
+        other: Query[ResultRow],
+    ) -> SetQuery[ResultRow]:
+        if _projection_count(self.node) != _projection_count(other.node):
+            message = "set operation projection counts must match"
+            raise QueryValidationError(message)
+        return SetQuery(SetNode(self.node, operator, other.node))
+
+    def _replace_order(self, terms: tuple[OrderNode, ...]) -> Query[ResultRow]:
+        if isinstance(self.node, SelectNode):
+            return SelectQuery[ResultRow](replace(self.node, orders=terms))
+        return SetQuery[ResultRow](replace(self.node, orders=terms))
+
+    def _replace_limit(self, value: int) -> Query[ResultRow]:
+        if isinstance(self.node, SelectNode):
+            return SelectQuery[ResultRow](replace(self.node, limit=value))
+        return SetQuery[ResultRow](replace(self.node, limit=value))
+
+    def _replace_offset(self, value: int) -> Query[ResultRow]:
+        if isinstance(self.node, SelectNode):
+            return SelectQuery[ResultRow](replace(self.node, offset=value))
+        return SetQuery[ResultRow](replace(self.node, offset=value))
+
+
+class SelectQuery(Query[ResultRow], Generic[ResultRow]):
+    __slots__ = ()
+
+    @property
+    def select_node(self) -> SelectNode:
+        node = self.node
+        if not isinstance(node, SelectNode):
+            message = "SELECT query contains an invalid node"
+            raise QueryStateError(message)
+        return node
+
+    def for_update(self) -> SelectQuery[ResultRow]:
+        """Hold the rows this reads, so nobody else changes them first."""
+        return self._locked(LockStrength.UPDATE)
+
+    def for_no_key_update(self) -> SelectQuery[ResultRow]:
+        """Hold the rows, but let their keys still be referenced."""
+        return self._locked(LockStrength.NO_KEY_UPDATE)
+
+    def for_share(self) -> SelectQuery[ResultRow]:
+        """Hold the rows against change, while letting others read them too."""
+        return self._locked(LockStrength.SHARE)
+
+    def for_key_share(self) -> SelectQuery[ResultRow]:
+        """Hold only the keys, against a change that would break a reference."""
+        return self._locked(LockStrength.KEY_SHARE)
+
+    def nowait(self) -> SelectQuery[ResultRow]:
+        """Fail rather than wait for a row somebody else already holds."""
+        return self._waiting(LockWait.NOWAIT)
+
+    def skip_locked(self) -> SelectQuery[ResultRow]:
+        """Pass over a row somebody else already holds, rather than wait."""
+        return self._waiting(LockWait.SKIP_LOCKED)
+
+    def of(self, *targets: TableLike | NodeProvider) -> SelectQuery[ResultRow]:
+        """Hold rows of these tables only, and not everything read.
+
+        A column names the table that holds it, because a lock is taken on
+        rows and a caller who knows the column should not have to say the
+        table again.
+        """
+        if not targets:
+            message = "a lock names at least one table or none at all"
+            raise QueryValidationError(message)
+        named = tuple(_locked_table(target) for target in targets)
+        return SelectQuery(
+            replace(self.select_node, lock=replace(self._lock, tables=named))
+        )
+
+    def _locked(self, strength: LockStrength) -> SelectQuery[ResultRow]:
+        node = self.select_node
+        current = node.lock
+        wait = LockWait.WAIT if current is None else current.wait
+        tables = () if current is None else current.tables
+        return SelectQuery(replace(node, lock=LockNode(strength, wait, tables)))
+
+    def _waiting(self, wait: LockWait) -> SelectQuery[ResultRow]:
+        return SelectQuery(
+            replace(self.select_node, lock=replace(self._lock, wait=wait))
+        )
+
+    @property
+    def _lock(self) -> LockNode:
+        lock = self.select_node.lock
+        if lock is None:
+            message = "how a lock waits is said after what it locks"
+            raise QueryStateError(message)
+        return lock
+
+    def distinct(self, enabled: bool = True, /) -> SelectQuery[ResultRow]:
+        return SelectQuery(
+            replace(self.select_node, distinct=_boolean_setting(enabled, "distinct"))
+        )
+
+    def from_(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        if self.select_node.source is not None:
+            message = "SELECT source is already defined"
+            raise QueryStateError(message)
+        return SelectQuery(replace(self.select_node, source=resolve_source(source)))
+
+    def join(self, source: SourceBase | TableLike, /) -> JoinStep[ResultRow]:
+        """An inner join, qualified by the clause that follows it."""
+        return self._joining(JoinKind.INNER, source)
+
+    def inner_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> JoinStep[ResultRow]:
+        return self._joining(JoinKind.INNER, source)
+
+    def left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> JoinStep[ResultRow]:
+        return self._joining(JoinKind.LEFT, source)
+
+    def right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> JoinStep[ResultRow]:
+        return self._joining(JoinKind.RIGHT, source)
+
+    def full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> JoinStep[ResultRow]:
+        return self._joining(JoinKind.FULL, source)
+
+    def semi_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SemiJoinStep[ResultRow]:
+        """Rows that have a match, without bringing the match back.
+
+        No database writes it as a join, so neither does the SQL: it becomes
+        `EXISTS`, which is what a semi join means and what every dialect here
+        already understands.
+        """
+        return SemiJoinStep(self, resolve_source(source), negated=False)
+
+    def anti_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SemiJoinStep[ResultRow]:
+        """Rows that have no match, which is `NOT EXISTS`."""
+        return SemiJoinStep(self, resolve_source(source), negated=True)
+
+    def cross_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        """Every row against every row, which nothing qualifies."""
+        return self._joined(JoinNode(JoinKind.CROSS, self._source(source)))
+
+    def natural_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        """Joined on every column the two share, whatever those turn out to be."""
+        return self._natural(JoinKind.INNER, source)
+
+    def natural_left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        return self._natural(JoinKind.LEFT, source)
+
+    def natural_right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        return self._natural(JoinKind.RIGHT, source)
+
+    def natural_full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> SelectQuery[ResultRow]:
+        return self._natural(JoinKind.FULL, source)
+
+    def _joining(
+        self,
+        kind: JoinKind,
+        source: SourceBase | TableLike,
+    ) -> JoinStep[ResultRow]:
+        return JoinStep(self._joined, kind, self._source(source))
+
+    def _natural(
+        self,
+        kind: JoinKind,
+        source: SourceBase | TableLike,
+    ) -> SelectQuery[ResultRow]:
+        return self._joined(JoinNode(kind, self._source(source), natural=True))
+
+    def _source(self, source: SourceBase | TableLike) -> SourceNode:
+        _require_from(self.select_node)
+        return resolve_source(source)
+
+    def _joined(self, join: JoinNode) -> SelectQuery[ResultRow]:
+        return SelectQuery(
+            replace(self.select_node, joins=(*self.select_node.joins, join))
+        )
+
+    def where(self, condition: Expression[bool], /) -> SelectQuery[ResultRow]:
+        require_boolean(condition, "WHERE")
+        if self.select_node.condition is not None:
+            message = "WHERE condition is already defined"
+            raise QueryStateError(message)
+        return SelectQuery(replace(self.select_node, condition=condition.node))
+
+    def group_by(self, *expressions: object) -> SelectQuery[ResultRow]:
+        if not expressions:
+            message = "GROUP BY requires at least one expression"
+            raise QueryValidationError(message)
+        nodes = tuple(_expression_node(value, "GROUP BY") for value in expressions)
+        return SelectQuery(replace(self.select_node, groups=nodes))
+
+    def having(self, condition: Expression[bool], /) -> SelectQuery[ResultRow]:
+        require_boolean(condition, "HAVING")
+        if self.select_node.having is not None:
+            message = "HAVING condition is already defined"
+            raise QueryStateError(message)
+        return SelectQuery(replace(self.select_node, having=condition.node))
+
+    def window(
+        self,
+        *specifications: WindowSpecification,
+    ) -> SelectQuery[ResultRow]:
+        """Declare the windows this query's functions look through by name."""
+        if not specifications:
+            message = "WINDOW requires at least one named window"
+            raise QueryValidationError(message)
+        additions = tuple(item.declaration for item in specifications)
+        existing = {item.name for item in self.select_node.windows}
+        names = [item.name for item in additions]
+        if existing.intersection(names) or len(names) != len(set(names)):
+            message = "window names must be unique within a query"
+            raise QueryValidationError(message)
+        return SelectQuery(
+            replace(self.select_node, windows=self.select_node.windows + additions)
+        )
+
+    def with_(
+        self,
+        *common_tables: CommonTable[object],
+    ) -> SelectQuery[ResultRow]:
+        if not common_tables:
+            message = "WITH requires at least one common table"
+            raise QueryValidationError(message)
+        existing = {item.name for item in self.select_node.common_tables}
+        additions = tuple(item.definition for item in common_tables)
+        names = [item.name for item in additions]
+        if existing.intersection(names) or len(names) != len(set(names)):
+            message = "common table names must be unique within a query"
+            raise QueryValidationError(message)
+        return SelectQuery(
+            replace(
+                self.select_node,
+                common_tables=(*self.select_node.common_tables, *additions),
+            )
+        )
+
+    def order_by(self, *terms: object) -> SelectQuery[ResultRow]:
+        return _as_select(super().order_by(*terms))
+
+    def limit(self, value: int, /) -> SelectQuery[ResultRow]:
+        return _as_select(super().limit(value))
+
+    def offset(self, value: int, /) -> SelectQuery[ResultRow]:
+        return _as_select(super().offset(value))
+
+
+class SetQuery(Query[ResultRow], Generic[ResultRow]):
+    __slots__ = ()
+
+    def order_by(self, *terms: object) -> SetQuery[ResultRow]:
+        return _as_set(super().order_by(*terms))
+
+    def limit(self, value: int, /) -> SetQuery[ResultRow]:
+        return _as_set(super().limit(value))
+
+    def offset(self, value: int, /) -> SetQuery[ResultRow]:
+        return _as_set(super().offset(value))
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    /,
+) -> SelectQuery[tuple[Value1]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    /,
+) -> SelectQuery[tuple[Value1, Value2]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    /,
+) -> SelectQuery[tuple[Value1, Value2, Value3]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    value4: Expression[Value4] | Projection[Value4],
+    /,
+) -> SelectQuery[tuple[Value1, Value2, Value3, Value4]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    value4: Expression[Value4] | Projection[Value4],
+    value5: Expression[Value5] | Projection[Value5],
+    /,
+) -> SelectQuery[tuple[Value1, Value2, Value3, Value4, Value5]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    value4: Expression[Value4] | Projection[Value4],
+    value5: Expression[Value5] | Projection[Value5],
+    value6: Expression[Value6] | Projection[Value6],
+    /,
+) -> SelectQuery[tuple[Value1, Value2, Value3, Value4, Value5, Value6]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    value4: Expression[Value4] | Projection[Value4],
+    value5: Expression[Value5] | Projection[Value5],
+    value6: Expression[Value6] | Projection[Value6],
+    value7: Expression[Value7] | Projection[Value7],
+    /,
+) -> SelectQuery[tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7]]: ...
+
+
+@overload
+def select(
+    value1: Expression[Value1] | Projection[Value1],
+    value2: Expression[Value2] | Projection[Value2],
+    value3: Expression[Value3] | Projection[Value3],
+    value4: Expression[Value4] | Projection[Value4],
+    value5: Expression[Value5] | Projection[Value5],
+    value6: Expression[Value6] | Projection[Value6],
+    value7: Expression[Value7] | Projection[Value7],
+    value8: Expression[Value8] | Projection[Value8],
+    /,
+) -> SelectQuery[
+    tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+]: ...
+
+
+@overload
+def select(
+    value1: object,
+    value2: object,
+    value3: object,
+    value4: object,
+    value5: object,
+    value6: object,
+    value7: object,
+    value8: object,
+    /,
+    *values: object,
+) -> SelectQuery[tuple[object, ...]]:
+    """Wider than the overloads above name, where the element types stop.
+
+    A query is still a query past eight projections, and matching no overload
+    would take the whole chain down with it rather than just the tuple. Past
+    here a projection is checked when it is turned into one, and the row is
+    `object` per column, which is what is still known about it.
+    """
+
+
+def select(  # type: ignore[misc]
+    *values: object,
+) -> SelectQuery[object]:
+    if not values:
+        message = "SELECT requires at least one projection"
+        raise QueryValidationError(message)
+    return SelectQuery(SelectNode(tuple(projection_node(value) for value in values)))
+
+
+def select_from(table: ColumnedTable, /) -> SelectQuery[tuple[object, ...]]:
+    """Every column the table declares, in the order it declares them.
+
+    The column list is written out rather than left as a star, because a star
+    changes meaning the moment a column is added and the caller reading the
+    row would not know it had. Values arrive as a tuple in that order, which
+    is the order the generated row type takes its arguments in.
+    """
+    columns = table.COLUMNS
+    if not columns:
+        message = (
+            "table names no columns to select; generated tables declare them, "
+            "and any other table has to be selected from by naming its columns"
+        )
+        raise QueryValidationError(message)
+    projections = tuple(projection_node(column) for column in columns)
+    node = SelectNode(projections, every_column=True)
+    query: SelectQuery[tuple[object, ...]] = SelectQuery(node)
+    return query.from_(table_source(table))
+
+
+class SemiJoinStep(Generic[ResultRow]):
+    """A semi or anti join waiting for the predicate that matches the rows."""
+
+    __slots__ = ("_negated", "_query", "_source")
+    _query: SelectQuery[ResultRow]
+    _source: SourceNode
+    _negated: bool
+
+    def __init__(
+        self,
+        query: SelectQuery[ResultRow],
+        source: SourceNode,
+        *,
+        negated: bool,
+    ) -> None:
+        object.__setattr__(self, "_query", query)
+        object.__setattr__(self, "_source", source)
+        object.__setattr__(self, "_negated", negated)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "join steps are immutable"
+        raise AttributeError(message, name, value)
+
+    def on(self, condition: Expression[bool], /) -> SelectQuery[ResultRow]:
+        require_boolean(condition, "JOIN")
+        inner = SelectNode(
+            (ProjectionNode(BoundValueNode(1, ScalarFamily.NUMERIC)),),
+            source=self._source,
+            condition=condition.node,
+        )
+        matched = ExistsNode(inner, negated=self._negated)
+        node = self._query.select_node
+        return SelectQuery(replace(node, matches=(*node.matches, matched)))
+
+
+class JoinStep(Generic[ResultRow]):
+    """A join waiting to be told how the two tables line up.
+
+    SQL names the table first and qualifies it after, and so does this. The
+    step cannot be run or read: until it is qualified there is no query.
+    """
+
+    __slots__ = ("_join", "_kind", "_source")
+    _join: Callable[[JoinNode], SelectQuery[ResultRow]]
+    _kind: JoinKind
+    _source: SourceNode
+
+    def __init__(
+        self,
+        join: Callable[[JoinNode], SelectQuery[ResultRow]],
+        kind: JoinKind,
+        source: SourceNode,
+    ) -> None:
+        object.__setattr__(self, "_join", join)
+        object.__setattr__(self, "_kind", kind)
+        object.__setattr__(self, "_source", source)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "join steps are immutable"
+        raise AttributeError(message, name, value)
+
+    def on(self, condition: Expression[bool], /) -> SelectQuery[ResultRow]:
+        """The predicate the rows are matched by."""
+        require_boolean(condition, "JOIN")
+        return self._join(JoinNode(self._kind, self._source, condition.node))
+
+    def using(self, *columns: str | ColumnReference) -> SelectQuery[ResultRow]:
+        """Matched on columns both tables name the same way."""
+        names = tuple(_using_name(column) for column in columns)
+        if not names:
+            message = "USING requires at least one column"
+            raise QueryValidationError(message)
+        return self._join(JoinNode(self._kind, self._source, using=names))
+
+    def on_key(
+        self, relation: RelationshipDescriptor[object, object], /
+    ) -> SelectQuery[ResultRow]:
+        """Matched on the foreign key the schema already declares.
+
+        Generation writes a descriptor for every key in both directions, so
+        the columns are a fact rather than something to restate here and get
+        wrong.
+        """
+        return self._join(JoinNode(self._kind, self._source, _key_condition(relation)))
+
+
+def _using_name(column: object) -> str:
+    """The column's name in the database, which is what USING matches on.
+
+    A generated column and a hand written field both carry one, and both say
+    it the same way once the expression is a node.
+    """
+    if isinstance(column, str):
+        return column
+    node = getattr(column, "node", None)
+    if isinstance(node, FieldNode):
+        return node.name
+    message = "USING takes columns or their names"
+    raise QueryValidationError(message)
+
+
+def _key_condition(
+    relation: RelationshipDescriptor[object, object],
+) -> ExpressionNode:
+    """One equality per key column, and the same shape for a composite key.
+
+    A descriptor validates that its two sides line up when it is built, so
+    the pairs here are known to match.
+    """
+    equalities = [
+        BinaryNode(
+            BinaryOperator.EQUAL,
+            FieldNode(source, relation.source_table),
+            FieldNode(target, relation.target_table),
+        )
+        for source, target in zip(
+            relation.source_columns, relation.target_columns, strict=True
+        )
+    ]
+    if len(equalities) == 1:
+        return equalities[0]
+    return VariadicNode(VariadicOperator.AND, tuple(equalities))
+
+
+def exists(query: Query[ResultRow], /) -> Condition:
+    """Whether the query returns any row at all.
+
+    What is projected inside does not matter, so nothing is read out of it.
+    Databases understand that, and so do readers.
+    """
+    return Condition(ExistsNode(query.node))
+
+
+def not_exists(query: Query[ResultRow], /) -> Condition:
+    """Whether the query returns nothing at all."""
+    return Condition(ExistsNode(query.node, negated=True))
+
+
+def _expression_node(value: object, clause: str) -> ExpressionNode:
+    if isinstance(value, Expression):
+        return value.node
+    message = f"{clause} requires typed expressions"
+    raise TypeError(message)
+
+
+def _require_from(node: SelectNode) -> None:
+    if node.source is None:
+        message = "JOIN requires a FROM source"
+        raise QueryStateError(message)
+
+
+def _page_value(value: object, label: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        message = f"{label} must be a non-negative integer"
+        raise QueryValidationError(message)
+    return value
+
+
+def _locked_table(target: TableLike | NodeProvider) -> str:
+    if isinstance(target, TableLike):
+        return write_target(target).name
+    node = target.node
+    if not isinstance(node, FieldNode) or node.table is None:
+        message = "a lock names a table, or a column that names one"
+        raise QueryValidationError(message)
+    return node.table
+
+
+def _boolean_setting(value: object, label: str) -> bool:
+    if not isinstance(value, bool):
+        message = f"{label} setting must be boolean"
+        raise QueryValidationError(message)
+    return value
+
+
+def _projection_count(node: QueryNode) -> int:
+    if isinstance(node, SelectNode):
+        return len(node.projections)
+    return _projection_count(node.left)
+
+
+def _as_select(query: Query[ResultRow]) -> SelectQuery[ResultRow]:
+    if isinstance(query, SelectQuery):
+        return query
+    message = "query operation did not preserve SELECT state"
+    raise QueryStateError(message)
+
+
+def _as_set(query: Query[ResultRow]) -> SetQuery[ResultRow]:
+    if isinstance(query, SetQuery):
+        return query
+    message = "query operation did not preserve set state"
+    raise QueryStateError(message)
+
+
+__all__ = (
+    "JoinStep",
+    "Query",
+    "SelectQuery",
+    "SemiJoinStep",
+    "SetQuery",
+    "exists",
+    "not_exists",
+    "select",
+    "select_from",
+)