Encoded query strings

An encoded query string represents a complex filter on a list of records.

Use encoded query strings to include a filter as part of a URL parameter, such as the sysparm_query URL parameter, or as a reference qualifier to restrict the data that is selectable for a reference field.

You can create encoded query strings manually or copy them from list filters.

Table 1. Encoded query string examples
Title Example
Referring to Boolean or string values

To create a query string on Boolean fields, use this syntax: field=true or field=false. For example, to return only active records in a table, use:

active=true

To create a query string with a field that has a specific string value, use this syntax: field=value. For example, to return incident records where the category is network, use:

category=network
Referring to reference fields

To create a query string that refers to a reference field in another table, use this syntax: field_in_referenced_table=value. For example, to return users with the itil role in the Assigned to reference field on the Incident form, use:

roles=itil
Referring to choice list values

To create a query string that refers to a choice list option, use the value of the choice list, not the label, with this syntax: choice list field=value. For example, to return configuration items (CIs) with the status Installed, which has a value of 1 in the choice list, use:

install_status=1

See Values to associate with choice labels for scripting to find the options for the values.

Using multiple conditions

To use two conditions joined by an AND operator, use the carat ^ symbol in this syntax: field1=value1^field2=value2. For example, to return all active users with the "itil" role, use:

active=true^roles=itil

To use two conditions joined by an OR operator, use the carat symbol with OR with this syntax: field1=value1^ORfield1=value2. For example, to return all users with either the "itil" or "admin" roles, use:

roles=itil^ORroles=admin

To add multiple conditions where one condition is a JavaScript function, use this syntax: javascript:'field=value^' + function(). The function must return a string that can be concatenated with the first string to produce a valid query string. For example, to return all active users and meet the conditions of the getGroupQualifier() function, use:

javascript:'active=true^' + getGroupQualifier()
Listing values in order

To sort data by a specific field, use the ORDERBY condition with the following syntax: field1=value^ORDERBYfield2.

For example, to return the days of the week in order from the Day of the Week [sys_cal_unit] table, use:

unit_name=day^ORDERBYvalue

In the Day of the Week table, unit_name is the field that specifies day, week, or month, and value is a numerical value for each day from 1 (Monday) to 7 (Sunday). The query string returns a list of the days of the week in order from the lowest value, which represents Monday, to the largest value, which represents Sunday.

Note: Reference qualifiers do not support the ORDERBY condition. In reference qualifiers, you can sort the reference lookup list by using standard list controls. To specify the order of an auto-complete list for a reference field, use the ref_ac_order_by dictionary attribute.
Including a related list query

At the end of the query statement, enclose the related list information with ^RLQUERY and ^ENDRLQUERY and the quantity. For example, in a query on the Problem table that includes problems with at least one related incident, use:

^RLQUERYincident.problem_id,>=1^ENDRLQUERY

You can also specify conditions on the related table. For example, to include the condition that at least one of the related incidents is critical priority, use:

^RLQUERYincident.problem_id,>=1^priority=1^ENDRLQUERY
Note: Related list queries must be enabled in System PropertiesList v3. Select the Allow related list query conditions to be added through the filter check box to enable it. You can build a related list query for a list that uses List v2, however, the filter conditions cannot be modified until you removed the related list condition in the breadcrumb.