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=dbaix901nyc

{
  "metadata": {
    "powered_by": "arc46.io",
    "git": "squid-0.10.8+24-4af2b54",
    "build": "2025-09-12T09:39:40.935Z",
    "license_max_entities": "Unlimited",
    "license_valid_till": "2050-12-31T23:59:59.000Z",
    "requested_by": "arc46_rest_demo",
    "request_received": "2025-09-14T15:39:25.730Z",
    "config": "cmdb_ci_server_minimal",
    "row_count": 1,
    "provided_filter": "base_name=dbaix901nyc",             <= encodedQuery as provided by caller
    "combined_filter": "base_name=dbaix901nyc"              <= resulting encodedQuery used to retrieve data
  },
  "data": [
    {
      "asset_tag": "P1000182",
      "last_discovered": "2024-07-12T11:21:50Z",
      "name": "dbaix901nyc",                                <= property that matches encodedQuery
      "sys_class_name": "cmdb_ci_unix_server",
      "sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
      "sys_mod_count": 12,
      "sys_updated_on": "2024-07-17T10:54:43Z"
    }
  ],
  ...
}

Field Names and Variable Prefixes​

Squid uses ServiceNow database views to

a) define what data is retrieved and b) aggregate data of multiple tables in a single JSON.

Every table that is incorporated into a ServiceNow database view must have a so-called 'Variable prefix'. By convention all Squid database views use 'base' as the 'Variable prefix' for the base table. (If you want to use existing database views that do not follow this naming convention, the prefix can be changed in any specific configuration.)

The prefixes for any additional joined tables are documented in the view. Predefined configurations document the used prefixes in the documentation of the configuration e.g., cmdb_ci_server. Look for 'encodedQuery prefix'.

Squid removes the database view specific 'Variable prefixes' to present the returned JSON in a more expected format. Instead of base_sys_id we return sys_id.

For ServiceNow to understand a given encodedQuery we have to use the field names defined on the database view that we are querying, i.e. we have to set conditions on base_sys_id instead of sys_id.

A future release will take care of this for you, but we're not quite there yet.

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. Squid has no plausible way of checking for the existence of an index. (This is technically possible, but the performance impact on each and every request does not justify that approach.)

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_nameLIKEdbaix901nyc

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 filter that limit the returned data. Both together are a security feature (TODO add link to corresponding documentation). ^NQ would add a top level OR clause 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=dbaix901nyc^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=dbaix901nyc&encodedQuery=base_asset_tag=P1000182

Last updated on
We track. Ok?