Documentation Plugins ServiceNow Query editor

ServiceNow query editor

The ServiceNow query editor lets you build queries that retrieve records or aggregate statistics from your ServiceNow tables. Use Table queries to display individual records like incidents and change requests, or Stats queries to calculate metrics such as incident counts, average resolution times, and category breakdowns.

Before you begin

• Configure the ServiceNow data source.
• Verify your ServiceNow user has read access to the tables you want to query.

Key concepts

The following terms are used throughout this document:

Query types

The ServiceNow query editor supports two query types, selectable from the Query drop-down:

• Table: Returns individual records from a ServiceNow table. Use this for displaying data in table panels, stat panels, or any visualization that works with raw records.
• Stats: Returns aggregated statistics about table data using the Aggregate API. Use this for metric-based visualizations like graphs, bar charts, and gauges.

Table query

A Table query retrieves records from a ServiceNow table with options to select fields, filter results, sort, and limit the number of rows returned.

Table

Select a ServiceNow table from the Table drop-down. A predefined set of common tables is listed by default, but you can type a custom table name to query any table the user has access to.

Show Fields

Select one or more fields to display using the Show Fields selector. Fields are returned in the order you specify. If Use Sys Tables? is enabled in the data source configuration, the drop-down is populated with available fields from the ServiceNow dictionary.

Display value

The Display Value setting controls whether the query returns raw values or human-friendly labels. Select one of the following options:

Time field

The Time Field setting determines how the query interacts with your dashboard’s time range.

By default, the time field toggle is disabled and the query uses Ignore Time mode. In this mode, results aren’t filtered by the dashboard time range, and filters control which data is displayed.

When you enable the toggle, select a date or time field (for example, opened_at). Only records with values in that field that fall within the dashboard’s time range are returned.

Sort by

Use the Sort By setting to order results by one or more fields. For each sort entry, select a field and choose asc (ascending) or desc (descending) order.

Limit

Set a maximum number of rows to return. The default limit is 25. Increase this value to retrieve more records, but be aware that large result sets may affect performance.

Stats query

A Stats query retrieves aggregated statistics from a ServiceNow table using the Aggregate API.

Show Field

Select one or more fields and the aggregation(s) to apply to each field. The following aggregations are available:

You can apply multiple aggregations to a single field and add multiple fields to a single query.

Group by

Use the Group By setting to split aggregated results by one or more fields. For example, grouping by priority returns separate aggregated values for each priority level.

Group by results include a tag with the group field name and its values, which you can use with the Labels to Fields transformation to create separate columns.

Filters

Stats queries support the same filter options as Table queries. Refer to the Filters section.

Filters

Both Table and Stats queries support filters to narrow down results. Add filters using the Filters section of the query editor.

Filter structure

Each filter consists of:

• Field: The ServiceNow table field to filter on.
• Operator: The comparison operator.
• Value: The value to compare against (some operators don’t require a value).
• Conjunction: How this filter combines with the next filter (AND, OR, or NQ).

Conjunctions

String operators

Date operators

Number operators

Boolean operators

Filter value types

The input for filter values depends on the field type:

• Boolean fields: Display a True/False selector.
• Text fields: Display a free-text input.
• Date fields: Display a date picker when a date value is required.
• Choice fields: Display a drop-down with available choices (when Use Sys Tables? is enabled).
• No-value operators: Operators like Is anything, Today, Not Today, Is Empty, Is Not Empty, and Is empty string don’t display an additional input.

Field references

Fields that reference other ServiceNow tables can be expanded to access fields from the related table. In the field selector, reference fields display a collapse indicator. Click to expand and view the available sub-fields.

To use a field from a referenced table, select it using dot notation (for example, caller_id.name to get the caller’s name from the sys_user table).

Annotations

The ServiceNow data source supports annotations using the standard query editor. For examples and a step-by-step guide, refer to Annotate dashboards with ServiceNow events.

Transformations

You can apply transformations to ServiceNow query results to reshape data for your visualizations.

The Labels to fields transformation is particularly useful with Stats queries that use Group By. It converts group-by label values into separate table columns.

Next steps

• Set up alerting with ServiceNow queries
• Annotate dashboards with ServiceNow events
• Use template variables