[v1 API] 9 — Cells axis sorting: sort rows and columns by measure or field

[tomanizer]

Part of #403. Depends on #408.

What

Allow callers to control the order of row and column axis members in the cells query. Currently rows and columns are returned in natural DuckDB order with no sort guarantee.

Request addition

Add an optional sort object to the cells request body:

{
  "axes": { ... },
  "window": { ... },
  "sort": {
    "rows":    [{ "alias": "total_volume", "direction": "DESC" }],
    "columns": [{ "alias": "date",         "direction": "ASC"  }]
  }
}

alias references either a measure alias or a dimension field alias defined in the same request. Multiple sort entries are applied in order (primary sort, secondary sort, etc.).

Implementation

The sort must be applied to the axis member ordering, not to the cells themselves. The window (offset/limit) is applied after sorting, so the caller gets the Nth page of the sorted axis.

For sort.rows referencing a measure: the row members are ordered by the aggregate value of that measure (summed/averaged across all columns). This requires a sub-query or CTE that computes the per-row aggregate totals, then orders the rows by that.

For sort.rows referencing a row dimension field: standard ORDER BY field_alias ASC|DESC.

For sort.columns referencing a measure: same pattern as rows but for columns.

Validation

• alias must refer to an alias defined in axes.rows / axes.columns / axes.measures — otherwise 422 SORT_TARGET_NOT_IN_QUERY
• A row sort by a column dimension alias is invalid (and vice versa) — 422 SORT_TARGET_NOT_IN_QUERY
• direction must be ASC or DESC

Acceptance criteria

• sort.rows by measure alias returns rows in correct measure-sorted order
• sort.rows by dimension alias returns rows in field-sorted order
• sort.columns by measure alias works equivalently
• Window offset/limit is applied after sorting (page 2 of sorted results)
• Invalid alias returns 422 SORT_TARGET_NOT_IN_QUERY
• Omitting sort returns results in natural order (no regression)
• Tests cover: measure sort, field sort, multi-key sort, invalid alias, window interaction