Wren Core 0.8 makes top-N cube queries deterministic—if the caller passes the sort

Wren Core Python 0.8.0 adds explicit ordering to cube queries, closing a small but consequential gap for questions such as “top five merchants by spend.” The release can now compile that request into native SQL with an ORDER BY before LIMIT, instead of leaving the selected rows dependent on a database’s unspecified output order.

What the new query shape does

The new orderBy field accepts a list of selected cube members and lowercase asc or desc directions. Wren’s own regression example selects merchant and net spend, then produces ORDER BY 2 DESC, 1 ASC LIMIT 5: spend establishes the ranking and merchant provides a deterministic tie-break.

The compiler validates the sort before generating SQL. It rejects a member that is not already selected, the same member listed twice, unsupported directions, and malformed fields. It uses output-column ordinals rather than wrapping the cube query in another SQL layer. That keeps the generated statement compact while limiting the sort expression to semantic-layer members the query already exposed.

Compatibility is deliberate. If orderBy is missing or empty, Wren preserves its previous behavior: a time-dimension query remains ordered by its first time dimension, while other cube queries do not gain an implicit sort.

Why agents need the explicit contract

A LIMIT 5 clause answers “five rows,” not “the top five.” Without ordering, repeated executions can return a different subset as physical plans, parallelism or source data change. The problem is especially easy to hide behind a natural-language interface because a fluent answer can present an arbitrary subset as a ranking.

Multi-column ordering helps, but the caller must use it correctly. For a stable leaderboard, the requested measure should come first and a consistently valued dimension should break ties. For offset pagination, every page should use the same complete ordering; the release does not make an unordered offset deterministic.

There is also an integration boundary to test. Version 0.8.0 is a Wren Core Python release, and the merged patch changes the Rust cube compiler, its Python binding tests and public core types. It does not by itself prove that every Wren AI UI, CLI or agent tool has begun sending orderBy. Teams upgrading should capture the cube-query JSON at the calling layer, inspect the generated SQL, and verify that ranking prompts produce the expected ordered statement.

The practical acceptance test is straightforward: run a top-N prompt with tied measure values, confirm the request contains both the primary sort and tie-breaker, and rerun it against the same snapshot. If the same ordered rows return each time, the feature is connected end to end—not merely installed in the compiler.