GlideRecord.orderBy()

What It Does

The orderBy() method configures the SQL ORDER BY clause for a GlideRecord query. When you call this method, ServiceNow stores the sort instruction internally and applies it when the query executes via query(), queryNoDomain(), or other query methods. The sort occurs at the database level, making it efficient for large datasets.

ServiceNow translates your orderBy() call into the appropriate SQL syntax based on the underlying database (MySQL, Oracle, SQL Server, etc.). The platform handles null value positioning, character encoding, and locale-specific sorting rules automatically. For reference fields, you can dot-walk to sort by fields on the referenced table, which creates the necessary SQL joins.

The method returns void and modifies the GlideRecord object state internally. Multiple calls to orderBy() are cumulative, creating a multi-level sort where the first call becomes the primary sort, the second call the secondary sort, and so on. This mirrors SQL's ORDER BY col1, col2, col3 syntax.

Edge cases include sorting by choice fields (sorts by the underlying value, not display value), date/time fields (handles timezone conversion), and encrypted fields (may not sort as expected). The method validates field names at runtime, so invalid fields cause the query to fail with a database error rather than failing silently.

Related methods include orderByDesc() for descending sort and chooseWindow() for pagination. Unlike client-side GlideList.sort(), orderBy() sorts at the database level before records are returned to the application server.

When to Use This

Use orderBy() when you need predictable, consistent ordering for reports, data exports, or any processing where record sequence matters. This is essential for batch processing scripts, scheduled jobs that process records in chunks, and Business Rules that depend on processing order. Database-level sorting is always more efficient than application-level sorting for large datasets.

For simple single-record lookups or when you're only checking if records exist, skip orderBy() to improve performance. Use orderByDesc() instead when you need the most recent records first, such as finding the latest approval or newest incident. Avoid application-level sorting with JavaScript arrays when working with more than a few hundred records—let the database do the heavy lifting.

Return Value

The orderBy() method returns void—it doesn't return any value you can use. The method modifies the internal state of the GlideRecord object to store the sort specification. You chain other GlideRecord methods after calling orderBy(), but you're working with the same GlideRecord instance, not a return value.

When the field name is invalid or the table doesn't exist, orderBy() doesn't immediately throw an error. The error surfaces later when you execute the query, resulting in a database exception. This deferred validation means you must test your queries thoroughly, especially when building dynamic field names from user input or configuration data.

Platform Behavior & Side Effects

• No Business Rules, ACLs, or notifications fire—orderBy() only configures query behavior
• Nothing writes to the database—this is purely a query configuration method
• Performance impact depends on indexes—sorting by unindexed fields can slow large queries significantly
• Works identically across all server-side contexts—Business Rules, Script Includes, Scheduled Jobs, and Fix Scripts
• Sort specifications are not cached—each GlideRecord instance maintains its own sort configuration
• Dot-walking in sort fields creates SQL joins, which can impact query performance on large tables
• Domain separation applies normally—sorted results still respect domain visibility rules