Basic ascending or descending sorting
Sort records by newest or oldest timestamps, names, IDs, or other columns.
Drizzle ORM · Module
.orderBy
.orderBy() controls result ordering in Drizzle's core query builder. Relational queries also support ordering objects, callbacks, and custom SQL expressions.
How it works
In Drizzle's core query builder, call .orderBy() after selecting the source rows and optionally filtering them. Pass column expressions such as asc(column) or desc(column); for ordering features not directly represented by the API, pass an sql expression instead.
Syntax
query.orderBy(...columns)Parameters
| Name | Type | Description |
|---|---|---|
...columns | SQL.Asc | SQL.Desc | SQL | column ordering expressions | One or more column ordering expressions, such as asc(column), desc(column), or a custom sql expression; relational-query forms may also use an ordering object or callback. |
Returns
A query builder configured with an SQL ORDER BY clause; executing it returns rows in the specified order.
Key points
- Relational query builders provide a dedicated ordering API.
- Relational queries support the core ordering API or an
order byoperator available through the callback. - Use a custom SQL template when the built-in ordering expressions do not cover the required behavior.
- An object form can specify ascending order for a relational-query field.
Common mistakes
- In relational queries, use the callback's table argument when referencing columns; directly using the imported table object is invalid in that context.
- Multiple ordering clauses are retained in insertion order, so place the primary sort before secondary tie-breakers.
Example: Order selected rows descending
import { desc, eq } from 'drizzle-orm';
import { db } from './db';
import { posts } from './schema';
const rows = await db
.select()
.from(posts)
.where(eq(posts.authorId, 1))
.orderBy(desc(posts.createdAt));Fetches matching posts with the newest records first.
When to use it
Custom SQL ordering
Add a database-specific ordering expression such as NULL placement.
Multi-column ordering
Define primary and secondary sorting for stable results.
Nested relational ordering
Apply independent ordering to parent and nested relational results.
Interview questions
QHow do you sort rows with Drizzle's core query builder?
Use .orderBy() with ordering expressions such as asc(column) or desc(column) in the core query builder. The documentation also shows that a custom sql expression can be supplied when more specific ordering behavior is needed.
Follow-up: How would you express NULL ordering? Pass a custom SQL expression, for example sql\${users.id} desc nulls first\.
QHow does orderBy work in relational queries?
In relational queries, orderBy can use an object such as { id: "asc" }. It can also use a callback, whose table argument represents the current query scope.
Follow-up: Why is the callback argument required in nested queries? It exposes the aliased table for that scope, enabling correct SQL generation.
QWhat happens when several ordering clauses are supplied?
Multiple orderBy clauses on the same table appear in the generated query in the same order they were added. This lets you define deterministic primary and secondary sorting.
Follow-up: How can you add ordering behavior not directly provided by Drizzle? Use the sql template in the ordering expression.
Related
ascdescsqlwherefindMany