GlideAggregate.orderByAggregate()

What It Does

The orderByAggregate() method modifies a GlideAggregate query to sort the grouped results by their calculated aggregate values instead of the grouping field values. This transforms a basic aggregate query into a ranked analysis, enabling you to find the highest, lowest, or most common groups based on their aggregate calculations.

Internally, ServiceNow adds an ORDER BY clause to the generated SQL query that sorts on the aggregate column rather than the grouped column. The method validates that both the aggregate type and field match an existing aggregate function in the query - if they don't match exactly, the ordering silently fails and results appear in database default order.

The method returns void and modifies the query object in place. The ordering takes effect when you call query() and iterate through results. By default, results are ordered in ascending order (lowest aggregate values first) - use orderByDesc() after calling this method to reverse the sort order.

Edge cases include attempting to order by aggregate functions not yet added to the query (silently ignored), using incorrect field names that don't match the aggregate definition (no error, default ordering), and calling the method multiple times (last call wins). The method also interacts unexpectedly with setLimit() - the limit applies after ordering, making it perfect for top-N queries.

This method works alongside addAggregate() (defines what to calculate), groupBy() (defines how to group), and setLimit() (restricts result count). Unlike regular orderBy() which sorts on field values, this method sorts on calculated aggregate results.

When to Use This

Use orderByAggregate() when you need ranked analysis of grouped data: finding assignment groups with the most open incidents, users who submitted the most requests, or categories with the highest average resolution times. This is the correct method for any "top-N" or "bottom-N" analysis where the ranking is based on aggregate calculations rather than alphabetical or chronological ordering.

Avoid this method when you need to sort by the grouping field values themselves - use regular orderBy() instead. Don't use it for simple record queries without aggregates (use GlideRecord), or when you need complex multi-level sorting (GlideAggregate sorting is limited). Common misuse includes trying to order by fields not included in aggregate calculations, or expecting it to work without calling addAggregate() first.

Return Value

Returns void (undefined in JavaScript). The method modifies the GlideAggregate object's internal query structure rather than returning a value. Success or failure cannot be determined from the return value - you'll only discover ordering problems when results appear in unexpected sequence after calling query().

Since there's no return value to check, always verify your aggregate and field parameters match exactly what you passed to addAggregate(). The method fails silently with incorrect parameters, leaving results in database default order (usually by primary key).

Platform Behavior & Side Effects

• No Business Rules, ACLs, or notifications fire - GlideAggregate queries bypass record-level security and workflow mechanisms
• Database writes: none - this is a read-only query modification that only affects SELECT statement generation
• Performance: adds ORDER BY clause to aggregate query, slightly slower than unordered aggregates but much faster than sorting in JavaScript
• Caching: not cached by ServiceNow - each query execution hits the database with fresh aggregate calculation and ordering
• Scope behavior: identical across Business Rules, Script Includes, and Scheduled Jobs - no security context differences
• Memory usage: minimal - ordering happens at database level, not in application memory
• Transaction behavior: runs within current transaction scope but doesn't modify data or affect transaction rollback scenarios