GlideAggregate.groupBy()

What It Does

The groupBy() method modifies a GlideAggregate query to group results by the specified field. When the query executes, ServiceNow generates SQL with a GROUP BY clause, causing aggregate functions like COUNT, SUM, and AVG to calculate values for each distinct value in the grouping field rather than across the entire result set.

Internally, ServiceNow builds a SQL query where the fieldName becomes part of both the SELECT clause and the GROUP BY clause. The method validates that the field exists on the target table and handles reference field notation like 'assignment_group.name' by performing the appropriate table joins. Multiple calls to groupBy() on the same GlideAggregate instance will group by multiple fields simultaneously.

The method returns void and must be called before query() to take effect. Once you iterate through results with next(), each record represents one group, and you access the grouping field value using getValue() and aggregate calculations using getAggregate().

Edge cases include grouping by fields that contain null values, which creates a separate group for null entries. Choice fields group by the underlying database value, not the display label. Date/datetime fields group by the exact timestamp unless you use database functions in the field name. Reference fields can be grouped by sys_id or by drilling into referenced table fields.

The method works closely with addAggregate(), addHaving(), and orderByAggregate(). Without groupBy(), aggregate functions calculate across all records matching your encoded query. With groupBy(), they calculate per group, enabling breakdown reporting and analysis.

When to Use This

Use groupBy() when you need aggregate calculations broken down by categories rather than totals across all records. Classic use cases include incident counts by assignment group, request item totals by department, or change success rates by type. Any time you're building reports, dashboards, or metrics that need "group by" behavior, this is your method.

Don't use groupBy() when you need individual record details or when a simple aggregate across all matching records suffices. If you're just getting a total count or sum without categorization, use addAggregate() alone. For individual record processing, use GlideRecord instead. Avoid the common mistake of using GlideRecord with client-side JavaScript arrays to manually group results—this is inefficient and doesn't scale.

Return Value

This method returns void and modifies the GlideAggregate object's internal query structure. The method never fails or throws errors for invalid field names—ServiceNow will generate a SQL error at query execution time if the field doesn't exist. There's no return value to check for success or failure.

The effect of calling this method becomes apparent when you iterate through query results. Each call to next() returns one group rather than one record, and you use getValue(fieldName) to get the grouping value and getAggregate() to get the calculated aggregates for that group.

Platform Behavior & Side Effects

• No Business Rules, ACLs, or notifications fire—GlideAggregate queries bypass all record-level security and business logic
• Nothing gets written to the database—this is a read-only query modification operation
• Performance is generally good as the database handles grouping efficiently, but complex reference field grouping can require expensive joins
• Results are not cached—each query execution hits the database with fresh SQL
• Domain separation applies at the SQL level—you only see groups from records in accessible domains
• Behavior is identical across all server-side execution contexts—Business Rules, Script Includes, and Scheduled Jobs all work the same way
• Field-level ACLs and table ACLs are respected—inaccessible fields return empty values and restricted tables return no results