Skip to main content

encodedQuery Reference

ServiceNow has the concept of 'encodedQueries'.

See ServiceNow: 'Encoded query strings' for details on how to structure a query. See ServiceNow: 'Operators available for filters and queries' for details on available operators for encodedQueries.

Usage​

Using encodedQueries in Squid is as simple as defining a query parameter encodedQuery with the encodedQuery as value.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=web-prod-zurich-01

Response
{
  "metadata": {
    ...,
    "config": "cmdb_ci_server_minimal",
    "row_count": 1,
    ...
  },
  "data": [
    {
      "asset_tag": "SRV-003",
      "name": "web-prod-zurich-01",                          <= matches encodedQuery
      "sys_class_name": "cmdb_ci_server",
      "sys_id": "da9b0e66ebf67254f0a4fe7acad0cdf3",
      "sys_mod_count": 2,
      "sys_updated_on": "2026-02-17T15:09:32Z"
    }
  ],
  ...
}

Field Names and Prefixes​

Field names in encodedQueries use a base_ prefix for the primary table — for example, base_name instead of name, base_sys_id instead of sys_id. Squid removes these prefixes from the returned JSON, but they are required in encodedQueries.

Additional joined tables may use different prefixes. Predefined configurations document the required prefixes — see e.g. cmdb_ci_server (look for "encodedQuery prefix").

A future release will handle prefix translation automatically.

Operator Tiers​

Squid categorizes encodedQuery operators into three tiers based on their performance and security characteristics:

EncodedQuery Operator TiersThis diagram shows the three-tier categorization of encodedQuery operators in Squid, helping developers understand which operators they can use and any restrictions that apply. TIER 1 - ALLOWED (Green, top): These operators have no restrictions and can be used in any encodedQuery. Operators: = (equals), != (not equals), IN, NOT IN, STARTSWITH, ISEMPTY, ISNOTEMPTY, EMPTYSTRING, less than/greater than comparisons, BETWEEN, SAMEAS, NSAMEAS, field comparisons (GT_FIELD, LT_FIELD, etc.), RELATIVEGT, RELATIVELT, VALCHANGES, CHANGESFROM, CHANGESTO, DYNAMIC, RLQUERY, SUBQUERY, JOIN, ^ (AND), ^OR, and dot-walking. These are considered safe for general use with indexed fields. TIER 2 - RESTRICTED (Orange, middle): These operators are blocked by default but can be enabled per-configuration by setting "Restrict Encoded Query" to false. They are restricted due to performance risk - they typically cause full table scans with text search operations. Operators: % (ENDSWITH), * (LIKE/CONTAINS), !* (NOT LIKE), ORDERBY, TEXTQUERY, javascript. Rationale: These operations can severely impact ServiceNow instance performance, especially on large tables or non-indexed fields. TIER 3 - FORBIDDEN (Red, bottom): These operators are always rejected regardless of configuration settings, due to security risks. Operators: ^NQ (New Query / top-level OR). Rationale: ^NQ adds a top-level OR clause that could circumvent view filters and role-based restrictions configured to limit data access, creating a security vulnerability. Usage guidance: Start with ALLOWED operators. If RESTRICTED operators are needed, evaluate the performance impact and create a dedicated configuration with restrictions disabled. FORBIDDEN operators cannot be used under any circumstances.ALLOWEDNo restrictions= != IN NOT IN STARTSWITH ISEMPTY ISNOTEMPTY< <= >= > BETWEEN SAMEAS DYNAMIC ^ ^ORRLQUERY SUBQUERY JOIN . (dot-walking)RESTRICTEDConfig must allow% ENDSWITH * LIKE CONTAINS !* NOT LIKEORDERBY 123TEXTQUERY321 javascriptPerformance risk: may cause full table scansFORBIDDENAlways rejected^NQSecurity risk: circumvents view filters and role restrictions

Supported Operators​

  • ^ / ^OR (AND/OR)
  • =, !=
  • STARTSWITH
  • ISEMPTY / ISNOTEMPTY
  • EMPTYSTRING
  • IN / NOT IN
  • < / <= / >= / > / BETWEEN / MORETHAN / LESSTHAN
  • SAMEAS / NSAMEAS
  • GT_FIELD / GT_OR_EQUALS_FIELD / LT_FIELD / LT_OR_EQUALS_FIELD
  • RELATIVEGT / RELATIVELT
  • VALCHANGES / CHANGESFROM / CHANGESTO
  • DYNAMIC
  • RLQUERY / ENDRLQUERY / SUBQUERY / ENDSUBQUERY / JOIN
  • . (dot walking)

As always with database queries, handle with care. The above operators will cause full table scans if the queried fields are not indexed.

Restricted Operators​

Squid is built to deliver large amounts of data in the most performant way possible without impacting your ServiceNow instance. We therefore prevent encodedQueries from executing operations that have the potential of having a noticeable impact on your instance. Anything that would cause a full table scan with text search, order by operations etc. are by default rejected.

As the performance of database queries always depends on the exact query and the presence of indexes our categorizing of operators into critical (restricted) and non-critical (unrestricted) can only be a best effort.

For you to better understand why we are restricting at all we have included the following anecdotal query durations:

Querying cmdb_ci with 1.1 million entries. (These are just anecdotal values to give an impression of what we're talking about. This is NOT a full-fledged performance evaluation. Measurement after 5 warmup queries.)

FieldSTARTSWITHLIKEENDSWITHORDERBY
name - indexed2ms1900ms1900ms48ms
environment - not indexed3500ms3500ms3500ms4700ms

Restricting encoded queries in this way might sound heavy-handed, but in most use cases the caller of Squid is coming from a peripheral system that has little to nothing to do with ServiceNow other than that it needs data. The caller will probably neither know nor notice any negative impact he or she is causing.

We however recognize that there may be valid use cases when these operators are necessary and useful. Configurations therefore have a property Restrict Encoded Query that is set to true on all predefined configurations. If this property is set to true the following operators are NOT allowed. If you wish to allow these operators, create a new configuration and set the Restrict Encoded Query to false.

  • % / ENDSWITH
  • * / LIKE / CONTAINS
  • !* / NOT LIKE
  • javascript (Anything that requires javascript is restricted)
  • ORDERBY
  • 123TEXTQUERY321 / 123TEXTINDEXGROUP321

Unless the requested configuration explicitly allows the use of restricted operators, including any of the restricted operators in an encodedQuery is considered an error condition and the request is rejected.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=web-prod-zurich-01

warning

Squid reserves the right to expand the above-mentioned list of restricted encoded query operators at any point in time.

ServiceNow may implement new encoded query operators or undocumented operators may come to our attention. If considered potentially performance critical, these will be added to the above list at our discretion. Please check the release notes for any changes.

Forbidden Operators​

  • ^NQ — Squid allows configurations to be restricted by the role of the caller and configurations to define view filters that limit the returned data. Both together are a security feature — see Query Security for the full threat model. ^NQ adds a top-level OR clause (New Query — see ServiceNow KB0564887 and Operators available for filters and queries) to any query, allowing a caller to circumvent any set restrictions.

Including a forbidden operator in an encodedQuery is considered an error condition and the request is rejected.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=web-prod-zurich-01^NQbase_name=somethingelse

Using Restricted Operators in view_filter​

Configurations have a property called view_filter. This allows a Squid administrator to add an encodedQuery to the configuration. This encodedQuery is NOT restricted in any way as it is defined by a Squid administrator.

Time/Date Values​

Time/Date values are a difficult topic in a ServiceNow context. ServiceNow will accept nonsense Time/Date values without throwing any kind of error and just make a best effort. This will give you the impression of your query being correct until you notice that your results do not match what you were expecting.

The following is based on trial and error:

encodedQuery=base_sys_updated_on>2024-04-22 23:00:00 will be read as '2024-04-22 23:00:00 UTC' as will

encodedQuery=base_sys_updated_on>2024-04-22T23:00:01 encodedQuery=base_sys_updated_on>2024-04-22T23:00:01Z encodedQuery=base_sys_updated_on>2024-04-22T23:00:01nonsense(!)

warning

encodedQuery=base_sys_updated_on>2024-04-22x23:00:01 will be accepted as valid encodedQuery, but ServiceNow will only interpret the first part, i.e. '2024-04-22' resulting in a query value of '2024-04-22 00:00:00 UTC'.

Please be sure to check any encodedQueries that use Time/Date values.

Query Parameter Format​

Squid will accept encoded queries as

encodedQuery=yourEncodedQuery

Multiple values are considered an error condition.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=web-prod-zurich-01&encodedQuery=base_asset_tag=SRV-003

Last updated on
We track. Ok?