GlideAggregate.addQuery()

What It Does

The addQuery() method adds a filter condition to your GlideAggregate query that gets applied before any aggregation occurs. ServiceNow builds a WHERE clause from all your addQuery() calls and executes them against the database first, then performs the aggregation functions on the filtered result set.

Internally, ServiceNow converts your GlideAggregate into a SQL query with GROUP BY clauses and aggregate functions. The addQuery() conditions become WHERE clauses that filter the base records before grouping occurs. This is crucial for performance because filtering happens at the database level before expensive aggregation operations.

The method returns a GlideQueryCondition object that represents the specific condition you just added. You can chain additional methods like addOrCondition() on this return value to build complex logical expressions. The return value is never null, even for invalid field names or malformed queries.

Edge cases behave identically to GlideRecord: querying non-existent fields doesn't throw errors but returns no results, and reference field queries automatically perform joins. Date fields accept relative operators like javascript:gs.daysAgoStart(30) and encoded query strings work in the value parameter.

Unlike addHaving() which filters after aggregation, addQuery() filters the base records before grouping occurs. This makes it the correct choice for filtering on regular table fields rather than computed aggregate values.

When to Use This

Use addQuery() when you need to filter the base records before aggregation, such as counting incidents from the last 30 days or averaging priority scores for active records only. This is your primary filtering mechanism and should handle 90% of your GlideAggregate filtering needs.

Use addHaving() instead when you need to filter based on the aggregated results themselves, like finding assignees who have more than 10 open incidents. Use addEncodedQuery() when you already have a complex encoded query string from a list filter or saved query.

Avoid the common mistake of trying to filter on aggregate functions with addQuery() — you can't use addQuery('COUNT', '> 5') because COUNT isn't a field in your base table, it's a computed value that only exists after aggregation.

Return Value

Returns a GlideQueryCondition object that represents the specific condition you added. This object supports method chaining for complex logical operations like addOrCondition() and can be stored in a variable for later manipulation.

The method never returns null or throws exceptions, even for invalid field names or malformed queries. Invalid conditions simply result in no matching records when the query executes. You can safely chain methods on the return value without null checking.

Platform Behavior & Side Effects

• No Business Rules, ACLs, or notifications fire because this method only builds query conditions without touching data
• Nothing gets written to the database until you call query() — this method only modifies the query object in memory
• Performance is excellent because conditions are pushed down to the database WHERE clause, filtering before expensive aggregation operations
• ACL enforcement still applies when the query executes, automatically filtering out records the current user can't access
• Reference field queries automatically create database joins, which can impact performance on large tables with complex reference chains
• Behavior is identical across all server-side contexts — Business Rules, Script Includes, and Scheduled Jobs all execute the same database query
• Query conditions are not cached — each execution builds and runs a fresh SQL query against current data