GlideAggregate.addAggregate()

What It Does

The addAggregate() method configures what aggregate calculation ServiceNow should perform when your GlideAggregate query executes. Unlike GlideRecord queries that return individual records, aggregate queries return computed values across groups of records — totals, averages, counts, and extremes.

Internally, ServiceNow translates your aggregate operations into SQL aggregate functions in the database query. When you call addAggregate('SUM', 'quantity'), the platform generates a SUM(quantity) clause. The database performs the calculation and returns the result, which becomes available through the getAggregate() method after the query executes.

The method itself returns void — it's purely a configuration step. The actual aggregate values aren't calculated until you call query() and next(). You can add multiple aggregate operations to a single GlideAggregate object, and ServiceNow will compute them all in one database round-trip.

COUNT operations behave differently depending on whether you specify a field. addAggregate('COUNT') counts all records that match your query conditions, including records where specific fields might be null. addAggregate('COUNT', 'field_name') only counts records where that field has a non-null value.

This method works in conjunction with groupBy() to create grouped aggregates — like total incident count by priority or average resolution time by assignment group. Without groupBy(), your aggregate covers all records matching the query conditions.

When to Use This

Use addAggregate() when you need computed values across multiple records rather than individual record data. This is essential for dashboards, reports, KPI calculations, and any analytics where you're summarizing data. It's dramatically more efficient than iterating through GlideRecord results and calculating aggregates in JavaScript — let the database do what it does best.

Don't use GlideAggregate when you need to access individual record fields beyond your grouping criteria. If you find yourself wanting both aggregate data and detailed record information, you probably need two separate queries — one GlideAggregate for the summary and one GlideRecord for the details. Also avoid GlideAggregate for simple existence checks; GlideRecord.get() or GlideRecord.hasNext() are more appropriate.

Common misuse includes trying to aggregate on reference field display values or computed fields that don't exist in the database. Aggregate operations work on actual database columns, not on values that ServiceNow calculates dynamically. Reference field aggregates work on sys_ids, not display names.

Return Value

The addAggregate() method returns void — it doesn't provide any immediate feedback about success or failure. The method simply registers your aggregate operation with the GlideAggregate object for later execution. Any errors in aggregate type names or field references won't surface until you actually run the query.

The actual aggregate results become available through getAggregate() after calling query() and next(). Those results come back as strings, even for numeric aggregates, so cast them appropriately for mathematical operations.

Platform Behavior & Side Effects

• No business rules fire during aggregate queries — ServiceNow bypasses the entire business rule engine since it's not loading individual records
• ACLs still apply to the underlying table — users can only aggregate data they have read access to
• Database performance is generally excellent for aggregate queries — databases are optimized for this type of operation
• No audit records are created since you're not accessing or modifying individual records
• Results are not cached by default — each query hits the database fresh, which ensures accuracy but may impact performance for frequently-run aggregates
• Cross-scope access works the same as GlideRecord — you can aggregate data from any table your scope has access to
• Domain separation applies if enabled — aggregates respect the user's domain visibility automatically