snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/sql/aggregate.py

@@ -0,0 +1,232 @@
+"""Emission of aggregates (COUNT/EXISTS/projection) reusing a SELECT's FROM+JOINs+WHERE.
+
+Same deep-navigation `plan`; they project an aggregate instead of columns.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import fields, is_dataclass
+from typing import Any
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.core.exceptions import SnakeEmitError
+from snakeorm.expressions import (
+    SnakeAggregate,
+    SnakeStringAgg,
+    SnakeCondition,
+    SnakeOrder,
+    SnakeValue,
+    count,
+)
+from snakeorm.expressions.window import has_window
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.sql.condition import emit_condition_into
+from snakeorm.sql.joins import JoinPlan
+from snakeorm.sql.refs import qualified
+from snakeorm.sql.value import Correlation, ExistsAliases, emit_order_key, emit_value
+
+
+def emit_count(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    where: SnakeCondition | None = None,
+    plan: JoinPlan | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `SELECT COUNT(*) FROM ... [JOINs] [WHERE]`.
+
+    The COUNT(*) is emitted through the `count()` node (the only place that knows how to write it);
+    it consumes no params.
+    """
+    params: list[object] = []
+    qualify = plan.alias_for if plan is not None else None
+    projected = emit_value(count(), dialect, params, qualify)
+    return (
+        f"SELECT {projected} {_from_where(table, dialect, params, where, plan)}",
+        tuple(params),
+    )
+
+
+def emit_exists(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    where: SnakeCondition | None = None,
+    plan: JoinPlan | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `SELECT EXISTS(SELECT 1 FROM ... [JOINs] [WHERE])`."""
+    params: list[object] = []
+    inner = _from_where(table, dialect, params, where, plan)
+    return f"SELECT EXISTS(SELECT 1 {inner})", tuple(params)
+
+
+def emit_project(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    columns: Sequence[SnakeValue[Any]],
+    where: SnakeCondition | None = None,
+    plan: JoinPlan | None = None,
+    group_by: Sequence[SnakeValue[Any]] = (),
+    having: SnakeCondition | None = None,
+    order_by: tuple[SnakeOrder, ...] = (),
+    limit: int | None = None,
+    offset: int | None = None,
+    functional_dependency: bool = False,
+    distinct: bool = False,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `SELECT [DISTINCT] <cols> FROM ... [JOINs] [WHERE] [GROUP BY] [HAVING] [ORDER BY] [LIMIT]`.
+
+    Params in clause order (= SQL evaluation order) for continuous numbering. `having` without
+    `group_by` is valid (a global aggregate). `functional_dependency=True` disables the GROUP BY
+    guard: it is used by `annotate()`, which projects every column while grouping only by the PK
+    (they all depend on it).
+    """
+    if not functional_dependency:
+        _guard_grouped_projection(columns, group_by)
+    _guard_no_window_in_group_by(group_by)
+    params: list[object] = []
+    qualify = plan.alias_for if plan is not None else None
+    # One single correlation for the whole statement: aggregates that are correlated subqueries
+    # (e.g. a `collection.count()` projected by annotate) need to know how to reference the parent.
+    # Plain columns and aggregates ignore it.
+    correlate = _correlation(table, dialect, plan)
+    projected = ", ".join(
+        emit_value(column, dialect, params, qualify, correlate) for column in columns
+    )
+    keyword = "SELECT DISTINCT" if distinct else "SELECT"
+    sql = f"{keyword} {projected} {_from_where(table, dialect, params, where, plan)}"
+    if group_by:
+        keys = ", ".join(
+            emit_value(column, dialect, params, qualify, correlate)
+            for column in group_by
+        )
+        sql = f"{sql} GROUP BY {keys}"
+    if having is not None:
+        sql = f"{sql} HAVING {emit_condition_into(having, dialect, params, qualify, correlate)}"
+    if order_by:
+        keys = ", ".join(
+            emit_order_key(key, dialect, params, qualify, correlate) for key in order_by
+        )
+        sql = f"{sql} ORDER BY {keys}"
+    clause = dialect.limit_offset(limit, offset, params)
+    if clause:
+        sql = f"{sql} {clause}"
+    return sql, tuple(params)
+
+
+def _correlation(
+    table: SnakeTableInfo, dialect: SnakeDialect, plan: JoinPlan | None
+) -> Correlation:
+    """Correlation context for the HAVING (in case it carries correlated subqueries)."""
+    parent_ref = (
+        plan.root_alias if plan is not None else dialect.quote_ident(table.name)
+    )
+    return Correlation(parent_ref=parent_ref, aliases=ExistsAliases())
+
+
+def _flattened(child: object) -> Iterator[object]:
+    """One field's value as nodes, unwrapping sequences however deeply they nest.
+
+    A `CASE` keeps its branches as a tuple OF TUPLES, so unwrapping one level finds a tuple and
+    stops there — which is how the aggregate inside a branch stayed invisible.
+    """
+    if isinstance(child, (tuple, list)):
+        for item in child:
+            yield from _flattened(item)
+    else:
+        yield child
+
+
+def _subnodes(value: object) -> Iterator[object]:
+    """The direct children of an expression node, with its sequences flattened out.
+
+    It reads the node's own fields instead of naming the node types, and that is deliberate: the set
+    of things that can wrap an aggregate is open — `COALESCE`, `NULLIF`, `CASE`, arithmetic, a cast,
+    and whatever comes next. A walk that lists them is a walk that has to be remembered.
+    """
+    if not is_dataclass(value) or isinstance(value, type):
+        return
+    for field in fields(value):
+        yield from _flattened(getattr(value, field.name))
+
+
+def _aggregated_paths(value: object) -> set[tuple[str, ...]]:
+    """Every path that sits INSIDE an aggregate, however deeply it is wrapped.
+
+    An aggregate's own paths are all of them: `SUM(x)` aggregates `x` wherever the `SUM` appears.
+
+    `SnakeStringAgg` is named alongside `SnakeAggregate` and not folded into it: it IS an aggregate
+    —it collapses a group— but it is a separate node because its separator has no fixed position
+    across the engines. A walk that only knew the one class would have refused `string_agg(name)`
+    beside a `GROUP BY` as an ungrouped column, which is the opposite of what it is.
+    """
+    if isinstance(value, (SnakeAggregate, SnakeStringAgg)):
+        return set(value.paths())
+    found: set[tuple[str, ...]] = set()
+    for child in _subnodes(value):
+        found |= _aggregated_paths(child)
+    return found
+
+
+def _guard_grouped_projection(
+    columns: Sequence[SnakeValue[Any]], group_by: Sequence[SnakeValue[Any]]
+) -> None:
+    """With GROUP BY, every non-aggregated projected column must be grouped (caught before Postgres).
+
+    The comparison goes through `paths()`. A path is fine when it is grouped OR when it sits inside
+    an aggregate — which is what the error message has always said, and what the check used to
+    decide by asking whether the projected node ITSELF was an aggregate. `COALESCE(SUM(x), 0)` is
+    valid on every engine and was being refused, because the outer node is a `COALESCE`.
+
+    The other direction is what the walk must not lose: `COALESCE(name, '')` aggregates nothing, and
+    a bare column laundered through a wrapper has to stay an error.
+    """
+    if not group_by:
+        return
+    grouped = {path for column in group_by for path in column.paths()}
+    for column in columns:
+        aggregated = _aggregated_paths(column)
+        for path in column.paths():
+            if path not in grouped and path not in aggregated:
+                name = ".".join(path)
+                raise SnakeEmitError(
+                    f"Column '{name}' appears in the projection but neither in the GROUP BY "
+                    f"nor inside an aggregate. Add it to group_by(...) or aggregate it."
+                )
+
+
+def _from_where(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    params: list[object],
+    where: SnakeCondition | None,
+    plan: JoinPlan | None,
+) -> str:
+    """Builds `FROM <table> [AS t0] [JOINs] [WHERE <cond>]` (shared by count/exists)."""
+    qualify = plan.alias_for if plan is not None else None
+    table_ref = qualified(table.schema, table.name, dialect)
+    if plan is not None:
+        table_ref = f"{table_ref} AS {plan.root_alias}"
+    sql = f"FROM {table_ref}"
+    if plan is not None and plan.has_joins:
+        sql = f"{sql} {' '.join(plan.joins)}"
+    if where is not None:
+        parent_ref = (
+            plan.root_alias if plan is not None else dialect.quote_ident(table.name)
+        )
+        correlate = Correlation(parent_ref=parent_ref, aliases=ExistsAliases())
+        sql = f"{sql} WHERE {emit_condition_into(where, dialect, params, qualify, correlate)}"
+    return sql
+
+
+def _guard_no_window_in_group_by(group_by: Sequence[SnakeValue[Any]]) -> None:
+    """A window cannot group: SQL evaluates windows AFTER the GROUP BY.
+
+    The condition guard covers WHERE/HAVING, but the GROUP BY is a list of values, not a condition.
+    """
+    for value in group_by:
+        if has_window(value):
+            raise SnakeEmitError(
+                "A window function cannot go in a GROUP BY: SQL evaluates it AFTER grouping, so "
+                "there is nothing to group by yet. Group by the columns and project the window, "
+                "or wrap the query and group on the outside."
+            )

snakeorm/sql/condition.py

@@ -0,0 +1,359 @@
+"""Emission of a parametrised WHERE: SnakeCondition -> (sql, params).
+
+Walks the boolean AST and produces SQL with the dialect's placeholders; the values travel in
+`params` (kills injection and enables multi-engine). `qualify` qualifies columns with an alias (deep
+JOINs).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.core.exceptions import (
+    SnakeEmitError,
+    SnakeNodeError,
+    SnakeUnsupportedFeature,
+)
+from snakeorm.expressions import (
+    SnakeAnd,
+    SnakeComparison,
+    SnakeCondition,
+    SnakeExists,
+    SnakeExistsJoin,
+    SnakeInList,
+    SnakeInSubquery,
+    SnakeIsNotNull,
+    SnakeIsNull,
+    SnakeLike,
+    SnakeNot,
+    SnakeOr,
+    SnakeSubquery,
+    SnakeTupleIn,
+)
+from snakeorm.expressions.window import has_window
+from snakeorm.sql.refs import qualified
+from snakeorm.sql.value import (
+    Correlation,
+    ExistsAliases,
+    Qualify,
+    emit_expression_or_literal,
+    emit_operand,
+    emit_value,
+)
+
+
+def emit_condition(
+    condition: SnakeCondition,
+    dialect: SnakeDialect,
+    qualify: Qualify | None = None,
+    correlate: Correlation | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Translates an AST condition into a parametrised `(sql, params)`."""
+    params: list[object] = []
+    sql = emit_condition_into(condition, dialect, params, qualify, correlate)
+    return sql, tuple(params)
+
+
+def inline_params(sql: str, params: Sequence[object], dialect: SnakeDialect) -> str:
+    """Replaces a compiled SQL's placeholders with their literals, for DDL (which takes no params).
+
+    A forward pass that never revisits: a literal containing the placeholder token is not
+    reinterpreted. The token is asked of the dialect by index (for numbered placeholders `$1`, `$2`).
+    """
+    written: list[str] = []
+    rest = sql
+    for index, value in enumerate(params, start=1):
+        head, separator, rest = rest.partition(dialect.placeholder(index))
+        if not separator:
+            raise SnakeEmitError(
+                f"The compiled SQL is missing a placeholder for parameter {index} of "
+                f"{len(params)}: it cannot be inlined into DDL."
+            )
+        written.append(head)
+        written.append(dialect.literal(value))
+    written.append(rest)
+    return "".join(written)
+
+
+def emit_condition_ddl(condition: SnakeCondition, dialect: SnakeDialect) -> str:
+    """Emits a condition for DDL: reuses the parametrised walk and then inlines the literals.
+
+    It does not reopen injection: only the programmer's own literals get here, escaped by the
+    dialect.
+    """
+    sql, params = emit_condition(condition, dialect)
+    return inline_params(sql, params, dialect)
+
+
+def _value_in_condition(
+    value: object,
+    dialect: SnakeDialect,
+    params: list[object],
+    qualify: Qualify | None = None,
+    correlate: Correlation | None = None,
+) -> str:
+    """Emits a value inside a condition, rejecting window functions.
+
+    SQL evaluates windows AFTER WHERE/GROUP BY/HAVING. The guard lives here (the single choke point
+    every condition goes through) instead of being repeated in every node.
+    """
+    if has_window(value):
+        raise SnakeEmitError(
+            "A window function cannot be used in a WHERE, a GROUP BY or a HAVING: SQL evaluates "
+            "them AFTER those clauses. Project it with select(...) and filter on the outside, "
+            "or solve it with a subquery."
+        )
+    return emit_value(value, dialect, params, qualify, correlate)
+
+
+def emit_condition_into(
+    node: SnakeCondition,
+    dialect: SnakeDialect,
+    params: list[object],
+    qualify: Qualify | None = None,
+    correlate: Correlation | None = None,
+) -> str:
+    """Emits a node accumulating values into `params` (a side effect) and returns the SQL.
+
+    The placeholders use `len(params)`, so the numbering carries on (this is what allows combining
+    SET + WHERE without a collision). `qualify` qualifies columns with an alias; `correlate` carries
+    the EXISTS/COUNT context.
+    """
+    if isinstance(node, SnakeComparison):
+        left = _value_in_condition(node.left, dialect, params, qualify, correlate)
+        right = emit_expression_or_literal(
+            node.right, dialect, params, qualify, correlate
+        )
+        return f"{left} {node.op.value} {right}"
+    if isinstance(node, SnakeAnd):
+        joined = " AND ".join(
+            emit_condition_into(part, dialect, params, qualify, correlate)
+            for part in node.parts
+        )
+        return f"({joined})"
+    if isinstance(node, SnakeOr):
+        joined = " OR ".join(
+            emit_condition_into(part, dialect, params, qualify, correlate)
+            for part in node.parts
+        )
+        return f"({joined})"
+    if isinstance(node, SnakeInList):
+        if not node.values:
+            raise SnakeEmitError("An IN needs at least one value")
+        left = _value_in_condition(node.left, dialect, params, qualify, correlate)
+        items = ", ".join(
+            emit_expression_or_literal(value, dialect, params, qualify, correlate)
+            for value in node.values
+        )
+        return f"{left} IN ({items})"
+    if isinstance(node, SnakeTupleIn):
+        return _emit_tuple_in(node, dialect, params, qualify, correlate)
+    if isinstance(node, SnakeIsNull):
+        return f"{_value_in_condition(node.left, dialect, params, qualify, correlate)} IS NULL"
+    if isinstance(node, SnakeIsNotNull):
+        return f"{_value_in_condition(node.left, dialect, params, qualify, correlate)} IS NOT NULL"
+    if isinstance(node, SnakeLike):
+        left = _value_in_condition(node.left, dialect, params, qualify, correlate)
+        pattern = emit_expression_or_literal(
+            node.pattern, dialect, params, qualify, correlate
+        )
+        # An ESCAPE clause only if the value's wildcards were escaped (startswith/...): without it
+        # SQLite treats the `\` as a character and silently filters wrong. A raw `.like()` respects
+        # the default.
+        #
+        # The character is the backslash on all three engines — that is decided in `_escape_like`,
+        # which is engine-agnostic — but how to WRITE it inside a literal is the dialect's job, so
+        # it goes through `literal()`. Hardcoded as `'\'` this clause was ERROR 1064 on MySQL, where
+        # the backslash escapes the quote and the literal never closes: `startswith`, `contains` and
+        # `endswith` did not work on that engine at all.
+        escape = f" ESCAPE {dialect.literal(chr(92))}" if node.escaped else ""
+        if node.case_insensitive and not dialect.supports_ilike:
+            # Portable fallback: SQLite has no ILIKE, so it folds both sides to
+            # lowercase.
+            return f"LOWER({left}) LIKE LOWER({pattern}){escape}"
+        operator = "ILIKE" if node.case_insensitive else "LIKE"
+        return f"{left} {operator} {pattern}{escape}"
+    if isinstance(node, SnakeNot):
+        return f"NOT ({emit_condition_into(node.operand, dialect, params, qualify, correlate)})"
+    if isinstance(node, SnakeExists):
+        return _emit_exists(node, dialect, params, correlate)
+    if isinstance(node, SnakeInSubquery):
+        left = _value_in_condition(node.left, dialect, params, qualify, correlate)
+        return f"{left} IN ({_emit_in_subquery(node.subquery, dialect, params)})"
+    raise SnakeNodeError(f"Condition node cannot be emitted: {type(node).__name__}")
+
+
+def _emit_in_subquery(
+    sub: SnakeSubquery[Any], dialect: SnakeDialect, params: list[object]
+) -> str:
+    """Emits `SELECT <column> FROM <table> [WHERE ...]` of a scalar subquery.
+
+    Its params accumulate in the shared list (continuous numbering, positional).
+    Single-table (no alias); it gets its own correlation in case its WHERE nests
+    an EXISTS.
+    """
+    quote = dialect.quote_ident
+    table_ref = qualified(sub.schema, sub.name, dialect)
+    sql = f"SELECT {quote(sub.column)} FROM {table_ref}"
+    if sub.where is not None:
+        correlate = Correlation(parent_ref=quote(sub.name), aliases=ExistsAliases())
+        where_sql = emit_condition_into(sub.where, dialect, params, None, correlate)
+        sql = f"{sql} WHERE {where_sql}"
+    return sql
+
+
+def _guard_placeholder_ceiling(node: SnakeTupleIn, dialect: SnakeDialect) -> None:
+    """Refuses a row constructor that would bind more placeholders than the engine accepts.
+
+    The number is the engine's own declared `bind_params`, which `add_all` and the prefetch already
+    slice by; this is the one path where the caller supplies the rows by hand.
+
+    MEASURED, at two widths, because two laws were candidates. On SQLite 3.53, 16.383 keys of two
+    columns and 8.191 of four both stop at the SAME placeholder count: what governs it is the
+    placeholders. Without this the engine answers `too many SQL variables`, which names neither the
+    query nor the way out.
+
+    WHAT IS DELIBERATELY NOT GUARDED is PostgreSQL's other ceiling. Measured on 17: it refuses at
+    8.184 keys with `stack depth limit exceeded` at BOTH widths — so there the law is the number of
+    keys and not the placeholders, and it is the PARSER's recursion, well under the 65.535 of the
+    protocol. That number moves with `max_stack_depth`, which is a server setting, so the ORM cannot
+    know it: refusing at a number taken from one server's configuration would forbid on a tuned
+    server what the database there allows. The limit is written down in the reference instead of
+    invented here.
+    """
+    placeholders = len(node.rows) * len(node.columns)
+    if placeholders <= dialect.max_bind_params:
+        return
+    raise SnakeEmitError(
+        f"This composite IN binds {placeholders} placeholders — {len(node.rows)} keys of "
+        f"{len(node.columns)} columns — and {type(dialect).__name__} accepts "
+        f"{dialect.max_bind_params} per statement. Slice the list of keys and combine the results; "
+        f"the ORM will not split it for you, because the halves are separate queries and only the "
+        f"caller knows whether that is acceptable here."
+    )
+
+
+def _emit_tuple_in(
+    node: SnakeTupleIn,
+    dialect: SnakeDialect,
+    params: list[object],
+    qualify: Qualify | None,
+    correlate: Correlation | None,
+) -> str:
+    """Emits `(c1, c2) IN ((%s, %s), ...)`, or its OR-of-ANDs equivalent without `supports_row_constructor`.
+
+    No rows is unemittable (there is no `IN ()`). Columns with `emit_value` (no params),
+    values with `emit_operand` (parametrised, continuous numbering).
+    """
+    if not node.rows:
+        raise SnakeEmitError("A tuple IN needs at least one row")
+    _guard_placeholder_ceiling(node, dialect)
+    if dialect.supports_row_constructor:
+        columns = ", ".join(
+            emit_value(column, dialect, params, qualify, correlate)
+            for column in node.columns
+        )
+        rows = ", ".join(
+            "(" + ", ".join(emit_operand(value, dialect, params) for value in row) + ")"
+            for row in node.rows
+        )
+        return f"({columns}) IN ({rows})"
+    clauses: list[str] = []
+    for row in node.rows:
+        conjunction = " AND ".join(
+            f"{emit_value(column, dialect, params, qualify, correlate)} "
+            f"= {emit_operand(value, dialect, params)}"
+            for column, value in zip(node.columns, row, strict=True)
+        )
+        clauses.append(f"({conjunction})")
+    return "(" + " OR ".join(clauses) + ")"
+
+
+def _emit_exists(
+    node: SnakeExists,
+    dialect: SnakeDialect,
+    params: list[object],
+    correlate: Correlation | None,
+) -> str:
+    """Emits `EXISTS (SELECT 1 FROM child AS alias [JOINs] WHERE child.fk = parent.pk [AND cond])`.
+
+    The alias (e0, e1...) comes from its own counter shared with the nested ones (it does not
+    collide with the outer t0...). The child's condition is re-anchored to the subquery's
+    alias; its to-one navigation JOINs (`node.joins`) are emitted inside, with aliases from the
+    same counter. A composite FK ANDs every pair. Everything parametrised.
+    """
+    if correlate is None:
+        raise SnakeNodeError(
+            "SnakeExists without a correlation context: the parent cannot be referenced"
+        )
+    quote = dialect.quote_ident
+    alias = correlate.aliases.allocate()
+    # `qualified()`, not a hand-written `f"{schema}.{name}"`: an engine without schemas
+    # (SQLite) does not accept `"public".` and gave `no such table: public.x`, breaking
+    # `.any()`, `.count()` and the aggregates.
+    child_ref = qualified(node.child_schema, node.child_name, dialect)
+    on = " AND ".join(
+        f"{alias}.{quote(child_col)} = {correlate.parent_ref}.{quote(parent_col)}"
+        for child_col, parent_col in node.pairs
+    )
+    alias_map, joins_sql = _build_exists_joins(
+        node.joins, alias, correlate.aliases, dialect
+    )
+    from_clause = f"{child_ref} AS {alias}{joins_sql}"
+    if node.condition is None:
+        return f"EXISTS (SELECT 1 FROM {from_clause} WHERE {on})"
+    inner = Correlation(parent_ref=alias, aliases=correlate.aliases)
+    cond_sql = emit_condition_into(
+        node.condition, dialect, params, _exists_qualify(alias_map), inner
+    )
+    return f"EXISTS (SELECT 1 FROM {from_clause} WHERE {on} AND {cond_sql})"
+
+
+def _build_exists_joins(
+    joins: tuple[SnakeExistsJoin, ...],
+    child_alias: str,
+    aliases: ExistsAliases,
+    dialect: SnakeDialect,
+) -> tuple[dict[tuple[str, ...], str], str]:
+    """Assigns an alias to each navigated JOIN of the EXISTS and emits its clauses; returns the prefix→alias map.
+
+    JOINs ordered from parent to child (the parent is already in `alias_map`; the base child
+    takes the empty prefix). Aliases from the same shared `ExistsAliases`, so they never
+    collide. to-one ON: `parent.local = alias.remote`; a composite FK ANDs the pairs.
+    """
+    quote = dialect.quote_ident
+    alias_map: dict[tuple[str, ...], str] = {(): child_alias}
+    clauses: list[str] = []
+    for join in joins:
+        alias = aliases.allocate()
+        alias_map[join.prefix] = alias
+        parent_alias = alias_map[join.prefix[:-1]]
+        on = " AND ".join(
+            f"{parent_alias}.{quote(local)} = {alias}.{quote(remote)}"
+            for local, remote in join.pairs
+        )
+        table_ref = qualified(join.schema, join.name, dialect)
+        clauses.append(f" JOIN {table_ref} AS {alias} ON {on}")
+    return alias_map, "".join(clauses)
+
+
+def _exists_qualify(alias_map: dict[tuple[str, ...], str]) -> Qualify:
+    """Qualifies a child column (or navigated target) with the alias of its relation prefix.
+
+    `Maker.name` → `()` → the child's alias; `Maker.nation.name` → `("nation",)` → the JOIN's
+    alias. A missing prefix would be a JOIN that was never built (it should not happen after
+    validating `.any()`).
+    """
+
+    def qualify(prefix: tuple[str, ...]) -> str:
+        alias = alias_map.get(prefix)
+        if alias is None:
+            raise SnakeUnsupportedFeature(
+                "navigation inside an EXISTS without a JOIN built for prefix "
+                f"'{'.'.join(prefix)}'; it should not happen after the .any() validation."
+            )
+        return alias
+
+    return qualify

snakeorm/sql/delete.py

@@ -0,0 +1,46 @@
+"""Emission of a parametrised DELETE: `DELETE FROM <schema.table> [WHERE <cond>]`.
+
+`where=None` deletes the whole table (valid SQL): the guard-rail lives in query/session, not here.
+"""
+
+from __future__ import annotations
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.expressions import SnakeCondition
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.sql.condition import emit_condition
+from snakeorm.sql.joins import JoinPlan
+from snakeorm.sql.pk_subquery import emit_pk_in, emit_pk_subquery
+from snakeorm.sql.refs import qualified
+
+
+def emit_delete(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    where: SnakeCondition | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `DELETE FROM ... [WHERE ...]` with the params kept apart."""
+    table_ref = qualified(table.schema, table.name, dialect)
+    sql = f"DELETE FROM {table_ref}"
+    if where is None:
+        return sql, ()
+    where_sql, params = emit_condition(where, dialect)
+    return f"{sql} WHERE {where_sql}", params
+
+
+def emit_delete_pk_in_subquery(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    plan: JoinPlan,
+    where: SnakeCondition,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `DELETE FROM ... WHERE <pk> IN (SELECT <pk> FROM ... [JOINs] WHERE <deep cond>)`.
+
+    For a WHERE that navigates a relationship: it is rewritten into a subquery over the PK (avoids
+    `DELETE ... FROM`, Postgres jargon). A composite PK uses a row constructor. Parametrised.
+    """
+    table_ref = qualified(table.schema, table.name, dialect)
+    params: list[object] = []
+    subquery = emit_pk_subquery(table, dialect, plan, where, params)
+    pk_in = emit_pk_in(table, dialect, subquery)
+    return f"DELETE FROM {table_ref} WHERE {pk_in}", tuple(params)