Skip to main content

Native Query Filters

James Herring
Updated

Native Query Filters

Native query filters pass a raw query string directly to the source system's API without modification. This gives you access to the full power of each system's native query language.

When to Use Native Filters

Use native filters when:

  • The standard filter builder can't express your query
  • You need system-specific features (JavaScript expressions in ServiceNow, JQL functions in Jira)
  • You have a pre-built query from the source system you want to reuse
  • You need maximum query performance and want to hand-optimize the query

Use standard filters when:

  • Your conditions are straightforward (field comparisons, AND/OR logic)
  • You want a portable filter that works across different source types
  • You want PB to validate the filter before execution
  • You prefer a visual filter builder over writing raw query strings

ServiceNow Encoded Queries

ServiceNow uses an encoded query format where conditions are joined with ^ (AND) and ^OR (OR).

Basic Examples

active=true^priority<=2

Extracts active records with priority 1 or 2.

state=1^ORstate=2^ORstate=3

Extracts records in state 1, 2, or 3.

active=true^short_descriptionLIKEnetwork^category=hardware

Extracts active hardware records where the short description contains "network".

Advanced Examples

assigned_to=javascript:gs.getUserID()

Extracts records assigned to the currently authenticated user.

sys_created_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()

Extracts records created today.

active=true^priority<=2^NQactive=true^category=production

Uses ^NQ (New Query) to create a UNION-style query — records that are either high priority OR in the production category.

Tips

  • Build in ServiceNow first: Create your filter in ServiceNow's list view, then copy the encoded query from the breadcrumb or URL parameter (sysparm_query=...)
  • Test before migrating: Verify the query returns the expected results in ServiceNow before using it in PB
  • Encode special characters: Values with special characters may need encoding

Jira JQL (Jira Query Language)

Jira uses JQL for filtering issues.

Basic Examples

project = "MYPROJ" AND status = "Open"

Extracts open issues from the MYPROJ project.

priority in ("High", "Highest") AND assignee is not EMPTY

Extracts high-priority assigned issues.

Advanced Examples

assignee = currentUser() AND updated >= -30d

Issues assigned to the authenticated user, updated in the last 30 days. Uses JQL's currentUser() function and relative date syntax.

project = "MYPROJ" AND sprint in openSprints() AND status != "Done"

Issues in open sprints that aren't done. Uses JQL's openSprints() function.

labels in ("migration", "data-cleanup") AND created >= "2024-01-01" ORDER BY priority DESC

Labelled issues created since 2024, ordered by priority.

Tips

  • Test in Jira first: Use Jira's advanced search to validate your JQL before using it in PB
  • JQL functions: Functions such as currentUser(), openSprints(), and startOfMonth() are available only in native mode.
  • Quoting: Use double quotes for string values in JQL

Database SQL WHERE Clauses

For database connections, native filters map to SQL WHERE clauses.

Examples

status = 'active' AND created_at > '2024-01-01'

Standard SQL WHERE clause.

department_id IN (SELECT id FROM departments WHERE region = 'EMEA')

Subquery filtering — not possible with standard filters.

name LIKE 'Smith%' AND email IS NOT NULL

SQL LIKE pattern matching.

Notes

  • PB sanitises inputs to prevent SQL injection, but always be careful when constructing queries from dynamic values
  • SQL syntax varies between database systems (MySQL, PostgreSQL, Oracle, SQL Server) — write queries appropriate for your source database

Pass-Through Behaviour

When you use a native filter, Precision Bridge:

  1. Evaluates the query string, substituting any procedure variables or formula expressions it contains (when the formula toggle is enabled on the value)
  2. Sends the resulting string directly to the source system's API
  3. Returns whatever records the source system returns

PB does not validate, modify, or optimise the query itself. Syntax errors will be reported by the source system at runtime, not during configuration.

Note on variables: Variable substitution still happens for native queries when the formula toggle is on. For example, you can write assigned_to=javascript:gs.getUserID()^sys_created_on>{cutoff_date} and PB will substitute the cutoff_date variable before sending the query. If you want a truly literal pass-through, leave the formula toggle off so the string is sent as-is.

Limitations

  • No validation: PB cannot check native query syntax — errors appear only at execution time
  • Not portable: A ServiceNow encoded query won't work with a database connection
  • No visual builder: Native queries must be written manually as text
  • Variable substitution: Variable references in native queries may need to use system-specific syntax

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk