ONQL syntax and query structure

OpManager Nexus Query Language (ONQL) follows a defined syntax and query structure to ensure queries are interpreted correctly and monitoring data is retrieved consistently. Each clause has a specific purpose and must follow a predefined order to identify the monitor category, determine which attributes to retrieve, apply filters and aggregations, and organize the results.

A consistent structure also helps detect query errors, prevent unsupported operations, and retrieve accurate results. This document provides a reference for the syntax, clauses, functions, and operators used in ONQL.

Query structure and order

An ONQL query follows a specific structure, with clauses arranged in a defined order. The following example shows how the different clauses are organized within a query for a custom report.

reporttype="" |
include( , , … )
filterby(  )
having(  )
sort  asc|desc
timeperiod  [timeslice ]

Clause: reporttype

Syntax: reporttype="" |

Description: The reporttype clause specifies the monitor category for which the query retrieves data. It also determines the attributes available for use in the query. The category must be enclosed in double quotes, followed by a pipe | to separate it from the remaining query.

Supported categories

The following table lists the supported monitor categories.

Instructions:

• The reporttype clause is mandatory in every Custom Report query. Omitting it returns the ONQL_ERROR_CLAUSE_02 error.
• The single pipe | is required. Omitting it returns the ONQL_ERROR_SYNTAX_05 error.

Attributes

Attributes identify the monitoring data used in report columns, filters, and sorting. Each attribute is specified using a dotted path in the format namespace.attribute. For attributes belonging to child entities, use namespace.relationship.attribute.

Supported namespaces

The following table lists the supported namespaces.

Instructions: Use the full namespace name when specifying attributes. Do not use abbreviations such as perf., inv., or avail., as they are not supported.

Relationship levels: Attributes can refer to the monitor itself, its child entities, or other related monitors. The relationship specified in the attribute path determines where the data is retrieved from.

Finding attribute names

The attributes available depend on the type of monitoring data you want to retrieve. While monitoring inventory and availability attributes are common across all accounts, the attributes under performance and resource inventory vary depending on the monitor categories, monitor types, plugins, and performance counters configured in the account.

To identify the attributes available in your account, press Ctrl + Space (Windows), Option + Space (macOS), or Shift + Space (Linux) in the Query Editor. This displays context-aware suggestions based on your monitoring configuration, helping you select the appropriate attributes without having to enter their names manually.

The suggestions provide the complete list of supported attributes for your account. Using an invalid or unsupported attribute name in your query returns the ONQL_ERROR_COLUMN_01 error.

To learn more about the supported attributes, their data types, and whether they can be used in filters, see the list of supported attributes.

The operator and value must be compatible with the attribute's data type. Using an unsupported operator returns the ONQL_ERROR_VALUE_01 error, while providing a value in an incorrect format returns the ONQL_ERROR_VALUE_02 error.

Clause: include()

The include() function specifies the columns to be retrieved. You can include monitoring attributes, apply aggregation functions, convert units, and assign custom column names. The columns appear in the order they are specified in the query.

The include() function is mandatory in every query.

Syntax: include(, , ...)

Each column follows this syntax: [aggregate[|aggregate...]](attribute) [in "unit"] [as "alias"]

Supported column formats

The following table shows the different ways you can specify columns within include().

Instructions:

• A query can include a maximum of 100 columns, with each aggregate in a multi-aggregate column counted separately. Exceeding this limit returns the ONQL_ERROR_COLUMN_04 error.
• Duplicate columns are not supported. Including duplicate columns returns the ONQL_ERROR_COLUMN_03 error.
• in comes before as, and both take quoted values.
• While using Custom Reports, anything you use in filterby(), having(), or sort must also be in include().
• Aliases are display only. Other clauses use the real attribute name.

Function: aggregate()

Aggregation functions summarize multiple data points collected over a specified time period into a single value for each report row. In ONQL, aggregation functions are supported only for attributes under the performance namespace.

Supported functions

The following table lists the supported aggregation functions.

Instructions:

• Aggregation functions can be applied only to performance attributes. On any other namespace, it returns ONQL_ERROR_RULE_01 (aggregation_performance_only).
• For p99 and pc to return calculated percentile values for supported performance metrics, configure your report settings.
• Functions such as sum, count, median, stddev, first, and last are not supported. Using them returns the ONQL_ERROR_ATTRIBUTE_02 error.

Unit conversion: in "unit"

The in modifier allows you to convert an attribute's value from its base unit to another supported unit within the same unit family. This helps you display performance, availability, and resource inventory attributes in units that are more suitable for your reporting requirements.

For example, you can convert downtime from milliseconds to hours using:

availability.down_time in "hrs"

Supported units

The following table lists the units supported for conversion.

Instructions:

• Enclose the unit in double quotes.
• Use the supported unit abbreviations exactly as listed. Full names such as "hours", "seconds", or "megabytes" are not supported.
• You can convert values only between units belonging to the same unit family.
• Applying unit conversion to an attribute that does not support it returns the ONQL_ERROR_VALUE_04 error.
• Specifying a unit from a different unit family returns the ONQL_ERROR_VALUE_03 error.

Clause: filterby()

The filterby() clause filters monitors based on their monitoring and resource inventory attributes before retrieving their data. It allows you to narrow down the monitors included in a Custom Report using conditions such as monitor names, types, tags, and other supported inventory attributes.

Syntax: filterby( [and|or ...])

Example:

filterby((monitoring_inventory.tags is ("prod") or monitoring_inventory.tags is ("stage")) and monitoring_inventory.monitor_name begins_with "web")

This example retrieves data for monitors whose names begin with web and are associated with either the prod or stage tag.

Supported operators

The following operators can be used to define filter conditions. ONQL uses word-based operators rather than symbols in filterby().

Combining filter conditions:

• You can combine multiple conditions using the and and or operators to create more complex filters.
• Use and to combine conditions on monitoring_inventory and resource_inventory attributes. Using or returns the ONQL_ERROR_RULE_03 error.
• Use the or operator to combine conditions within the same namespace, either Resource Inventory or Monitoring Inventory.
• Use the and operator to combine conditions across Resource Inventory and Monitoring Inventory namespaces.
• and requires all connected conditions to be satisfied.
• or requires at least one connected condition to be satisfied.
• and takes precedence over or. For example, a and b or c is evaluated as (a and b) or c.
• Use parentheses to group conditions and control their evaluation order. Two levels of nested parentheses are supported.
• An empty list returns ONQL_ERROR_SYNTAX_14.
• Using unsupported namespaces in filterby() returns the ONQL_ERROR_ATTRIBUTE_05 error.
• Specify a non-empty value in filterby(). Using an empty value like is "" returns the ONQL_ERROR_RULE_01 (value_not_empty) error.
• Include an operator when defining a condition in filterby(). Omitting it, as in filterby(monitoring_inventory.monitor_name), returns the ONQL_ERROR_SYNTAX_13 error.

Filtering with multiple values

You can specify multiple values within parentheses to match or exclude several values in a single condition.

Example 1: Match any specified value

filterby(monitoring_inventory.monitor_type is ("Website", "Server Monitor"))

Includes monitors belonging to any of the specified monitor types.

Example 2: Exclude all specified values

filterby(monitoring_inventory.tags is_not ("test", "sandbox"))

Excludes monitors associated with either of the specified tags.

Instructions:

• Monitoring inventory and resource inventory attributes: filterby() supports attributes under the monitoring inventory and resource inventory namespaces. To filter based on measured performance values, use having() instead.
• Only filterable attributes are supported: Attributes designated as display-only cannot be used in filter conditions. The Query Editor suggests only filterable attributes.
• Operators must match the data type: Use operators compatible with the attribute's data type. Text-based operators such as contains, begins_with, and regex are not supported for fixed-list attributes.

Clause: having()

The having() clause filters report rows based on their measured performance or availability values. It allows you to focus on monitors that meet specific conditions, such as CPU usage exceeding a threshold or monitors being in a particular status.

Syntax: having( [and ...])

Example:

having(avg(performance.cpu_utilization) > 80 and avg(performance.memory_utilization) > 70)

This example query retrieves resources where the average CPU usage exceeds 80% and the average memory usage exceeds 70% during the selected time period.

Supported operators

The following comparison operators can be used to define conditions in having().

Supported values

The values used in having() must be compatible with the selected attribute and operator.

• Numeric values: Supports integers, decimals, and negative numbers, such as 80, 1.5, and -3.
• Status values: Supports up, down, trouble, and critical with the is and is_not operators. Multiple status values can be separated by commas.

Instructions:

• Aggregation can be used for performance metrics: Each performance metric condition must contain an aggregation function. For example, having(performance.cpu_usage_percentage > 80) is invalid because the metric does not have an aggregation function. When an aggregation type is not mentioned, by default, average is calculated.
• Use only and to join conditions, including grouped conditions. Using or or commas between conditions returns the ONQL_ERROR_SYNTAX_07 error.
• You cannot apply multiple aggregation functions to the same attribute within a single condition. For example, avg|max(performance.cpu_usage_percentage) is invalid in having() and returns the ONQL_ERROR_RULE_01 (multi_aggregation_in_filter) error. Specify each aggregation in a separate condition instead.
• Performance and availability attributes only: having() supports attributes under the performance and availability namespaces.
• Use the in unit modifier to specify a threshold in a different unit within the same unit family, similar to unit conversion in columns. For example, having(avg(performance.response_time) in "secs" > 300) filters results where the average response time exceeds 300 seconds.
• Use parentheses in having() to group conditions for better readability. Since and is the only supported logical operator, parentheses do not affect the query results. You can nest parentheses to any depth.
• Use only supported operators and valid values for the specified attribute. Using text operators such as contains returns ONQL_ERROR_ATTRIBUTE_04, while specifying an incompatible value returns ONQL_ERROR_VALUE_02.
• Mandatory operator and value: Include an operator and a value in every having() condition. A condition that ends with an attribute without an operator or value returns the ONQL_ERROR_SYNTAX_12 error.
• Mandatory value: Specify a value after the operator in having(). Omitting the value, as in having(avg(...) >), returns the ONQL_ERROR_SYNTAX_10 error.

Clause: sort

The sort clause retrieves results in ascending or descending order based on a selected attribute. You can use it to organize monitoring data, identify the highest or lowest metric values, and prioritize the results for analysis.

Syntax: sort asc|desc

• asc sorts values in ascending order, from lowest to highest.
• desc sorts values in descending order, from highest to lowest.

Example:

sort avg(performance.response_time) desc

This example sorts results by average response time in descending order, displaying monitors with the highest average response time first.

Instructions:

• One sort column: You can sort report rows using only one column at a time.
• Mandatory sort direction: Specify either asc or desc. Parentheses are not required, and there is no default sort direction. Omitting it returns the ONQL_ERROR_SYNTAX_04 error.

Clause: timeperiod

The timeperiod clause defines the time period for which monitoring data is retrieved in a custom report. You can select a predefined time period, specify a custom date range, or define a relative time span to analyze monitoring data over the required duration.

The timeperiod clause must appear at the end of the query, followed only by timeslice, if specified.

Syntax:

• timeperiod
• timeperiod custom_period("start", "end")
• timeperiod custom_expression "span"

Custom date range: custom_period()

The custom_period() function allows you to retrieve monitoring data between two explicitly defined dates and times. You cannot use timeslice after custom_period() in a query.

Syntax: timeperiod custom_period("start", "end")

Example:

timeperiod custom_period("2026-08-01T00:00:00+0530", "2026-08-31T23:59:59+0530")

This example retrieves monitoring data from Aug. 1, 2026 through Aug. 31, 2026, using the specified time zone offset.

Instructions:

• Specify both timestamps in the ISO 8601 format YYYY-MM-DDTHH:mm:ss±HHMM, enclosed in double quotes.
• Use a numeric time zone offset without a colon, such as +0530. Formats such as Z and +05:30 are not supported.
• Specify valid calendar dates for each timestamp. Invalid dates, such as 2026-02-30, are not supported.
• The start time must be earlier than the end time.
• The selected time period cannot exceed two years.
• Ensure the specified time period complies with the first three rules to avoid ONQL_ERROR_PERIOD_07. Exceeding the maximum allowed time period returns the ONQL_ERROR_PERIOD_08 error.

Relative time span: custom_expression

The custom_expression option allows you to define a relative time range using a combination of days, hours, minutes, or months. This is useful for retrieving monitoring data over a specific duration without entering fixed dates.

Syntax: timeperiod custom_expression "span"

Examples:

timeperiod custom_expression "-7d"

timeperiod custom_expression "-1d 2h 30m"

timeperiod custom_expression "-1M"

These examples retrieve data for the preceding seven days, one day plus two hours and 30 minutes, and one month, respectively.

Supported units

The following units are supported.

Instructions:

• Case-sensitive units: Use the exact unit symbols. For example, m represents minutes, while M represents months. Uppercase H is not accepted in place of h.
• Optional negative sign: The leading - is optional. Relative time spans always represent a duration extending backward from the current time.
• Valid expression: Specify a correctly formatted expression. Malformed expressions return the ONQL_ERROR_PERIOD_05 error.
• Valid time span: Ensure the specified time span is within the supported range. Exceeding the allowed length returns the ONQL_ERROR_PERIOD_06 error.

Clause: timeslice

The timeslice clause divides the selected reporting period into smaller intervals, allowing you to analyze how monitoring metrics change over time instead of viewing a single aggregated value for the entire period.

The timeslice clause must appear immediately after a supported, predefined timeperiod.

Syntax: timeperiod timeslice

Example:

timeperiod last_24_hours timeslice hour

This example divides the last 24 hours into hourly intervals, allowing you to view the aggregated metric values for each hour.

Instructions:

• Supported time periods only: timeslice can be used only with the predefined time periods. Other periods, including last_7_days, last_week, today, and yesterday, are not supported.
• Named periods only: timeslice cannot be used with custom_period() or custom_expression.
• Compatible intervals: The selected interval must be supported for the specified time period. Otherwise, the query returns ONQL_ERROR_PERIOD_04.
• Valid interval names: Using an unrecognized interval returns ONQL_ERROR_PERIOD_03.

Glossary

The following table explains the key terms used in ONQL.

Formal grammar

The following grammar defines the structure of an ONQL query, including its clauses, functions, conditions, and supported expressions.

Notation:

• [x] indicates an optional element.
• x* indicates an element that can repeat zero or more times.
• | separates alternative expressions.
• Use at least one space between clauses. Extra white spaces between tokens do not affect the query.

query             = [ reporttype ] [ include ] [ filterby ] [ having ] [ sort ] [ timeperiod ]
reporttype        = "reporttype" "=" string "|"
include           = "include" "(" column ("," column)* ")"
filterby          = "filterby" "(" or_expr ")"
having            = "having" "(" having_expr ")"
sort              = "sort" column_ref ("asc" | "desc")
timeperiod        = "timeperiod" ( custom_period | custom_expression | period [ "timeslice" slice ] )
column            = column_ref [ "in" string ] [ "as" string ]
column_ref        = aggregation | attribute
aggregation       = agg_fn ("|" agg_fn)* "(" attribute ")"
attribute         = name [ "." level ] "." name
or_expr           = and_expr ("or" and_expr)*
and_expr          = term ("and" term)*
term              = "(" or_expr ")" | condition
condition         = attribute operator value
having_expr       = having_term ("and" having_term)*
having_term       = "(" having_expr ")" | having_cond
having_cond       = having_subject compare_op having_value
having_subject    = "(" having_subject ")" | aggregation [ "in" string ] | attribute [ "in" string ]
having_value      = value ("," value)*
value             = string | number | bareword | "(" value ("," value)* ")"
custom_period     = "custom_period" "(" string "," string ")"
custom_expression = "custom_expression" string
string            = '"' any-character-except-'"' '"'
number            = [ "-" ] digits [ "." digits ]

ONQL errors and troubleshooting

ONQL provides specific error codes to help you identify and resolve issues in your queries. When an error occurs, the Query Editor displays a descriptive message with the relevant values, making it easier to identify the issue.

ONQL error codes follow the format ONQL_ERROR__, where AREA indicates the error category and NN identifies the specific error within that category. Each error code remains unchanged even if its corresponding error message is updated, making it easier to identify and troubleshoot errors consistently. Each error has a unique code that remains consistent across interface languages. You can use these codes when contacting support or searching logs.

Types of errors

ONQL errors are classified into seven categories:

• Clause errors: Occur when mandatory clauses are missing or unsupported clause combinations are used.
• Syntax errors: Occur when a query does not follow the required ONQL syntax or structure.
• Time period and timeslice errors: Occur when reporting periods, custom time ranges, or time intervals are invalid or incompatible.
• Column errors: Occur when columns are invalid, incomplete, duplicated, or exceed supported limits.
• Attribute errors: Occur when unsupported attributes, aggregation functions, or operators are used.
• Value and unit errors: Occur when values, data types, or units are invalid or incompatible.
• Business-rule validation errors: Occur when a syntactically valid query violates ONQL-specific reporting rules.

See ONQL error codes for more details.

Additional troubleshooting guidance

If an error persists after correcting the query, copy the query text and error code, note the selected report type, and contact support with these details.

Related articles

• Understanding ONQL and how it works
• A quick guide to building queries using ONQL
• ONQL error codes and troubleshooting