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_cursorandcheck_cursor_orderfollow Wire rules and API changes.SortValueis exported fromrn_forge.web.tests/test_pagination.pycovers several terms with mixed directions, a repeated field, empty terms, a token round-trip of everySortValuetype includingNone, a token with the wrong value count, a token from the old single-value format (400), and a non-listk(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:
keysetandnext_page_tokenfollow The keyset predicate and API changes.tests/test_pagination.pypages 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 thepostgresmarker.- The
rn-forge-sqlalchemyconformance driver serves/conformance/peoplewithkeyset, and everypaginationcase passes.
S12.3.4 — Django pagination
State: Closed (2026-10-04)
Acceptance:
OrderByFilterreturns every term, with nulls last.CursorPaginationbuilds the composite predicate as aQ, and reads each term's value from the last row by field path, so a related lookup (author__name) works.tests/drf/test_pagination.pyruns the same concatenation property as S12.3.3, on SQLite and on PostgreSQL under thepostgresmarker.- The Django conformance fixture serves
/conformance/people, and everypaginationcase passes. - The
orderByparameter'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-sqlalchemyusage guide and the Django DRF views guide show a multi-term order over a nullable column. CHANGELOG.mdentries forrn-forge-web,rn-forge-sqlalchemy,rn-forge-djangoandrn-forge-fastapilist 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.