pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/rendering/expressions.py

@@ -0,0 +1,913 @@
+"""Shared scalar expression rendering with dialect hooks."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Generic, TypeAlias, TypeVar
+
+from pyoq.config import DatabaseDialect
+from pyoq.errors import CompilationError, UnsupportedQueryError
+from pyoq.query.casts import kind_for_target
+from pyoq.query.execution import CompilationContext
+from pyoq.query.nodes import (
+    AggregateName,
+    AggregateNode,
+    ArrayConstructNode,
+    ArrayDimensionsNode,
+    ArrayElementNode,
+    ArrayLengthNode,
+    ArrayNode,
+    BinaryNode,
+    BinaryOperator,
+    BoundValueNode,
+    CaseNode,
+    CastNode,
+    CollectionJoinNode,
+    CollectionNode,
+    ExistsNode,
+    ExpressionNode,
+    ExtractNode,
+    FieldNode,
+    FrameBound,
+    FrameBoundNode,
+    FrameExclusion,
+    FrameKind,
+    FrameNode,
+    FunctionName,
+    FunctionNode,
+    JsonBuild,
+    JsonBuildNode,
+    JsonContainsNode,
+    JsonKeysNode,
+    JsonNode,
+    JsonWriteNode,
+    RawNode,
+    RowValueNode,
+    ScalarFamily,
+    UnaryNode,
+    UnaryOperator,
+    VariadicNode,
+    VariadicOperator,
+    VendorFunctionNode,
+    WindowFunctionNode,
+    WindowNode,
+    WindowReferenceNode,
+    WindowSpecificationNode,
+)
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.sources import OrderTextRenderer, QueryTextRenderer
+from pyoq.query.select_nodes import JsonElementsSourceNode, OrderNode
+from pyoq.query.vendor import PLAIN_NAME
+from pyoq.schema.models import TypeKind
+
+ContextType = TypeVar("ContextType", bound=CompilationContext)
+
+_UNSAFE_RAW_TEXT = re.compile(r"\?|;|--|/\*|\*/|(?<![A-Za-z0-9_])[:@$][A-Za-z_]")
+
+_UNARY_SUFFIX = {
+    UnaryOperator.IS_NULL: "IS NULL",
+    UnaryOperator.IS_NOT_NULL: "IS NOT NULL",
+    UnaryOperator.IS_TRUE: "IS TRUE",
+    UnaryOperator.IS_FALSE: "IS FALSE",
+}
+
+_STANDARD_BINARY_SQL = {
+    BinaryOperator.EQUAL: "=",
+    BinaryOperator.NOT_EQUAL: "<>",
+    BinaryOperator.LESS_THAN: "<",
+    BinaryOperator.LESS_OR_EQUAL: "<=",
+    BinaryOperator.GREATER_THAN: ">",
+    BinaryOperator.GREATER_OR_EQUAL: ">=",
+    BinaryOperator.ADD: "+",
+    BinaryOperator.SUBTRACT: "-",
+    BinaryOperator.MULTIPLY: "*",
+    BinaryOperator.DIVIDE: "/",
+    BinaryOperator.MODULO: "%",
+    BinaryOperator.CONCAT: "||",
+    BinaryOperator.LIKE: "LIKE",
+    BinaryOperator.NOT_LIKE: "NOT LIKE",
+}
+
+_AGGREGATE_SQL = {
+    AggregateName.COUNT: "COUNT",
+    AggregateName.SUM: "SUM",
+    AggregateName.AVERAGE: "AVG",
+    AggregateName.MINIMUM: "MIN",
+    AggregateName.MAXIMUM: "MAX",
+}
+
+_FRAME_KINDS: Mapping[FrameKind, str] = {
+    FrameKind.ROWS: "ROWS",
+    FrameKind.RANGE: "RANGE",
+    FrameKind.GROUPS: "GROUPS",
+}
+
+_FRAME_BOUNDS: Mapping[FrameBound, str] = {
+    FrameBound.UNBOUNDED_PRECEDING: "UNBOUNDED PRECEDING",
+    FrameBound.PRECEDING: "PRECEDING",
+    FrameBound.CURRENT_ROW: "CURRENT ROW",
+    FrameBound.FOLLOWING: "FOLLOWING",
+    FrameBound.UNBOUNDED_FOLLOWING: "UNBOUNDED FOLLOWING",
+}
+
+_FRAME_EXCLUSIONS: Mapping[FrameExclusion, str] = {
+    FrameExclusion.CURRENT_ROW: "CURRENT ROW",
+    FrameExclusion.GROUP: "GROUP",
+    FrameExclusion.TIES: "TIES",
+    FrameExclusion.NO_OTHERS: "NO OTHERS",
+}
+
+_STANDARD_CAST_SQL: Mapping[TypeKind, str] = {
+    TypeKind.BOOLEAN: "BOOLEAN",
+    TypeKind.SMALL_INTEGER: "SMALLINT",
+    TypeKind.INTEGER: "INTEGER",
+    TypeKind.BIG_INTEGER: "BIGINT",
+    TypeKind.DECIMAL: "NUMERIC",
+    TypeKind.REAL: "REAL",
+    TypeKind.DOUBLE: "DOUBLE PRECISION",
+    TypeKind.STRING: "TEXT",
+    TypeKind.BINARY: "BYTEA",
+    TypeKind.DATE: "DATE",
+    TypeKind.TIME: "TIME",
+    TypeKind.DATETIME: "TIMESTAMP",
+    TypeKind.INTERVAL: "INTERVAL",
+    TypeKind.UUID: "UUID",
+    TypeKind.JSON: "JSONB",
+}
+"""Verified against a running PostgreSQL server, whose names these are."""
+
+_STANDARD_CHOOSING_SQL: Mapping[FunctionName, str] = {
+    FunctionName.COALESCE: "COALESCE",
+    FunctionName.NULLIF: "NULLIF",
+    FunctionName.GREATEST: "GREATEST",
+    FunctionName.LEAST: "LEAST",
+}
+
+_CHOOSING_FUNCTIONS = frozenset(
+    {
+        FunctionName.COALESCE,
+        FunctionName.NULLIF,
+        FunctionName.GREATEST,
+        FunctionName.LEAST,
+    }
+)
+"""Functions that take a list and answer with one of it."""
+
+_SCALAR_TRANSFORMS = frozenset(
+    {FunctionName.LOWER, FunctionName.UPPER, FunctionName.LENGTH}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionFunctions:
+    """How one dialect gathers rows into a single value, and builds one."""
+
+    array_function: str
+    object_function: str
+    empty_array: str
+    array_constructor: str
+    object_aggregate: str
+    ordered: bool = True
+
+
+_Call: TypeAlias = (
+    CaseNode
+    | CastNode
+    | WindowNode
+    | WindowFunctionNode
+    | ExistsNode
+    | VendorFunctionNode
+    | ArrayNode
+    | ArrayElementNode
+    | ArrayLengthNode
+    | ArrayConstructNode
+    | ArrayDimensionsNode
+    | JsonContainsNode
+    | JsonWriteNode
+    | JsonNode
+    | JsonBuildNode
+    | JsonKeysNode
+    | RowValueNode
+    | FunctionNode
+    | ExtractNode
+    | AggregateNode
+    | CollectionNode
+    | RawNode
+)
+"""Everything not a leaf and not an operator, which is everything named."""
+
+
+_KEPT = "pyoq_kept"
+"""What a limited collection calls the rows its order chose."""
+
+
+def _kept_entry(position: int) -> str:
+    """What one value a row carries is called inside that set."""
+    return f"pyoq_value_{position}"
+
+
+def _kept_order(position: int) -> str:
+    """What one of the keys it is ordered by is called inside that set."""
+    return f"pyoq_order_{position}"
+
+
+def _text_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+class ExpressionRenderer(ABC, Generic[ContextType]):
+    __slots__ = ("_context", "_declared_windows", "_render_order", "_render_query")
+    _context: ContextType
+    _declared_windows: frozenset[str]
+    _render_order: OrderTextRenderer | None
+    _render_query: QueryTextRenderer | None
+
+    def __init__(self, context: ContextType) -> None:
+        self._context = context
+        self._render_order = None
+        self._render_query = None
+        self._declared_windows = frozenset()
+
+    def declares_windows(self, names: frozenset[str], /) -> frozenset[str]:
+        """The windows named by the query being written, and the ones before it.
+
+        A subquery declares its own, so the caller puts back what it replaced
+        once that query has been written.
+        """
+        previous = self._declared_windows
+        self._declared_windows = names
+        return previous
+
+    def orders_rows_with(self, render_order: OrderTextRenderer, /) -> None:
+        """How to write one term of an ORDER BY, direction and nulls included.
+
+        A window orders rows the way a query does, and only one place knows
+        what a dialect accepts there, so it hands the answer back rather than
+        being reached for.
+        """
+        self._render_order = render_order
+
+    def reads_queries_with(self, render_query: QueryTextRenderer, /) -> None:
+        """How to write a query that appears inside an expression.
+
+        Only the query renderer knows how, and it is built from this one, so
+        it hands the answer back rather than being reached for.
+        """
+        self._render_query = render_query
+
+    @property
+    @abstractmethod
+    def dialect(self) -> str: ...
+
+    @abstractmethod
+    def qualified_field(self, node: FieldNode) -> str: ...
+
+    @abstractmethod
+    def render_extract(self, node: ExtractNode) -> str: ...
+
+    @abstractmethod
+    def render_string_predicate(self, node: FunctionNode) -> str: ...
+
+    @abstractmethod
+    def require_raw_expressions(self) -> None: ...
+
+    @property
+    @abstractmethod
+    def collection_functions(self) -> CollectionFunctions:
+        """How this dialect gathers rows into one value."""
+
+    def qualified_table(self, node: CollectionNode) -> str:
+        """Name the table a collection reads, and the name it answers to.
+
+        A collection may read the table its parent is already reading, which
+        is what a relation to its own table is, so the alias is what keeps the
+        correlation naming two different things.
+        """
+        written = self.quoting.qualified(
+            node.table, schema=node.schema, catalog=node.catalog
+        )
+        if node.alias is None:
+            return written
+        return f"{written} AS {self.quoting.quote(node.alias)}"
+
+    def qualified_join(self, join: CollectionJoinNode) -> str:
+        """Name a table a collection reads alongside its own.
+
+        Quoted the same way any other name is, and aliased where the join says
+        so, because a collection may read a table it has already read.
+        """
+        written = self.quoting.qualified(
+            join.table, schema=join.schema, catalog=join.catalog
+        )
+        if join.alias is None:
+            return written
+        return f"{written} AS {self.quoting.quote(join.alias)}"
+
+    @abstractmethod
+    def validate_binary(self, node: BinaryNode) -> None: ...
+
+    def binary_operator_sql(self, operator: BinaryOperator) -> str | None:
+        return _STANDARD_BINARY_SQL.get(operator)
+
+    @property
+    def cast_type_names(self) -> Mapping[TypeKind, str]:
+        """What this dialect calls each type a cast can ask for."""
+        return _STANDARD_CAST_SQL
+
+    def cast_type_sql(self, value_type: type[object]) -> str:
+        """How to name a cast target, or a refusal when there is no way to.
+
+        A dialect that has no such type must say so. Emitting a name it
+        merely tolerates would answer with a value of the wrong type and call
+        it the requested one.
+        """
+        kind = kind_for_target(value_type)
+        name = self.cast_type_names.get(kind)
+        if name is None:
+            message = (
+                f"{self.dialect} cannot cast to {kind.value}, "
+                f"because it has no such type"
+            )
+            raise UnsupportedQueryError(message)
+        return name
+
+    def require_window_functions(self) -> None:
+        """Whether this dialect can measure a row against its neighbours."""
+
+    def _compile_window_function(self, node: WindowFunctionNode) -> str:
+        arguments = ", ".join(self.compile(argument) for argument in node.arguments)
+        return f"{node.name.value.replace('-', '_').upper()}({arguments})"
+
+    def _compile_window(self, node: WindowNode) -> str:
+        self.require_window_functions()
+        looked_through = node.window
+        if isinstance(looked_through, WindowReferenceNode):
+            self._require_declared(looked_through.name)
+            return f"{self.compile(node.expression)} OVER {looked_through.name}"
+        specification = self.compile_window_specification(looked_through)
+        return f"{self.compile(node.expression)} OVER ({specification})"
+
+    def _require_declared(self, name: str) -> None:
+        if name not in self._declared_windows:
+            message = f"window {name} is read through but the query does not declare it"
+            raise CompilationError(message)
+
+    def compile_window_specification(self, node: WindowSpecificationNode) -> str:
+        """How a window divides and orders the rows it covers."""
+        clauses: list[str] = []
+        if node.partition_by:
+            partitions = ", ".join(
+                self.compile(expression) for expression in node.partition_by
+            )
+            clauses.append(f"PARTITION BY {partitions}")
+        if node.order_by:
+            clauses.append(f"ORDER BY {self._ordered_rows(node.order_by)}")
+        if node.frame is not None:
+            clauses.append(self._compile_frame(node.frame))
+        return " ".join(clauses)
+
+    def _compile_frame(self, node: FrameNode) -> str:
+        """The rows a window function reads, where this dialect can narrow them."""
+        self.require_frame(node)
+        start = self._frame_bound(node.start)
+        if node.end is None:
+            written = f"{_FRAME_KINDS[node.kind]} {start}"
+        else:
+            written = (
+                f"{_FRAME_KINDS[node.kind]} BETWEEN {start} "
+                f"AND {self._frame_bound(node.end)}"
+            )
+        if node.exclusion is None:
+            return written
+        return f"{written} EXCLUDE {_FRAME_EXCLUSIONS[node.exclusion]}"
+
+    def _frame_bound(self, node: FrameBoundNode) -> str:
+        written = _FRAME_BOUNDS[node.bound]
+        if node.offset is None:
+            return written
+        return f"{self.compile(node.offset)} {written}"
+
+    def require_frame(self, node: FrameNode) -> None:
+        """Whether this dialect can narrow a window the way it was asked to."""
+
+    def _ordered_rows(self, orders: tuple[OrderNode, ...]) -> str:
+        if self._render_order is None:
+            message = f"{self.dialect} cannot order the rows a window covers"
+            raise CompilationError(message)
+        render_order = self._render_order
+        return ", ".join(render_order(order) for order in orders)
+
+    def _compile_cast(self, node: CastNode) -> str:
+        target = self.cast_type_sql(node.value_type)
+        return f"CAST({self.compile(node.expression)} AS {target})"
+
+    def choosing_function_sql(self, name: FunctionName) -> str:
+        """What this dialect calls the function that picks one of its arguments."""
+        return _STANDARD_CHOOSING_SQL[name]
+
+    def compile(self, node: ExpressionNode) -> str:
+        """Whatever this node is, written the way this dialect writes it."""
+        if isinstance(node, (BoundValueNode, FieldNode)):
+            return self._compile_leaf(node)
+        if isinstance(node, (UnaryNode, BinaryNode, VariadicNode)):
+            return self._compile_operator(node)
+        return self._compile_call(node)
+
+    def _compile_leaf(self, node: BoundValueNode | FieldNode) -> str:
+        """A value or a column, which nothing inside has to be written first."""
+        if isinstance(node, BoundValueNode):
+            return self._context.bind(node)
+        return self.qualified_field(node)
+
+    def _compile_operator(
+        self,
+        node: UnaryNode | BinaryNode | VariadicNode,
+    ) -> str:
+        """The nodes written as operators between or before their operands."""
+        if isinstance(node, UnaryNode):
+            return self._compile_unary(node)
+        if isinstance(node, BinaryNode):
+            return self._compile_binary(node)
+        return self._compile_variadic(node)
+
+    def _compile_call(self, node: _Call) -> str:
+        """The nodes written as a name, a bracket, or a query of their own."""
+        if isinstance(node, CaseNode):
+            return self._compile_case(node)
+        if isinstance(node, CastNode):
+            return self._compile_cast(node)
+        if isinstance(node, (WindowNode, WindowFunctionNode)):
+            return self._compile_windowed(node)
+        if isinstance(node, ExistsNode):
+            return self._compile_exists(node)
+        if isinstance(node, RowValueNode):
+            return self._compile_row_value(node)
+        if isinstance(node, VendorFunctionNode):
+            return self._compile_vendor_function(node)
+        if isinstance(
+            node,
+            (
+                ArrayNode,
+                ArrayElementNode,
+                ArrayLengthNode,
+                ArrayConstructNode,
+                ArrayDimensionsNode,
+            ),
+        ):
+            return self._compile_array(node)
+        if isinstance(node, JsonBuildNode):
+            return self.render_json_build(node)
+        if isinstance(node, (JsonNode, JsonContainsNode, JsonWriteNode, JsonKeysNode)):
+            return self._compile_json(node)
+        if isinstance(node, FunctionNode):
+            return self._compile_function(node)
+        if isinstance(node, ExtractNode):
+            return self.render_extract(node)
+        if isinstance(node, AggregateNode):
+            return self._compile_aggregate(node)
+        if isinstance(node, CollectionNode):
+            return self._compile_collection(node)
+        return self._compile_raw(node)
+
+    @property
+    @abstractmethod
+    def quoting(self) -> IdentifierQuoting:
+        """How this dialect writes a name that has to be written out."""
+
+    @property
+    @abstractmethod
+    def database_dialect(self) -> DatabaseDialect:
+        """Which database this writes for, as the configuration names it."""
+
+    def routine_name(
+        self,
+        name: str,
+        schema: str | None = None,
+        catalog: str | None = None,
+    ) -> str:
+        """A routine's name as written, or quoted when it is not plain.
+
+        A name a database reads as written is left alone, so a call reads the
+        way it would be typed, and a built-in keeps the spelling the database
+        knows it by. Anything else is quoted, which is what makes a name with a
+        space usable and a name with a quote in it harmless.
+
+        Where the routine says which schema it is kept in, each part is quoted
+        as itself, because a schema may hold a dot and a flattened name cannot
+        say where one part ends.
+        """
+        if schema is None and catalog is None:
+            if PLAIN_NAME.match(name):
+                return name
+            return ".".join(self.quoting.quote(part) for part in name.split("."))
+        return self.quoting.qualified(name, schema=schema, catalog=catalog)
+
+    def _compile_vendor_function(self, node: VendorFunctionNode) -> str:
+        """A function this database has, refused where it has not got it.
+
+        A caller who said which databases a function exists on is told here
+        rather than by the server, because a query that cannot run is better
+        found while it is being written.
+        """
+        if node.dialects and self.database_dialect not in node.dialects:
+            named = ", ".join(sorted(node.dialects))
+            message = (
+                f"{node.name} was declared for {named}, and this is "
+                f"{self.database_dialect.value}"
+            )
+            raise UnsupportedQueryError(message)
+        arguments = ", ".join(self.compile(argument) for argument in node.arguments)
+        written = self.routine_name(node.name, node.schema, node.catalog)
+        return f"{written}({arguments})"
+
+    def _compile_json(
+        self,
+        node: JsonNode | JsonContainsNode | JsonWriteNode | JsonKeysNode,
+    ) -> str:
+        if isinstance(node, JsonNode):
+            return self.render_json(node)
+        if isinstance(node, JsonContainsNode):
+            return self.render_json_contains(node)
+        if isinstance(node, JsonKeysNode):
+            return self.render_json_keys(node)
+        return self.render_json_write(node)
+
+    def _compile_array(
+        self,
+        node: (
+            ArrayNode
+            | ArrayElementNode
+            | ArrayLengthNode
+            | ArrayConstructNode
+            | ArrayDimensionsNode
+        ),
+    ) -> str:
+        if isinstance(node, ArrayNode):
+            return self.render_array(node)
+        if isinstance(node, ArrayElementNode):
+            return self.render_array_element(node)
+        if isinstance(node, ArrayConstructNode):
+            return self.render_array_construct(node)
+        if isinstance(node, ArrayDimensionsNode):
+            return self.render_array_dimensions(node)
+        return self.render_array_length(node)
+
+    def render_array(self, node: ArrayNode) -> str:
+        """An array asked about, where this dialect has arrays."""
+        del node
+        raise UnsupportedQueryError(self._no_arrays())
+
+    def render_array_element(self, node: ArrayElementNode) -> str:
+        """One element of an array, where this dialect has arrays."""
+        del node
+        raise UnsupportedQueryError(self._no_arrays())
+
+    def render_array_length(self, node: ArrayLengthNode) -> str:
+        """How many elements an array holds, where this dialect has arrays."""
+        del node
+        raise UnsupportedQueryError(self._no_arrays())
+
+    def render_array_construct(self, node: ArrayConstructNode) -> str:
+        """An array built from values, where this dialect has arrays."""
+        del node
+        raise UnsupportedQueryError(self._no_arrays())
+
+    def render_array_dimensions(self, node: ArrayDimensionsNode) -> str:
+        """How many dimensions an array has, where this dialect has arrays."""
+        del node
+        raise UnsupportedQueryError(self._no_arrays())
+
+    def _no_arrays(self) -> str:
+        return (
+            f"{self.dialect} has no array type; hold a collection as JSON "
+            f"or in a table of its own"
+        )
+
+    @abstractmethod
+    def render_json_elements(self, node: JsonElementsSourceNode) -> str:
+        """A JSON array read as rows, which every dialect spells its own way."""
+
+    @abstractmethod
+    def render_json_keys(self, node: JsonKeysNode) -> str:
+        """The members an object has, as a JSON array of their names."""
+
+    @abstractmethod
+    def render_json(self, node: JsonNode) -> str:
+        """How this dialect reads inside a JSON value.
+
+        There is no shared spelling to fall back on: PostgreSQL takes a path
+        as a list of steps, while SQLite and MySQL take one written string,
+        and PostgreSQL reads that written string as a member name that is
+        simply not there. So every dialect answers this itself.
+        """
+
+    @abstractmethod
+    def render_json_write(self, node: JsonWriteNode) -> str:
+        """How this dialect writes a value into a JSON document."""
+
+    @abstractmethod
+    def render_json_contains(self, node: JsonContainsNode) -> str:
+        """Whether one JSON value holds another, where a dialect can ask."""
+
+    def json_path_text(self, path: tuple[str | int, ...]) -> str:
+        """A path as SQLite and MySQL write one, bound rather than written in."""
+        steps = "".join(
+            f"[{step}]" if isinstance(step, int) else f".{step}" for step in path
+        )
+        return self._context.bind(BoundValueNode(f"${steps}", ScalarFamily.STRING))
+
+    def _compile_row_value(self, node: RowValueNode) -> str:
+        values = ", ".join(self.compile(expression) for expression in node.expressions)
+        return f"({values})"
+
+    def _compile_windowed(self, node: WindowNode | WindowFunctionNode) -> str:
+        if isinstance(node, WindowNode):
+            return self._compile_window(node)
+        return self._compile_window_function(node)
+
+    def _compile_collection(self, node: CollectionNode) -> str:
+        """Render a correlated collection as one value beside its parent.
+
+        The empty case is coalesced rather than left null, because a relation
+        with no rows is an empty collection and a caller should not have to tell
+        the difference from a fetch that did not happen.
+        """
+        functions = self.collection_functions
+        self._require_collection_order(node, functions)
+        if node.limit is not None:
+            return self._compile_limited_collection(node, functions)
+        aggregate = (
+            f"{functions.array_function}"
+            f"({self._collection_row(node)}{self._collection_order(node)})"
+        )
+        return "".join(
+            (
+                "(SELECT COALESCE(",
+                aggregate,
+                ", ",
+                functions.empty_array,
+                ") FROM ",
+                self._collection_reading(node),
+                " WHERE ",
+                self.compile(node.condition),
+                ")",
+            )
+        )
+
+    def _compile_limited_collection(
+        self,
+        node: CollectionNode,
+        functions: CollectionFunctions,
+    ) -> str:
+        """A collection of only the rows its order put first.
+
+        The derived table answers with the values each row carries rather than
+        with the row already built, for two reasons. A join's columns are not
+        reachable through the one name a derived table answers under. And
+        SQLite loses the JSON subtype of a value that passes through one, so an
+        object built inside comes back quoted as text rather than as an object.
+        """
+        kept = self.quoting.quote(_KEPT)
+        carried = ", ".join(
+            (
+                *(
+                    f"{self.compile(entry.expression)} AS "
+                    f"{self.quoting.quote(_kept_entry(position))}"
+                    for position, entry in enumerate(node.entries)
+                ),
+                *(
+                    f"{self.compile(order.expression)} AS "
+                    f"{self.quoting.quote(_kept_order(position))}"
+                    for position, order in enumerate(node.orders)
+                ),
+            )
+        )
+        inner = "".join(
+            (
+                "SELECT ",
+                carried,
+                " FROM ",
+                self._collection_reading(node),
+                " WHERE ",
+                self.compile(node.condition),
+                self._collection_order(node),
+                f" LIMIT {node.limit:d}",
+            )
+        )
+        pairs = ", ".join(
+            f"{_text_literal(entry.key)}, "
+            f"{kept}.{self.quoting.quote(_kept_entry(position))}"
+            for position, entry in enumerate(node.entries)
+        )
+        ordering = ", ".join(
+            f"{kept}.{self.quoting.quote(_kept_order(position))}"
+            f"{' DESC' if order.descending else ''}"
+            for position, order in enumerate(node.orders)
+        )
+        row = f"{functions.object_function}({pairs})"
+        aggregate = f"{functions.array_function}({row} ORDER BY {ordering})"
+        return "".join(
+            (
+                "(SELECT COALESCE(",
+                aggregate,
+                ", ",
+                functions.empty_array,
+                ") FROM (",
+                inner,
+                f") AS {kept})",
+            )
+        )
+
+    def _collection_row(self, node: CollectionNode) -> str:
+        """One row of the collection, as the object it is gathered into."""
+        pairs = ", ".join(
+            f"{_text_literal(entry.key)}, {self.compile(entry.expression)}"
+            for entry in node.entries
+        )
+        return f"{self.collection_functions.object_function}({pairs})"
+
+    def _collection_reading(self, node: CollectionNode) -> str:
+        """The table a collection reads, and whatever it reads alongside it.
+
+        Every join is a left join. A join widens what each row of a collection
+        carries and does not decide which rows there are, and an inner one
+        would drop a row whose join matched nothing: a null foreign key, or a
+        row pointing at one that is not there. The row is the collection's
+        answer, so it stays and the value it could not reach reads as null.
+        """
+        joined = "".join(
+            f" LEFT JOIN {self.qualified_join(join)} ON {self.compile(join.condition)}"
+            for join in node.joins
+        )
+        return f"{self.qualified_table(node)}{joined}"
+
+    def _collection_order(self, node: CollectionNode) -> str:
+        if not node.orders:
+            return ""
+        terms = ", ".join(
+            f"{self.compile(order.expression)}{' DESC' if order.descending else ''}"
+            for order in node.orders
+        )
+        return f" ORDER BY {terms}"
+
+    def _require_collection_order(
+        self,
+        node: CollectionNode,
+        functions: CollectionFunctions,
+    ) -> None:
+        if not node.orders or functions.ordered:
+            return
+        message = (
+            f"{self.dialect} cannot order rows inside a collection; fetch this "
+            f"relation with select-in instead"
+        )
+        raise UnsupportedQueryError(message)
+
+    def _compile_exists(self, node: ExistsNode) -> str:
+        if self._render_query is None:
+            message = f"{self.dialect} cannot read a query inside an expression"
+            raise CompilationError(message)
+        prefix = "NOT EXISTS" if node.negated else "EXISTS"
+        return f"{prefix} ({self._render_query(node.query)})"
+
+    def _compile_unary(self, node: UnaryNode) -> str:
+        operand = self.compile(node.operand)
+        if node.operator is UnaryOperator.NOT:
+            return f"(NOT {operand})"
+        if node.operator is UnaryOperator.NEGATE:
+            return f"(-{operand})"
+        suffix = _UNARY_SUFFIX.get(node.operator)
+        if suffix is None:
+            message = f"unsupported {self.dialect} unary operator: {node.operator}"
+            raise UnsupportedQueryError(message)
+        return f"({operand} {suffix})"
+
+    def render_binary(self, node: BinaryNode, left: str, right: str) -> str:
+        operator = self.binary_operator_sql(node.operator)
+        if operator is None:
+            message = f"unsupported {self.dialect} binary operator: {node.operator}"
+            raise UnsupportedQueryError(message)
+        rendered = self._context.structural_text(operator)
+        return f"({left} {rendered} {right})"
+
+    def _compile_binary(self, node: BinaryNode) -> str:
+        self.validate_binary(node)
+        return self.render_binary(
+            node, self.compile(node.left), self.compile(node.right)
+        )
+
+    def _compile_variadic(self, node: VariadicNode) -> str:
+        if node.operator in {VariadicOperator.IN, VariadicOperator.NOT_IN}:
+            return self._compile_membership(node)
+        if node.operator in {VariadicOperator.BETWEEN, VariadicOperator.NOT_BETWEEN}:
+            return self._compile_range(node)
+        if node.operator is VariadicOperator.AND:
+            separator = " AND "
+        elif node.operator is VariadicOperator.OR:
+            separator = " OR "
+        else:
+            message = f"unsupported {self.dialect} variadic operator: {node.operator}"
+            raise UnsupportedQueryError(message)
+        return f"({separator.join(self.compile(item) for item in node.operands)})"
+
+    def _compile_membership(self, node: VariadicNode) -> str:
+        expression, *values = node.operands
+        if not values:
+            return "(1 = 1)" if node.operator is VariadicOperator.NOT_IN else "(0 = 1)"
+        operator = "NOT IN" if node.operator is VariadicOperator.NOT_IN else "IN"
+        rendered_values = ", ".join(self.compile(value) for value in values)
+        return f"({self.compile(expression)} {operator} ({rendered_values}))"
+
+    def _compile_range(self, node: VariadicNode) -> str:
+        if len(node.operands) != 3:
+            message = f"{self.dialect} range predicate requires exactly three operands"
+            raise CompilationError(message)
+        expression, lower, upper = node.operands
+        operator = (
+            "NOT BETWEEN"
+            if node.operator is VariadicOperator.NOT_BETWEEN
+            else "BETWEEN"
+        )
+        return (
+            f"({self.compile(expression)} {operator} {self.compile(lower)} "
+            f"AND {self.compile(upper)})"
+        )
+
+    def _compile_case(self, node: CaseNode) -> str:
+        branches = " ".join(
+            f"WHEN {self.compile(when)} THEN {self.compile(then)}"
+            for when, then in node.branches
+        )
+        if node.otherwise is None:
+            return f"CASE {branches} END"
+        return f"CASE {branches} ELSE {self.compile(node.otherwise)} END"
+
+    def _compile_function(self, node: FunctionNode) -> str:
+        if node.name in _CHOOSING_FUNCTIONS:
+            arguments = ", ".join(self.compile(argument) for argument in node.arguments)
+            return f"{self.choosing_function_sql(node.name)}({arguments})"
+        if node.name in _SCALAR_TRANSFORMS:
+            if len(node.arguments) != 1:
+                message = f"{self.dialect} scalar transform requires one argument"
+                raise CompilationError(message)
+            name = node.name.value.upper()
+            return f"{name}({self.compile(node.arguments[0])})"
+        if len(node.arguments) != 2:
+            message = f"{self.dialect} string predicate requires two arguments"
+            raise CompilationError(message)
+        return self.render_string_predicate(node)
+
+    def _compile_aggregate(self, node: AggregateNode) -> str:
+        name = _AGGREGATE_SQL.get(node.name) or self._json_aggregate_sql(node.name)
+        if name is None:
+            message = f"unsupported {self.dialect} aggregate: {node.name}"
+            raise UnsupportedQueryError(message)
+        if not node.arguments:
+            return f"{name}(*)"
+        distinct = "DISTINCT " if node.distinct else ""
+        arguments = ", ".join(self.compile(argument) for argument in node.arguments)
+        return f"{name}({distinct}{arguments})"
+
+    def _json_aggregate_sql(self, name: AggregateName) -> str | None:
+        """Gathering rows into JSON, which each dialect calls its own thing."""
+        functions = self.collection_functions
+        if name is AggregateName.JSON_ARRAY_AGG:
+            return functions.array_function
+        if name is AggregateName.JSON_OBJECT_AGG:
+            return functions.object_aggregate
+        return None
+
+    def render_json_build(self, node: JsonBuildNode) -> str:
+        """A JSON value built from the values around it, named per dialect."""
+        functions = self.collection_functions
+        if node.kind is JsonBuild.ARRAY:
+            built = functions.array_constructor
+        else:
+            built = functions.object_function
+        arguments = ", ".join(self.compile(argument) for argument in node.arguments)
+        return f"{built}({arguments})"
+
+    def _compile_raw(self, node: RawNode) -> str:
+        self.require_raw_expressions()
+        fragments: list[str] = []
+        for part in node.parts:
+            if isinstance(part, str):
+                self._validate_raw_text(part)
+                fragments.append(self._context.structural_text(part))
+            else:
+                fragments.append(self.compile(part))
+        return f"({''.join(fragments)})"
+
+    def _validate_raw_text(self, value: str) -> None:
+        if _UNSAFE_RAW_TEXT.search(value):
+            message = (
+                f"{self.dialect} raw text cannot contain bind markers "
+                "or statement syntax"
+            )
+            raise CompilationError(message)
+
+
+__all__ = ("ExpressionRenderer",)