GlideRecord.addNullQuery()

What It Does

The addNullQuery() method adds an IS NULL condition to your GlideRecord query, which matches records where the specified field contains no value. This includes fields that are explicitly set to null, empty strings, and fields that have never been populated. The method is a convenience wrapper that internally translates to addQuery(fieldName, 'ISEMPTY', '').

ServiceNow's database layer treats null values and empty strings identically for query purposes. When you call addNullQuery(), the platform generates a WHERE clause that checks for both NULL and empty string conditions in the underlying database query. This unified approach eliminates the need to write separate conditions for different types of 'empty' values.

The method returns a GlideQueryCondition object that represents the null check condition within your query's condition tree. This return value allows you to chain additional operators like addOrCondition() to build complex logical expressions. The GlideQueryCondition is automatically integrated into the parent GlideRecord's query structure, so you don't need to explicitly attach it.

Reference fields behave predictably with addNullQuery() – the method checks whether the reference field contains a sys_id value, not whether the referenced record exists. A reference field with a sys_id pointing to a deleted record will not match a null query. Choice fields are treated as strings, so only fields with no selected value will match the null condition.

Unlike addQuery() with a value parameter, addNullQuery() cannot be negated by changing an operator parameter. To find non-null values, use addNotNullQuery() instead. Both methods work identically across all field types, including encrypted fields and journal fields.

When to Use This

Use addNullQuery() when you need to find records with missing or empty field values as part of data validation, cleanup scripts, or business logic that depends on incomplete records. Common scenarios include finding incidents without assigned groups, users missing email addresses, or configuration items lacking crucial attributes. This method is particularly useful in scheduled jobs that identify and process incomplete data.

Avoid using addNullQuery() when you need to check for specific default values or when empty strings should be treated differently from null values. If your business logic distinguishes between 'never set' and 'explicitly cleared', use addQuery() with specific value comparisons instead. For performance-critical queries on large tables, consider whether adding a compound index on the null-checked field and other query conditions would improve execution time.

Never chain addNullQuery() and addNotNullQuery() on the same field without an OR condition – this creates a logical impossibility that returns zero records. The common mistake is forgetting that multiple conditions on the same GlideRecord are ANDed together by default.

Return Value

The method returns a GlideQueryCondition object that represents the IS NULL condition within your query structure. This object provides methods for chaining additional conditions, such as addOrCondition(), addCondition(), and other query builders. The returned GlideQueryCondition is already integrated into the parent GlideRecord's query, so calling query() will include the null check automatically.

The method never returns null or undefined, even when called with invalid field names. ServiceNow will generate the query condition object regardless of field validity, but the resulting database query may return unexpected results or fail silently if the field doesn't exist. Always validate field names against the table dictionary when building dynamic queries.

Platform Behavior & Side Effects

• No database writes occur – this method only modifies the query condition tree in memory
• Business Rules do not fire when adding query conditions, only when executing query() or accessing records
• ACL checks apply to the target field during query execution, potentially filtering results based on user permissions
• Query performance depends on database indexing – null checks on unindexed fields can be slow on large tables
• Domain separation applies during query execution if the target table is domain-separated
• The method works identically in Business Rules, Script Includes, and Scheduled Jobs with no behavioral differences