When to Use addEncodedQuery() and applyEncodedQuery()

Encoded queries are one of the fastest ways to move a filter from a list view into a script.

That is why they are so popular. You build the filter in the UI, copy the breadcrumb, paste the encoded string into GlideRecord, and move on.

The problem is that many scripts start treating encoded queries like magic text. They are not magic. They are compact query logic, and compact query logic deserves the same care as any other code.

1. What addEncodedQuery() is good at

addEncodedQuery() adds a prebuilt filter string to a GlideRecord query.

That makes it especially useful when:

• the logic already exists in a list filter
• the conditions are too awkward to express with many addQuery() and addOrCondition() calls
• you want a compact way to reuse a tested filter

For example:

var gr = new GlideRecord("incident");
gr.addEncodedQuery("active=true^priority=1^ORpriority=2");
gr.query();

That can be easier to read than rebuilding the same filter with several query-condition objects, especially when the condition came from the platform UI in the first place.

2. addQuery() is still the better default for simple filters

Encoded queries are useful, but they are not automatically clearer.

If the filter is simple, plain GlideRecord calls are usually easier to understand:

var gr = new GlideRecord("incident");
gr.addActiveQuery();
gr.addQuery("priority", 1);
gr.query();

That is easier to maintain than:

gr.addEncodedQuery("active=true^priority=1");

So the bias I use is:

• use addQuery() for simple, field-by-field logic
• use addEncodedQuery() when the filter is genuinely complex or copied from the UI

3. Encoded queries are great for copied breadcrumbs

One of the best uses of addEncodedQuery() is reusing a filter you already trust.

Suppose you build the correct incident filter in a list, copy the query, and move it into script:

var gr = new GlideRecord("incident");
gr.addEncodedQuery("active=true^assignment_group=" + groupSysId + "^state!=7");
gr.orderByDesc("sys_updated_on");
gr.query();

That is practical because:

• the filter was easy to validate in the UI first
• the script stays close to the real business filter
• you avoid a long chain of conditions that is harder to compare with the breadcrumb version

This is where encoded queries shine.

4. Do not confuse addEncodedQuery() with applyEncodedQuery()

These two methods sound similar, but they are not for the same job.

addEncodedQuery() is for filtering the records you are about to query.

applyEncodedQuery() is for taking the terms in an encoded query and applying their values to the current GlideRecord.

That means this is a query filter:

var gr = new GlideRecord("incident");
gr.addEncodedQuery("active=true^priority=1");
gr.query();

But this is a record-population pattern:

var incident = new GlideRecord("incident");
incident.initialize();
incident.applyEncodedQuery("category=inquiry^priority=2^short_description=Portal login issue");
incident.insert();

That second example is niche, but it is valid. It is useful when you already have an encoded query that represents field values you want to stamp onto a new record.

If your goal is “fetch rows from the database,” you almost always want addEncodedQuery(), not applyEncodedQuery().

5. The biggest risk is a bad encoded query

This is the part people underestimate.

ServiceNow warns that an incorrectly constructed encoded query can drop the invalid portion and still run the valid remainder. In the worst case, that means you think you are targeting a narrow set of rows, but the platform returns a much broader set.

Bad example:

var gr = new GlideRecord("incident");
gr.addEncodedQuery("activ=true^priority=1");
gr.query();

If activ is not a valid field, you might assume the whole query fails. It may not. You may simply end up running a less restrictive query than intended.

That is why encoded queries deserve extra caution before you follow them with:

• update()
• deleteRecord()
• deleteMultiple()
• any script that changes records in bulk

There is a system property, glide.invalid_query.returns_no_rows, that can reduce the blast radius, but it is not a substitute for validating the query itself.

6. Build encoded queries deliberately

The best habits here are boring, which is good.

• Copy complex filters from a list only after you verify the result set.
• Combine addEncodedQuery() with plain addQuery() when that keeps the script clearer.
• Log getEncodedQuery() during debugging so you know what you actually built.
• Build dynamic fragments from validated values instead of dumping unchecked input into the string.

For example:

var gr = new GlideRecord("task");
gr.addActiveQuery();
gr.addEncodedQuery("priority=1^ORpriority=2");
gr.addQuery("assignment_group", groupSysId);
gr.query();

That is often easier to reason about than forcing every condition into one long encoded string.

7. Readability still matters

Encoded queries save space, but short code is not always clear code.

This:

gr.addEncodedQuery("active=true^stateIN1,2,3^priority=1^ORpriority=2^assignment_group=" + groupSysId);

may be technically fine, but it becomes harder to review once you start mixing multiple business rules into a single string.

If the encoded query is getting hard to parse, that is a signal to split the logic:

• keep the reusable or copied portion encoded
• keep the script-specific conditions explicit

The goal is not to impress future readers with a dense query string. The goal is to let them safely change it later.

8. A simple rule of thumb

When deciding between the three common patterns:

1. Use addQuery() for simple filters you are building by hand.
2. Use addEncodedQuery() for copied or genuinely complex filters.
3. Use applyEncodedQuery() when you want to apply encoded terms as field values on the current record.

That keeps the intent clear.

Final thought

Encoded queries are useful because they let you move fast, especially when the UI already helped you build the right filter.

Just do not let the compact syntax fool you. A small typo inside an encoded string can change the scope of the query much more than you expected.

Use them when they make the script clearer, validate them before bulk actions, and keep applyEncodedQuery() for the cases where you really mean “apply values,” not “run a query.”