sdmxlib 0.64.0__tar.gz → 0.65.0__tar.gz

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.64.0
+Version: 0.65.0
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.64.0"
+version = "0.65.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 requires-python = ">=3.13"

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.64.0"
+version = "0.65.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/__init__.py

@@ -19,7 +19,7 @@ from sdmxlib.session import Session, SessionHook, ValueSet
 from sdmxlib.query import RawSql, RawSqlError, schema
 from sdmxlib.query.accessors import ArtefactRow, CodeRow, HCodeRow, ReportedAttributeRow, q
 from sdmxlib.query._compile import CompiledQuery
-from sdmxlib.query._expr import Agg, AggPred, AnyPred, Col, Cols, Cursor, Pred, RowKind, Win, WinFn, WinPred
+from sdmxlib.query._expr import Agg, AggPred, AnyPred, Col, Cols, Cursor, Pred, RowKind, Untyped, Win, WinFn, WinPred
 from sdmxlib.query.observations import ObsQuery, ObsRow
 from sdmxlib.query.query import Frame, Grouped, Page, Query, union
 from sdmxlib.sql import SqlRelation
@@ -136,6 +136,27 @@ from sdmxlib.model import (
     artefact_urn,
 )
 
+
+def len[R: RowKind]() -> Agg[R]:  # noqa: A001 - polars' `pl.len()`; nothing in this module calls the builtin
+    """The number of rows, as an aggregate — `count(*)`, named for polars' `pl.len()`.
+
+    For `Query.agg`, which folds a whole query into one row, so the row count
+    can come out of the same scan as the other aggregates (#414):
+
+        obs.agg(SEX=obs.col("SEX").unique(), n=sl.len())
+
+    A function rather than a column method because it counts *rows*, not the
+    values of any column — the same reason `group_by(...).len()` is a method on
+    the grouping rather than on a column. The row kind is taken from where it is
+    used, so it fits any query's `agg`.
+
+    Shadows the builtin only as `sl.len`; this module never calls `len()`
+    itself, which is why it is defined here rather than re-exported from a
+    module that would need a second suppression.
+    """
+    return Agg[R]("count", ())
+
+
 __all__ = [
     "Agency",
     "AgencyScheme",
@@ -278,6 +299,7 @@ __all__ = [
     "SupportsUrn",
     "TimeDimension",
     "UnresolvedRef",
+    "Untyped",
     "ValidationError",
     "ValidationIssue",
     "ValueMap",
@@ -290,6 +312,7 @@ __all__ = [
     "dim",
     "from_dict",
     "item",
+    "len",
     "parse",
     "parse_components",
     "q",

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/formats/sdmx_csv/writer.py

@@ -23,7 +23,7 @@ column maps in their dict-insertion order, which matches the order in
 which they were declared on the structure.
 
 Performance: rows are serialised via Polars' Rust CSV writer
-(``pl.from_arrow(batch).write_csv``) rather than Python's `csv`,
+(``pl.DataFrame(batch).write_csv``) rather than Python's `csv`,
 which makes the writer fast enough that bulk SDMX-CSV downloads are
 network-bound rather than writer-bound (#61).
 
@@ -43,7 +43,7 @@ Example:
 from __future__ import annotations
 
 import io
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 
 import polars as pl
 
@@ -143,10 +143,11 @@ def write_sdmx_csv(
             )
             raise KeyError(msg)
 
-        # pl.from_arrow returns DataFrame | Series; a RecordBatch always
-        # gives back a DataFrame, but the union is sticky in the stubs.
+        # The constructor rather than `pl.from_arrow`, which is typed
+        # `DataFrame | Series` and since polars 2.0 really does return a Series
+        # for stream-only inputs — a `cast` here would have hidden that.
         df = (
-            cast("pl.DataFrame", pl.from_arrow(batch))
+            pl.DataFrame(batch)
             .select(data_cols)
             .with_columns(
                 pl.lit(structure).alias("STRUCTURE"),

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/formats/sdmx_json/_data_common.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import calendar
 import re
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING, Literal, NamedTuple, TypedDict, cast
+from typing import TYPE_CHECKING, Literal, NamedTuple, TypedDict
 
 import msgspec
 import polars as pl
@@ -640,7 +640,11 @@ def encode_batch(
         )
         raise KeyError(msg)
 
-    df = cast("pl.DataFrame", pl.from_arrow(batch))
+    # The constructor, not `pl.from_arrow`: the same frame for a RecordBatch, but
+    # typed `DataFrame` rather than `DataFrame | Series` — and polars 2.0 made
+    # `from_arrow` return a Series for stream-only inputs, which a `cast` would
+    # have passed through unchecked.
+    df = pl.DataFrame(batch)
     n = df.height
     if n == 0:
         return b""

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/local/sql.py

@@ -59,6 +59,20 @@ if TYPE_CHECKING:
     from sdmxlib.model.binding import DataflowBinding
 
 
+class SidecarNotUniqueError(ValueError):
+    """A series-attributes sidecar holds more than one row per join key (#412).
+
+    The sidecar is joined as `LEFT JOIN … USING (<keys>)`, so every extra row
+    per key multiplies each observation it matches. Nothing errors downstream:
+    `count()`, `collect()` and every aggregate over a sidecar column come back
+    inflated by the fan-out factor, and every row looks valid.
+
+    A `ValueError` because it is the same kind of refusal `plan` already makes
+    for a sidecar sharing no columns — the binding names a table that cannot
+    serve as its series attributes — so a caller catching that catches this.
+    """
+
+
 @frozen(kw_only=True)
 class QueryPlan:
     """The resolved ``FROM`` side of a `DataflowBinding`'s query.
@@ -109,6 +123,10 @@ class SchemaInspector:
     def __init__(self, conn: duckdb.DuckDBPyConnection) -> None:
         self._conn = conn
         self._columns_cache: dict[str, tuple[str, ...]] = {}
+        #: (table, keys) -> (rows, distinct keys), for `key_counts`. Shares
+        #: `_columns_cache`'s lock and lifecycle: both describe a table as it
+        #: stands, and `invalidate` is the one signal that it changed.
+        self._key_counts_cache: dict[tuple[str, tuple[str, ...]], tuple[int, int]] = {}
         self._lock = threading.Lock()
 
     def columns(self, table: str) -> tuple[str, ...]:
@@ -139,15 +157,50 @@ class SchemaInspector:
         cols_b = set(self.columns(table_b))
         return tuple(c for c in self.columns(table_a) if c in cols_b)
 
+    def key_counts(self, table: str, keys: tuple[str, ...]) -> tuple[int, int]:
+        """``(rows, distinct key combinations)`` of ``table`` over ``keys`` (cached).
+
+        Rows with a NULL in any key are left out of both counts: `USING` never
+        matches NULL, so repeated NULL-keyed rows cannot multiply a join, and
+        refusing a table for them would be refusing a harmless one.
+
+        A scan of the table — ~5 ms on cenprof-2021-csip's 619-row geography
+        sidecar, ~37 ms cold — so memoised single-flight beside `columns`, and
+        dropped by `invalidate` with it.
+
+        Args:
+            table: The table to count, as `columns` takes it.
+            keys: The columns whose combinations are counted.
+        """
+        cache_key = (table, keys)
+        cached = self._key_counts_cache.get(cache_key)
+        if cached is not None:
+            return cached
+        with self._lock:
+            cached = self._key_counts_cache.get(cache_key)
+            if cached is not None:
+                return cached
+            tuple_sql = ", ".join(keys)
+            not_null = " AND ".join(f"{k} IS NOT NULL" for k in keys)
+            row = self._conn.execute(
+                f"SELECT count(*), count(DISTINCT ({tuple_sql})) FROM {table} WHERE {not_null}"
+            ).fetchone()
+            counts = (int(row[0]), int(row[1])) if row else (0, 0)
+            self._key_counts_cache[cache_key] = counts
+            return counts
+
     def invalidate(self, table: str) -> None:
-        """Drop the cached column list for ``table`` (e.g. after a rewrite)."""
+        """Drop everything cached about ``table`` (e.g. after a rewrite)."""
         with self._lock:
             self._columns_cache.pop(table, None)
+            for cache_key in [k for k in self._key_counts_cache if k[0] == table]:
+                del self._key_counts_cache[cache_key]
 
     def invalidate_all(self) -> None:
-        """Drop all cached column lists."""
+        """Drop everything cached about every table."""
         with self._lock:
             self._columns_cache.clear()
+            self._key_counts_cache.clear()
 
     def plan(self, binding: DataflowBinding) -> QueryPlan:
         """Resolve ``binding``'s main/sidecar tables into a `QueryPlan`.
@@ -163,6 +216,9 @@ class SchemaInspector:
         Raises:
             ValueError: If the binding names a sidecar that shares no columns
                 with the main table (no derivable join keys).
+            SidecarNotUniqueError: If the sidecar holds more than one row for
+                some combination of those keys, which would multiply every
+                observation the join matches (#412).
         """
         main = f"{binding.database_role}.{binding.table_location}"
         sidecar_loc = binding.series_attributes_location
@@ -176,4 +232,15 @@ class SchemaInspector:
                 f"shares no columns with {main!r}; cannot derive JOIN keys"
             )
             raise ValueError(msg)
+        rows, distinct = self.key_counts(sidecar, join_keys)
+        if rows != distinct:
+            keys = ", ".join(join_keys)
+            msg = (
+                f"series-attributes sidecar {sidecar!r} holds {rows:,} rows but only {distinct:,} distinct "
+                f"({keys}) — joined on those keys, every observation of a repeated series would be counted "
+                f"once per sidecar row, so counts and aggregates over its columns come back inflated (#412). "
+                f"The keys are the columns the two tables share; make the sidecar unique on them, or drop the "
+                f"shared columns that are not part of the series key."
+            )
+            raise SidecarNotUniqueError(msg)
         return QueryPlan(main=main, sidecar=sidecar, join_keys=join_keys)

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/model/dataset.py

@@ -156,8 +156,16 @@ class Dataset:
             if hint_cl is not None:
                 on_columns = hint_cl.code_ids()
             else:
-                # Codelist not resolved — discover column values from the data
-                on_columns = self.data.select(pivot_id).unique().collect()[pivot_id].cast(pl.String).to_list()
+                # Codelist not resolved — discover column values from the data.
+                # Sorted, because `unique` promises no order and the wide
+                # frame's columns would otherwise change from run to run.
+                on_columns = (
+                    self.data.select(pl.col(pivot_id).cast(pl.String))
+                    .unique()
+                    .sort(pivot_id)
+                    .collect()[pivot_id]
+                    .to_list()
+                )
             index = [d.id for d in self.structure.dimensions if d.id != pivot_id]
 
         else:
@@ -187,11 +195,15 @@ class Dataset:
             index.append(self.structure.time_dimension.id)
         measures = self.measures
         values = measures[0] if len(measures) == 1 else measures
+        # `maintain_order`: rows in the order their series first appear, which
+        # is `DataFrame.pivot`'s contract. The lazy pivot defaults to no order,
+        # and at a few thousand series that order differs run to run.
         return self.data.pivot(
             on=pivot_id,
             on_columns=pl.Series(on_columns),
             index=index,
             values=values,
+            maintain_order=True,
         )
 
     # ── SDMX-aware expressions ────────────────────────────────────────────────

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/polars.py

@@ -208,6 +208,10 @@ def validation_report(
             .rename({comp.id: "invalid_value"})
             .with_columns(pl.lit(comp.id).alias("column"))
             .select("column", "invalid_value", "count")
+            # `group_by` promises no order, and at a few thousand values the
+            # order it gives differs run to run — on polars 1.x and 2.0 alike.
+            # Components stay in DSD order (the loop); values within one sort.
+            .sort("invalid_value")
             .collect()
         )
         if not bad.is_empty():

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/query/_compile.py

@@ -843,12 +843,28 @@ class _Scope:
         for windows, applied a third time.
         """
         if isinstance(item, AnyAgg):
-            refs = [self._flat_reference(column, context="in a grouped aggregate") for column in item.columns]
-            body = self._agg_body_from(item, refs)
+            body = self._grouped_agg_body(item, context="in a grouped aggregate")
             return Sql(f"{body.text} AS {name}", body.params)
         ref = self._flat_reference(item, context="as a group key")
         return Sql(f"{ref.text} AS {name}", ref.params)
 
+    def _grouped_agg_body(self, agg: AnyAgg, *, context: str) -> Sql:
+        """A plain aggregate over the group's rows, honouring the column's `.sort()`.
+
+        The order was dropped here until #414: `col.sort().unique()` compiled to
+        `list(DISTINCT col ORDER BY col)` through a fan-out but to an unordered
+        `list(DISTINCT col)` in a `group_by().agg()` — the caller asked for an
+        order and silently did not get one. Read off the column exactly as
+        `_agg_subquery` reads it, so the two readings of an `Agg` agree.
+        """
+        refs = [self._flat_reference(column, context=context) for column in agg.columns]
+        order = agg.columns[0]._order if agg.columns else None
+        order_sql: Sql | None = None
+        if order is not None:
+            key_ref = self._flat_reference(order[0], context=context)
+            order_sql = Sql(f"{key_ref.text}{' DESC' if order[1] else ''}", key_ref.params)
+        return self._agg_body_from(agg, refs, order_sql)
+
     def grouped_having(self, pred: AggPred) -> Sql:
         """One `HAVING` term — an aggregate compared to a value.
 
@@ -861,8 +877,7 @@ class _Scope:
         means the correlated-subquery reading instead, which is why the two
         clauses compile it through different methods rather than sharing one.
         """
-        refs = [self._flat_reference(column, context="in a HAVING clause") for column in pred.agg.columns]
-        body = self._agg_body_from(pred.agg, refs)
+        body = self._grouped_agg_body(pred.agg, context="in a HAVING clause")
         return Sql(f"{body.text} {pred.op} ?", (*body.params, pred.value))
 
     def _aggregate(self, name: str, agg: AnyAgg) -> Sql:
@@ -1433,6 +1448,7 @@ def compile_projection(
     distinct: bool = False,
     qualify: Sequence[AnyWinPred] = (),
     group_keys: Sequence[AnyCol] = (),
+    aggregated: bool = False,
     having: Sequence[AggPred] = (),
     positional_order: Sequence[tuple[int, bool]] = (),
     fetch_scope: str | None = None,
@@ -1454,7 +1470,13 @@ def compile_projection(
     # front of `items`, so `_projected_prefixes` has already joined them.
     # Measured — adding one was a redundant call no mutation could kill.
     scope = _Scope(table, predicates, _Namespace(), extra_paths=extra, schema=root.__schema__, joins=root.__joins__)
-    projected = [scope.grouped(name, item) if group_keys else scope.projection(name, item) for name, item in items]
+    # `aggregated` rather than `group_keys` decides how an item compiles (#414):
+    # a root-level `Query.agg` aggregates over every row with no keys at all,
+    # and keying this on the keys sent it down the per-row projection path,
+    # which correlates each aggregate over a fan-out and refuses at the root.
+    # The keys still decide `GROUP BY` and the tiebreak below.
+    grouped = aggregated or bool(group_keys)
+    projected = [scope.grouped(name, item) if grouped else scope.projection(name, item) for name, item in items]
     constraint = _constraint_clause(root.__constraint__, scope.alias)
     where = _conjoin(
         [constraint, _scope_clause(fetch_scope, scope.alias, root.__schema__), *(scope.compile(p) for p in predicates)]
@@ -1503,6 +1525,11 @@ def compile_projection(
         # would name columns the projection may have dropped.
         keys = [f"{position} {'ASC' if ascending else 'DESC'} NULLS LAST" for position, ascending in positional_order]
         ordered = Sql("\nORDER BY " + ", ".join([*keys, *(tiebreak or [])]))
+    elif aggregated and not group_keys:
+        # One row, so nothing to order — and the root-key fallback below would
+        # name row columns that are no longer in an aggregate's scope, which
+        # DuckDB rejects with a GROUP BY binder error.
+        ordered = Sql("")
     else:
         ordered = _order_sql(root, scope, order, tiebreak=tiebreak)
     # `from_sql` last: it emits only the root joins something above referenced.

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/query/_expr.py

@@ -522,29 +522,35 @@ class Agg[R: RowKind](AnyAgg):
     #
     # Approved suppression, on the grounds that it mirrors `Win.__eq__`
     # exactly — same override, same reason, same pair of checkers.
+    #
+    # Declared `AggCompare[R]`, which is what all six return (#414). They said
+    # `Pred[R]`, so `having(col.count() > 1)` — whose parameter is `AggPred` —
+    # was a type error for every typed caller; the existing `having` tests
+    # passed only because their fixture is untyped. `AggCompare` is both an
+    # `AggPred` and a `Pred[R]`, so `filter` still takes it unchanged.
     def __hash__(self) -> int:
         return id(self)
 
-    def __eq__(self, other: object) -> Pred[R]:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
+    def __eq__(self, other: object) -> AggCompare[R]:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
         return AggCompare(self, "=", other)
 
-    def __ne__(self, other: object) -> Pred[R]:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
+    def __ne__(self, other: object) -> AggCompare[R]:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
         return AggCompare(self, "!=", other)
 
     def __bool__(self) -> bool:
         msg = _ambiguous_truth("an aggregate")
         raise TypeError(msg)
 
-    def __gt__(self, other: object) -> Pred[R]:
+    def __gt__(self, other: object) -> AggCompare[R]:
         return AggCompare(self, ">", other)
 
-    def __ge__(self, other: object) -> Pred[R]:
+    def __ge__(self, other: object) -> AggCompare[R]:
         return AggCompare(self, ">=", other)
 
-    def __lt__(self, other: object) -> Pred[R]:
+    def __lt__(self, other: object) -> AggCompare[R]:
         return AggCompare(self, "<", other)
 
-    def __le__(self, other: object) -> Pred[R]:
+    def __le__(self, other: object) -> AggCompare[R]:
         return AggCompare(self, "<=", other)
 
     def over(self, *partition: Col[R]) -> Win[R]:

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/query/observations.py

@@ -44,7 +44,7 @@ from typing import TYPE_CHECKING, Self
 import attrs
 
 from sdmxlib.model.datastructure import ComponentRole
-from sdmxlib.query._expr import Col, Cols, RowKind, Untyped
+from sdmxlib.query._expr import Cols, RowKind, Untyped
 from sdmxlib.query._joins import RootJoin
 from sdmxlib.query.query import Query
 
@@ -69,10 +69,19 @@ class Sidecar:
     changes the *plan* and never the spelling: `obs["GEO_NAME"]` means the same
     thing whether the column sits on the fact table or across a join.
 
+    **One row per series, enforced.** "Once per series" means unique on the
+    join keys, and a sidecar that is not would multiply every observation it
+    matches — silently, in every count and aggregate over its columns.
+    `SchemaInspector.plan` refuses one with `SidecarNotUniqueError` (#412), so
+    a `Sidecar` that exists has been checked.
+
     Attributes:
         table: Fully-qualified sidecar table.
         join_keys: Columns common to both sides — derived by
             `SchemaInspector.plan` from the tables themselves, not declared.
+            Which is why uniqueness is checked against *these*: a sidecar unique
+            on its own key can still fan out if the two tables share fewer
+            columns than that key.
         columns: Every column the sidecar has, for deciding which side a
             component lives on.
     """
@@ -316,8 +325,17 @@ class ObsQuery(Query[ObsRow]):
     here rather than raising.
     """
 
-    def col(self, component_id: str) -> Col[ObsRow]:
-        """The column for one SDMX component. See `Observations.__getitem__`."""
+    def col(self, component_id: str) -> Untyped[ObsRow]:
+        """The column for one SDMX component. See `Observations.__getitem__`.
+
+        Declared `Untyped`, which is what it always returned (#413). It said
+        `Col` — the lie #347 corrected on `__getitem__` and left here — so the
+        operators `Untyped` really offers were invisible to every checker and
+        every reader: the comparisons, and `.str`'s `contains`, `starts_with`,
+        `ends_with` and `caseless` rung. Those four are SDMX-REST's `co`, `nc`
+        (negated), `sw` and `ew`, with the `LIKE` escaping done by
+        `_label_match` rather than by each consumer.
+        """
         root = self.plan.root
         if not isinstance(root, Observations):  # pragma: no cover - built one way
             msg = f"this query is not rooted at observations, but at {type(root).__name__}"

{sdmxlib-0.64.0 → sdmxlib-0.65.0}/src/sdmxlib/query/query.py

@@ -1676,7 +1676,10 @@ class Query[R: RowKind, A = object]:
                 the grouped result, which can also order by an aggregate.
         """
         if not keys:
-            msg = "group_by() needs at least one key — grouping by nothing is what count() already does."
+            msg = (
+                "group_by() needs at least one key. To aggregate over every row at once, use "
+                ".agg(...) — several aggregates, one row — or .count() for the row count alone."
+            )
             raise TypeError(msg)
         for key in keys:
             _require_column("group_by", key)
@@ -1690,6 +1693,58 @@ class Query[R: RowKind, A = object]:
             raise SliceError(msg)
         return Grouped(query=self, keys=tuple(keys))
 
+    def agg(self, **named: Agg[R]) -> Frame[R, A]:
+        """Several aggregates over every row of the query, in one scan (#414).
+
+        One row out, one column per aggregate — `group_by(...).agg(...)` with
+        no keys, which is why it is not spelled that way: `group_by()` refuses
+        zero keys, and a row count alone is `count()`. The case this serves is
+        *several* answers from one pass, e.g. the distinct values each
+        dimension takes under a filter, plus the row count — what SDMX-REST's
+        `/availability` returns:
+
+            obs.agg(
+                SEX=obs.col("SEX").unique(),
+                TIME_PERIOD=obs.col("TIME_PERIOD").unique(),
+                n=sl.len(),
+            ).collect()
+
+        Not always faster than one `select(col).unique()` per column. On
+        cenprof-2021 (519M rows, six dimensions) one scan lost 2.8x unfiltered
+        and won 1.1-4.8x under a filter, so it is an option to take when a
+        filter narrows the scan, not a replacement.
+
+        An `Agg` here is a plain SQL aggregate over the query's rows — the same
+        expression in `select()` is a correlated subquery over a fan-out.
+
+        Raises:
+            TypeError: If no aggregates are given, or one is a plain column —
+                with no group keys there is no single value a column could
+                take. Project it with `select()`, or `group_by()` it.
+            SliceError: If the query is ordered or sliced. An order means
+                nothing once every row folds into one, and a limit applied
+                first would silently aggregate a truncated set.
+        """
+        if not named:
+            msg = "agg() needs at least one aggregate. For the row count alone, use .count()."
+            raise TypeError(msg)
+        for name, item in named.items():
+            if not isinstance(item, Agg):
+                msg = (
+                    f"{name!r} is a column, not an aggregate — agg() folds every row into one, so a "
+                    f"column has no single value to give. Aggregate it (.unique(), .count(), .max(), …), "
+                    f"or keep it per row with select(), or per group with group_by()."
+                )
+                raise TypeError(msg)
+        if self.order_keys or self._sliced():
+            msg = (
+                "cannot agg() a query that is ordered or sliced — an order means nothing once "
+                "every row folds into one, and a limit before aggregating aggregates a truncated "
+                "set. Aggregate the whole query, then order or slice something else."
+            )
+            raise SliceError(msg)
+        return Frame(query=self, items=tuple(named.items()), aggregated=True)
+
     # ── no implicit execution ─────────────────────────────────────────────
 
     def __iter__(self) -> None:
@@ -1757,7 +1812,7 @@ class Grouped[R: RowKind, A = object]:
         # the binding's layout.
         items: list[tuple[str, AnyCol | AnyAgg]] = [(key.projected_name, key) for key in self.keys]
         items.extend(named.items())
-        return Frame(query=self._query, items=tuple(items), group_keys=self.keys)
+        return Frame(query=self._query, items=tuple(items), group_keys=self.keys, aggregated=True)
 
     def len(self) -> Frame[R, A]:
         """Count rows per group, in a column named `len` — as polars names it.
@@ -1771,7 +1826,7 @@ class Grouped[R: RowKind, A = object]:
         # the binding's layout.
         items: list[tuple[str, AnyCol | AnyAgg]] = [(key.projected_name, key) for key in self.keys]
         items.append(("len", Agg[R]("count", ())))
-        return Frame(query=self._query, items=tuple(items), group_keys=self.keys)
+        return Frame(query=self._query, items=tuple(items), group_keys=self.keys, aggregated=True)
 
     @override
     def __repr__(self) -> str:
@@ -1853,6 +1908,11 @@ class Frame[R: RowKind, A = object]:
     #: aggregates are plain `GROUP BY` aggregates rather than correlated
     #: subqueries.
     group_keys: tuple[Col[R], ...] = ()
+    #: True when every item is a plain aggregate over the query's rows — a
+    #: `group_by().agg()` (with keys) or a root `Query.agg()` (without, #414).
+    #: Separate from `group_keys` because zero keys is a real case: one row
+    #: summarising the whole filtered query.
+    aggregated: bool = False
     #: `HAVING` terms — predicates over the *groups*, not over the rows.
     having_terms: tuple[AggPred, ...] = ()
 
@@ -2076,7 +2136,7 @@ class Frame[R: RowKind, A = object]:
         # impossible — the default order made it refuse, and `order_by()` with
         # no arguments clears the caller's keys and falls back to that same
         # default, so there was no spelling that worked.
-        row_order = self._query.order_keys if (self.group_keys or self.distinct) else self._query._order
+        row_order = self._query.order_keys if (self.aggregated or self.distinct) else self._query._order
         if self._query.unordered:
             # Drops the grouped and `unique()` tiebreaks along with the row
             # order, which is the point: those exist so groups come back in a
@@ -2092,6 +2152,7 @@ class Frame[R: RowKind, A = object]:
             distinct=self.distinct,
             qualify=self._query.qualifiers,
             group_keys=self.group_keys,
+            aggregated=self.aggregated,
             having=self.having_terms,
             positional_order=self.order,
             fetch_scope=self._query._fetch_scope,