Overview

DSL Reference

SN-Viz uses a pipe-delimited, key=value query language to describe what data to fetch and how to visualize it. Each query is a single line of clauses separated by |.

table=incident | filter=active=true | stat=COUNT | by=category | viz=bar

Only table= is required. All other parameters are optional and have sensible defaults. Clauses can be written in any order.

Tip: Press Ctrl+Enter inside any query box to execute immediately. Use /viz on any ServiceNow list to open SN-Viz with that table pre-filled, or /viz generate to auto-build visuals from the current list context.

Query Anatomy

Each clause has the form key=value. Whitespace around | and = is ignored. Keys are case-insensitive.

# Minimal — table only, shows total count as a gauge table=incident # Group by one field table=incident | stat=COUNT | by=priority | viz=pie # Two dimensions, stacked bar, limit each axis table=incident | by=category | by2=state | limit=6 | limit2=4 | viz=bar # Time trend with a date field table=change_request | trend=opened_at BY month | viz=area

All Parameters

Parameter Values Default Description
table= any SN table name — ServiceNow table to query (e.g. incident, change_request)
filter= Optional SN encoded query string none (all records) ServiceNow filter string using standard operators. Supports ^ (AND) and ^OR (OR).
stat= Optional COUNT | AVG(field) | SUM(field) | MIN(field) | MAX(field) COUNT Aggregate function. For AVG/SUM/MIN/MAX, the field name is required inside parentheses.
by= Optional field name (dot-walk supported) none Primary group-by field. Supports comma-separated multiple fields (deprecated — use by2= for 2D). Maps to the X-axis on bar charts.
by2= Optional field name none Second group-by field creating a 2D matrix. Maps to the series/legend (colors) on bar charts, and Y-axis on heatmaps.
trend= Optional field BY day|week|month|quarter|year none Time-series grouping on a date field. Produces a line or area chart automatically.
bucket= Optional field [range1, range2, ...] none Groups records into numeric ranges. Each bucket produces one bar. See Bucket Ranges section below.
viz= Optional bar|pie|donut|line|area|heatmap|scatter|treemap|gauge|number|table|auto auto Explicit chart type. With auto, SN-Viz picks the best type based on your data shape.
sort= Optional asc | desc desc Sort direction for grouped results. Sorts by the stat value.
limit= Optional positive integer none (all) Max number of groups to display from the primary grouping (by=). Groups are sorted by total value before slicing.
limit2= Optional positive integer none (all) Max number of groups from the secondary grouping (by2=). Only applicable when by2= is set.
target= Optional numeric value none Draws a red dashed horizontal target/threshold line on bar, line, and area charts.
having= Optional AGG^FIELD^OP^VALUE none Post-aggregation filter (like SQL HAVING). Filters groups after stats are computed.
label= Optional any text none Sets the panel title. Overwrites the editable panel heading when the query is executed.
drilldown= Optional true | false true Enable or disable click-to-drilldown navigation. When enabled, clicking a data point opens a filtered ServiceNow list.
from= Optional date string (YYYY-MM-DD or relative) none Start of the date window. Applies a filter on datefield.
to= Optional date string none End of the date window. Used with from=.
datefield= Optional any date field name sys_created_on Which date field to apply from=/to= filters on. Also used as the default field for trend queries.

filter=

Accepts a ServiceNow encoded query string — the same format used in SN list views. Use ^ for AND, ^OR for OR, and standard SN field operators.

Common operators
= Equals
!= Not equals
CONTAINS Contains (LIKE)
STARTSWITH Starts with
ISEMPTY / ISNOTEMPTY Is/Is not empty
IN In list (comma-separated values)
!= Not equals
> / < / >= / <= Numeric or date comparison
filter=active=true^priority=1^category=network filter=state!=6^assigned_toISNOTEMPTY filter=priority=1^ORpriority=2

stat=

Defines the aggregate function applied to each group. Default is COUNT.

Value Description Requires field
COUNT Count of records in each group No
AVG(field) Average value of field across each group Yes
SUM(field) Sum of field values across each group Yes
MIN(field) Minimum field value in each group Yes
MAX(field) Maximum field value in each group Yes
stat=COUNT stat=AVG(reopen_count) stat=SUM(business_duration)

by= and by2=

by= is the primary group-by field. It maps to the X-axis on bar charts, and to the primary dimension on heatmaps and scatter plots.

by2= is the secondary group-by field. It creates a 2D matrix, mapping to the legend/color series on bar charts, and to the Y-axis on heatmaps.

Note: Both by= and by2= support dot-walk syntax — you can traverse reference fields (e.g. by=assigned_to.department).
# 1D — simple bar by category by=category # 2D — category on X-axis, state as stacked colors by=category | by2=state # Dot-walk — group by the assignment group's manager by=assignment_group.manager.name

trend=

Groups results by a date field over time into equal-width buckets. Produces a line or area chart. Add by= to split into multiple series — one line per group value.

Syntax: trend=<date_field> BY <interval>

Interval Description
day One bucket per calendar day
week One bucket per week (Mon–Sun)
month One bucket per calendar month
quarter One bucket per fiscal quarter
year One bucket per year
trend=opened_at BY month trend=sys_created_on BY week # Multi-series: one line per category trend=opened_at BY month | by=category | limit=4

bucket=

Groups numeric field values into custom ranges. Each range becomes one bar. Cannot be combined with by= or trend=.

Syntax: bucket=<field> [range1, range2, ...]

Range Syntax
0 - 100Inclusive range: 0 ≤ x ≤ 100
>100Greater than 100 (unbounded high)
<=0Less than or equal to 0
>=200Greater than or equal to 200
bucket=reopen_count [0, 1, 2 - 5, >5] bucket=business_duration [<=60, 61 - 480, >480]

viz=

Selects the chart type. When set to auto (default), SN-Viz picks the best type based on your data shape.

Bar
viz=bar
Vertical bars. Stacked when by2= is set. Supports target=.
Pie
viz=pie
Full-circle proportional chart. Good for ≤8 categories.
Donut
viz=donut
Pie with a hollow center. Same rules as pie.
Line
viz=line
Continuous line chart. Best for trend data.
Area
viz=area
Line chart with filled area. Best for single-series trends.
Heatmap
viz=heatmap
2D grid with color intensity. Requires by= and by2=.
Scatter
viz=scatter
Bubble/dot plot. Requires by= and by2=. Click dots to drilldown.
Treemap
viz=treemap
Nested rectangles proportional to value.
Gauge
viz=gauge
Dial gauge. Best when no grouping is set.
Number
viz=number
Big number KPI card. Shows the total stat value.
Table
viz=table
Tabular view of grouped results. Scrollable, no chart.

limit= and limit2=

limit= controls the maximum number of groups shown from the primary dimension (by=). limit2= controls the secondary dimension (by2=).

Groups are ranked by total value descending before slicing — so you always see the top N by volume.

# Top 5 categories, top 3 states as stack colors by=category | by2=state | limit=5 | limit2=3

target=

Adds a red dashed horizontal line to bar, line, and area charts at the specified numeric value. Useful for SLA thresholds or KPI goals.

table=incident | stat=COUNT | by=assignment_group | target=50

having=

Filters groups after aggregation — equivalent to SQL's HAVING clause. Format: AGGREGATE^FIELD^OPERATOR^VALUE

AGGREGATE The stat: count, avg, sum, etc.
FIELD The groupby field name (e.g. category)
OPERATOR >, <, =, !=, >=, <=
VALUE Numeric threshold value
# Only show assignment groups with more than 50 incidents having=count^assignment_group^>^50

label=

Sets the panel title text when the query is executed. Overwrites the default "New Panel" heading. Useful when building dashboard layouts that need clear titles.

label=Active Incidents by Priority

drilldown=

Controls whether clicking a chart element navigates to a filtered ServiceNow list. Default is true. Set to false to disable.

When enabled, clicking a bar, pie slice, scatter dot, or other element appends the clicked group value as a filter to the base query and opens the matching list view in ServiceNow.

Note: Drilldown is supported on all chart types. Heatmap and Scatter drilldown require both by= and by2= to be set.

from= / to= / datefield=

These three parameters define a date window filter applied on top of the query. Typically set via the panel's Date Window dialog rather than typed manually.

Parameter Description
from= Start date. Accepts YYYY-MM-DD or ServiceNow relative date formats.
to= End date. Used with from=.
datefield= Date field to filter on. Defaults to sys_created_on. Also used as the default for trend queries.

Dot-walking Fields

Any field in by=, by2=, stat=(field), bucket=(field), and filter= can traverse reference fields using dot notation. As you type, autocomplete suggestions follow the chain and show fields on the referenced table.

# Group by the caller's department name by=caller_id.department.name # Group by the assignment group's manager location by=assignment_group.manager.location.name

2D Charts with by= and by2=

When both by= and by2= are set, SN-Viz builds a 2D matrix from the two fields:

  • Bar chart: by= → X-axis labels, by2= → stacked color series (legend)
  • Heatmap: by= → X-axis, by2= → Y-axis rows
  • Scatter: by= → X-axis, by2= → legend groups
Tip: Swapping by= and by2= in your query pivots the chart axes. Use limit= and limit2= to control how many groups appear on each axis.

Query Gallery

Copy any of these to get started immediately. All use the incident table which is universally present in ServiceNow instances.

Basic — Count by priority
table=incident | filter=active=true | stat=COUNT | by=priority | viz=pie
Stacked bar — Top 6 categories by 4 states
table=incident | stat=COUNT | by=category | by2=state | limit=6 | limit2=4 | viz=bar
Heatmap — Assignment group vs priority
table=incident | filter=active=true | by=assignment_group | by2=priority | limit=8 | limit2=5 | viz=heatmap
Time trend — Monthly incident volume
table=incident | trend=opened_at BY month | viz=area
Multi-series trend — Volume by category over time
table=incident | trend=opened_at BY month | by=category | limit=4 | viz=line
Average reopen count — Top close codes
table=incident | filter=active=false | stat=AVG(reopen_count) | by=close_code | limit=8 | viz=bar
Bucket — Reopen count distribution
table=incident | bucket=reopen_count [0, 1, 2 - 5, >5]
HAVING — Groups with more than 30 incidents
table=incident | by=category | having=count^category^>^30
KPI number — Total open P1 incidents
table=incident | filter=active=true^priority=1 | stat=COUNT | viz=number | label=Open P1 Incidents
Dot-walk — Incidents by caller department
table=incident | by=caller_id.department.name | limit=10 | viz=bar
Target line — SLA threshold at 100
table=incident | filter=active=true | by=assignment_group | limit=8 | target=100 | viz=bar