Skip to content

F12.3 — Multi-column sorting

State Closed
Parent E12
Iteration Release 3
Start Date 2026-10-04
Closed Date 2026-10-04
Predecessors —
Source Owner request, 2026-10-04

Stories: 6 Closed

Story State Depends on
S12.3.1 — Multi-term orderBy and composite tokens in rn-forge-web Closed (2026-10-04) —
S12.3.2 — Conformance cases Closed (2026-10-04) —
S12.3.3 — SQLAlchemy keyset Closed (2026-10-04) —
S12.3.4 — Django pagination Closed (2026-10-04) —
S12.3.5 — FastAPI dependency Closed (2026-10-04) —
S12.3.6 — Documentation and release notes Closed (2026-10-04) —

AIP-132 lets orderBy name several fields (team, score desc). The API conventions allow one and answer a second with 400, because the page token holds one sort value. This feature lifts that limit on both stacks and in rn-forge-sqlalchemy. The token holds one value per term, the keyset predicate compares them in turn with mixed directions, and null values get one defined place in the order, so a nullable field can be sorted on.

Context

Outcome: the owner scheduled this feature for release 3 on 2026-10-04. The keyset predicate stays in pykit: neither sqlakeyset nor DRF's CursorPagination can carry the shared opaque token, for the reasons recorded in rn_forge.sqlalchemy.pagination and rn_forge.django.drf.pagination.

Design

Wire rules

Outcome: the API conventions §4 state the rules: several orderBy terms, the key as tie-breaker, null last in both directions, and a token bound to the whole order.

The keyset predicate

Outcome: the predicate is the expanded OR-of-ANDs form, not a row-value comparison, because that works with mixed directions and is portable across SQLite, PostgreSQL and MySQL; the rn-forge-sqlalchemy pagination reference documents keyset's contract.

API changes

Outcome: Cursor, encode_cursor and next_page_token take one sort value per term, a breaking change to rn-forge-web and rn-forge-sqlalchemy made with no compatibility shim (ADR-0002), and a token issued before it is a 400. The pagination reference lists the current API.

New conformance cases

Outcome: the cases are in CASES, documented in the conformance reference, and pagination.order-by-two-fields-is-400 is gone.

S12.3.1 — Multi-term orderBy and composite tokens in rn-forge-web

State: Closed (2026-10-04)

Acceptance:

  • parse_order_by, format_order_by, Cursor, encode_cursor, decode_cursor and check_cursor_order follow Wire rules and API changes. SortValue is exported from rn_forge.web.
  • tests/test_pagination.py covers several terms with mixed directions, a repeated field, empty terms, a token round-trip of every SortValue type including None, a token with the wrong value count, a token from the old single-value format (400), and a non-list k (400).

S12.3.2 — Conformance cases

State: Closed (2026-10-04)

Acceptance: CASES gains the cases in New conformance cases and loses pagination.order-by-two-fields-is-400. The existing pagination tokens in the table are re-encoded in the new format. The Django, FastAPI and rn-forge-sqlalchemy drivers each serve /conformance/people and run every pagination case with no skips.

S12.3.3 — SQLAlchemy keyset

State: Closed (2026-10-04)

Acceptance:

  • keyset and next_page_token follow The keyset predicate and API changes.
  • tests/test_pagination.py pages through every ordering of a table with ties, nulls and mixed directions, and asserts that the pages concatenate to the same rows as one unpaged query with the same order. It does so on SQLite, and on PostgreSQL under the postgres marker.
  • The rn-forge-sqlalchemy conformance driver serves /conformance/people with keyset, and every pagination case passes.

S12.3.4 — Django pagination

State: Closed (2026-10-04)

Acceptance:

  • OrderByFilter returns every term, with nulls last. CursorPagination builds the composite predicate as a Q, and reads each term's value from the last row by field path, so a related lookup (author__name) works.
  • tests/drf/test_pagination.py runs the same concatenation property as S12.3.3, on SQLite and on PostgreSQL under the postgres marker.
  • The Django conformance fixture serves /conformance/people, and every pagination case passes.
  • The orderBy parameter's OpenAPI description says it takes a comma-separated list.

S12.3.5 — FastAPI dependency

State: Closed (2026-10-04)

Acceptance: order_by_param's OpenAPI description says it takes a comma-separated list and names the sortable fields. The FastAPI conformance fixture serves /conformance/people, and every pagination case passes.

S12.3.6 — Documentation and release notes

State: Closed (2026-10-04)

Acceptance:

  • The API conventions' §4 Sorting states the Wire rules and names each new case id. The sentences "A list sorts by one field" and "It must not be null" are gone.
  • The rn-forge-sqlalchemy usage guide and the Django DRF views guide show a multi-term order over a nullable column.
  • CHANGELOG.md entries for rn-forge-web, rn-forge-sqlalchemy, rn-forge-django and rn-forge-fastapi list every row of API changes as breaking.
  • The root and package sites build under --strict, and the scaffold suite passes.

Acceptance

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }

grep -q '"SortValue"' packages/rn-forge-web/src/rn_forge/web/__init__.py                   # S12.3.1
absent 'orderBy accepts one field' packages/rn-forge-web/src                               # S12.3.1
(cd packages/rn-forge-web && uv run pytest -q tests/test_pagination.py tests/test_conformance.py)   # S12.3.1, S12.3.2
grep -q 'pagination.composite-token-resumes-after-a-null' packages/rn-forge-web/src/rn_forge/web/conformance/cases.py   # S12.3.2
absent 'pagination.order-by-two-fields-is-400' packages/                                   # S12.3.2
(cd packages/rn-forge-sqlalchemy && uv run pytest -q)                                     # S12.3.3
(cd packages/rn-forge-django && uv run pytest -q tests/drf/test_pagination.py tests/test_conformance.py)   # S12.3.4
(cd packages/rn-forge-fastapi && uv run pytest -q tests/test_dependencies.py tests/test_conformance.py)    # S12.3.5
uv run pyright                                                                            # S12.3.1, S12.3.3–S12.3.5
uv run lint-imports                                                                       # S12.3.1, S12.3.3–S12.3.5
absent 'A list sorts by one field' packages/rn-forge-web/docs/guides/api-conventions.md   # S12.3.6
for pkg in web sqlalchemy django fastapi; do
  grep -qi 'orderBy' "packages/rn-forge-$pkg/CHANGELOG.md"                                 # S12.3.6
  (cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)")   # S12.3.6
done
uv run pytest -q -m scaffold                                                              # S12.3.6

The PostgreSQL legs of S12.3.3 and S12.3.4 run in CI's postgres job, which sets the DSN. rn-forge-sqlalchemy joins that job through its [tool.workspace-ci.postgres] table (RN_FORGE_TEST_POSTGRES_DSN), and its tests/conftest.py rewrites CI's bare postgresql:// scheme to postgresql+asyncpg:// for the async engine.

Considered and rejected

  • Row-value comparison, (a, b, id) > (x, y, z). It is short, but it only works when every term has the same direction, and SQLite before 3.15 and some MySQL plans handle it poorly. The expanded form handles mixed directions everywhere.
  • The database's own null placement. PostgreSQL puts nulls last ascending and first descending, while SQLite and MySQL do the opposite. One stack would then disagree with another on the same data, which §9's identical-wire rule forbids.
  • Nulls first in both directions, or nulls as the smallest value. "Smallest" moves nulls to the top of a descending list, where a UI shows empty cells first. Last in both directions matches what spreadsheet and table UIs do.
  • A cap on the number of terms. The endpoint's list of sortable fields already bounds it, and each field appears at most once.
  • Accepting old single-value tokens. A token lives for one request, so a client holding one across a deploy retries from the first page. A dual-format decoder would outlive its use.