Filtering Query Explanation

The filtering query config item allows you to to build dynamic queries using a JSON structure that mirrors ServiceNow's condition builder.

This approach provides flexibility to create parameterised queries that can be modified at runtime without hardcoding filter conditions.

Basic JSON Structure

All ServiceNow expressions follow this fundamental JSON structure:

{
  "type": "Nary",
  "operators": ["<operator>"],
  "operands": [
    {
      "type": "Field",
      "value": "<field_name>"
    },
    {
      "type": "Constant", 
      "value": "<comparison_value>"
    }
  ]
}

Incremental Processing JSON Structure

This example enables incremental processing from any ServiceNow table with the sys_updated_on field.

{
  "type": "Nary",
  "operators": [
    ">"
  ],
  "operands": [
    {
        "type": "Field",
        "value": "sys_updated_on"
      },
      {
        "type": "Constant",
        "value": "<<ExtractControl>>"
      }
  ]
}

Key Components

• type: Always set to "Nary" for ServiceNow expressions
• operators: Array containing the comparison operator(s)
• operands: Array containing the field and value being compared

Basic Query Examples

Simple Equality Check

This query filters records where the state field equals active

{
  "type": "Nary",
  "operators": ["="],
  "operands": [
    {
      "type": "Field",
      "value": "state"
    },
    {
      "type": "Constant",
      "value": "active"
    }
  ]
}

Numeric Comparison

This query filters records where u_founded is less than 2000

{
  "type": "Nary",
  "operators": ["<"],
  "operands": [
    {
      "type": "Field",
      "value": "u_founded"
    },
    {
      "type": "Constant",
      "value": "2000"
    }
  ]
}

Date Comparison

{
  "type": "Nary",
  "operators": [">="],
  "operands": [
    {
      "type": "Field",
      "value": "sys_created_on"
    },
    {
      "type": "Constant",
      "value": "2023-01-01"
    }
  ]
}

Supported Operators

The condition builder format supports many different operators, exhaustively documented in the official ServiceNow Reference

Some commonly used examples are also included below

Operator	Description	Example Use Case
=	Equals	state = "active"
!=	Not equals	priority != "low"
>	Greater than	number > 1000
>=	Greater than or equal	created >= "2023-01-01"
<	Less than	priority < 3
<=	Less than or equal	updated <= "2023-12-31"
LIKE	Contains substring	description contains "urgent"
NOTLIKE	Does not contain	notes does not contain "resolved"
STARTSWITH	Starts with	number STARTS WITH "INC"
ENDSWITH	Ends with	email ENDS WITH "@company.com"
ISEMPTY	Records where there is no value in field	short description is empty
ISNOTEMPTY	Records where there is any value in field	short description is not empty
IN	Value in list	category IN ["hardware", "software"]
NOT IN	Value not in list	state NOT IN ["closed", "resolved"]

Complex Queries with Multiple Conditions

AND Logic (Multiple Operators)

This creates an AND condition: state = 'active' AND priority >= 2

{
  "type": "Nary",
  "operators": ["=", ">="],
  "operands": [
    {
      "type": "Field",
      "value": "state"
    },
    {
      "type": "Constant",
      "value": "active"
    },
    {
      "type": "Field", 
      "value": "priority"
    },
    {
      "type": "Constant",
      "value": "2"
    }
  ]
}

OR Logic (Nested Structure)

This creates an OR condition: category = 'hardware' OR category = 'software'

{
  "type": "Nary",
  "operators": ["OR"],
  "operands": [
    {
      "type": "Nary",
      "operators": ["="],
      "operands": [
        {
          "type": "Field",
          "value": "category"
        },
        {
          "type": "Constant",
          "value": "hardware"
        }
      ]
    },
    {
      "type": "Nary", 
      "operators": ["="],
      "operands": [
        {
          "type": "Field",
          "value": "category"
        },
        {
          "type": "Constant",
          "value": "software"
        }
      ]
    }
  ]
}