GlideRecord.addEncodedQuery()

addEncodedQuery(query)→ void

intermediateTested on Xanadu

What It Does

The addEncodedQuery() method appends an encoded query string to the current GlideRecord's filter conditions. Encoded queries use ServiceNow's internal query language where conditions are structured as field^operator^value and multiple conditions are joined with '^' characters.

Internally, ServiceNow parses the encoded query string and converts it into the same filter conditions you'd create with addQuery() method calls. The platform validates field names against the target table's schema and converts operators into database-appropriate WHERE clauses when the query executes.

Each call to addEncodedQuery() creates an AND relationship with existing query conditions. Multiple encoded queries stack together, and conditions within a single encoded query string use the logical operators embedded in the string (typically AND, but OR is supported with the '^OR' syntax).

The method handles malformed queries by throwing runtime exceptions during query execution, not during the method call itself. Invalid field names or operators cause the query to fail when query() executes, making debugging more difficult than with explicit addQuery() calls.

This method works identically to addQuery() for building filters but accepts pre-formatted query strings instead of individual field/operator/value parameters. Both methods can be mixed in the same GlideRecord, and both respect the same query ordering and AND logic.

When to Use This

Use addEncodedQuery() when you have query strings copied from the ServiceNow UI (filter breadcrumbs or right-click > Copy query in list views). This is the fastest way to replicate complex user-built filters in server-side scripts without manually parsing each condition into separate addQuery() calls.

Prefer addQuery() for new code where you're building queries programmatically. Explicit field/operator/value parameters are more readable, easier to debug, and provide better IDE support. Reserve encoded queries for situations where the query string comes from user input, saved filters, or UI integrations.

Avoid concatenating user input directly into encoded query strings without validation. This creates injection vulnerabilities where malicious users can manipulate query logic. Always validate or escape user-provided values, or use addQuery() with parameterized values instead.

Return Value

The method returns void and modifies the GlideRecord instance in place. Success or failure cannot be determined from the method call itself since query parsing and validation happen during query execution, not during filter setup.

Invalid encoded query strings throw runtime exceptions when query() executes, not when addEncodedQuery() is called. Wrap query execution in try-catch blocks if you're working with dynamic or user-provided encoded queries.

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

Platform Behavior & Side Effects

No Business Rules, ACLs, or audit records are created by adding query conditions—these fire only during record retrieval and modification
Query parsing happens during execution, not when the encoded query is added, potentially causing delayed error discovery
Performance is identical to equivalent addQuery() calls since both compile to the same database WHERE clauses
Field-level ACLs are evaluated when the query executes, not when query conditions are defined
Multiple encoded queries on the same GlideRecord create AND conditions between each encoded string
No difference in behavior between Business Rules, Script Includes, or Scheduled Jobs—all execute with the same query parsing logic

⚠️

Encoded query syntax errors throw exceptions at query execution time, not when addEncodedQuery() is called, making debugging more difficult than explicit addQuery() calls.

Parameters

Name	Type	Required	Description
query	string	Yes	An encoded query string using ServiceNow's query syntax (field^operator^value). Multiple conditions are separated by '^' characters. Empty strings are ignored but null values throw errors.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Code Examples

Basic usage — copying query from UI filterbasic

// Copy encoded query from incident list filter breadcrumbs
var gr = new GlideRecord('incident');

// Equivalent to: state=1^priority=1^active=true
gr.addEncodedQuery('state=1^priority=1^active=true');
gr.query();

while (gr.next()) {
    gs.info('High priority incident: ' + gr.number + ' - ' + gr.short_description);
}

// Can be mixed with regular addQuery() calls
var gr2 = new GlideRecord('incident');
gr2.addQuery('caller_id', gs.getUserID());
gr2.addEncodedQuery('state=1^priority=1'); // AND with above condition
gr2.query();

gs.info('Found ' + gr2.getRowCount() + ' high priority incidents for current user');

This example shows copying an encoded query directly from the UI filters. The encoded query creates AND conditions between state, priority, and active fields, exactly as they appeared in the filter breadcrumbs.

Intermediate — building dynamic queries from saved filtersintermediate

// Retrieve and apply saved filter conditions from user preferences
var userSysId = gs.getUserID();
var filterQuery = gs.getUser().getPreference('incident.my_saved_filter');

function applyUserFilter(tableName, savedQuery) {
    var gr = new GlideRecord(tableName);
    
    // Always add base security constraints first
    gr.addQuery('active', true);
    gr.addQuery('assigned_to', userSysId);
    
    // Apply saved encoded query if it exists
    if (savedQuery && savedQuery.length > 0) {
        gr.addEncodedQuery(savedQuery);
    }
    
    return gr;
}

var incidents = applyUserFilter('incident', filterQuery);
incidents.query();
gs.info('Applied saved filter, found ' + incidents.getRowCount() + ' records');

This pattern combines security constraints with user-saved encoded queries. Base security conditions are added first as explicit queries, then user preferences are applied as encoded queries for flexibility.

Advanced — the injection vulnerability mistakeadvanced

// WRONG: Direct concatenation allows query injection
function getRecordsByUser(userId) {
    var gr = new GlideRecord('incident');
    // Malicious userId: "12345^active=false^state=7" 
    gr.addEncodedQuery('assigned_to=' + userId); // Injects extra conditions!
    gr.query();
    return gr;
}

// RIGHT: Use addQuery() with parameterized values
function getRecordsByUserSecure(userId) {
    var gr = new GlideRecord('incident');
    gr.addQuery('assigned_to', userId); // Platform handles escaping
    return gr;
}

// ALSO RIGHT: Validate before encoding
function getRecordsByUserValidated(userId) {
    var gr = new GlideRecord('incident');
    if (!GlideStringUtil.isEligibleSysID(userId)) {
        throw new Error('Invalid user ID format');
    }
    gr.addEncodedQuery('assigned_to=' + userId);
    return gr;
}

The wrong approach allows users to inject additional query conditions by manipulating the userId parameter. Always validate input or use parameterized addQuery() calls when dealing with user-provided values.

Gotchas

Empty encoded query strings are silently ignored, but null or undefined parameters throw runtime exceptions.

Syntax errors in encoded queries don't surface until query() executes, making debugging harder than explicit addQuery() calls.

Multiple addEncodedQuery() calls create AND relationships between each encoded string, not OR relationships.

Field names in encoded queries are case-sensitive and must exactly match the table schema or queries will fail at execution time.

User input concatenated directly into encoded queries creates injection vulnerabilities where malicious users can manipulate query logic with '^' characters.

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue