GlideRecord.addQuery(): Syntax & Examples

What It Does

The addQuery method builds WHERE conditions for GlideRecord database queries. It accepts a field name and value, then constructs the appropriate SQL WHERE clause internally. The method returns a GlideQueryCondition object that represents this specific condition within the larger query structure.

When ServiceNow processes an addQuery call, it doesn't execute the query immediately. Instead, it stores the condition in memory and applies it when query() executes. Multiple addQuery calls create AND conditions by default, meaning all conditions must be true for a record to match.

The returned GlideQueryCondition object enables method chaining with addOrCondition() to create complex logical expressions. This object maintains a reference to the specific condition within the query, allowing you to extend it with OR logic after the initial creation. The GlideQueryCondition never returns null or undefined - it always returns a valid condition object.

Field names support dot-walking syntax for related table queries, such as caller_id.department. The method validates field existence at query execution time, not when addQuery is called. Invalid field names cause the query to return zero results rather than throwing errors, which can create subtle bugs in production code.

The method integrates with other GlideRecord query methods like addEncodedQuery() and addNullQuery(). All query conditions combine with AND logic unless explicitly modified with OR conditions. This differs from addEncodedQuery, which accepts complete encoded query strings rather than individual field-value pairs.

When to Use This

Use addQuery when you need to filter records based on specific field values and want the flexibility to add OR conditions later. This method excels when building dynamic queries where conditions depend on runtime variables or user input. The returned GlideQueryCondition object makes it the preferred choice for complex conditional logic that might require OR branching.

For simple queries without OR conditions, consider addEncodedQuery() instead. It accepts complete query strings and often results in more readable code for static conditions. Use addNullQuery() or addNotNullQuery() for null checks rather than addQuery('field', ''), which doesn't handle null values correctly.

Avoid using addQuery with hardcoded encoded operators in the value parameter like addQuery('number', 'STARTSWITH123'). This pattern reduces readability and makes the code harder to maintain. The three-parameter version addQuery('number', 'STARTSWITH', '123') separates concerns more clearly.

Return Value

Returns a GlideQueryCondition object that represents the specific WHERE condition added to the query. This object provides methods like addOrCondition() for extending the condition with OR logic. The GlideQueryCondition maintains internal references to both the parent GlideRecord and the specific condition data, enabling method chaining and condition modification.

The method never returns null or throws exceptions for invalid parameters during the addQuery call itself. Invalid field names or malformed values only surface as problems during query execution, when the query returns zero results or unexpected data. This deferred validation means you should test queries thoroughly, especially when using dynamic field names or user-provided values.

Platform Behavior & Side Effects

• No database interaction occurs during the method call - conditions are stored in memory until query() executes
• ACL enforcement happens during query execution, not when adding conditions - secure fields may filter results unexpectedly
• Performance scales with query complexity - multiple addQuery calls create longer WHERE clauses but minimal memory overhead
• Field validation occurs at execution time only - invalid field names cause silent query failures rather than exceptions
• Before query Business Rules can modify conditions after addQuery but before query execution
• Domain separation automatically applies to queries in scoped applications - conditions may return fewer results than expected
• Query caching is not affected by individual addQuery calls - caching decisions happen at the complete query level