This document provides query language general syntax and OpsQL related information.

General syntax

The search query string has the following general form:

    <attribute> <operator> | <coperator> "<value>" [[<operator> [<attribute> | <coperator> "<value>"[)]] ... ]

Example of a query syntax:

Find all the resources, which have an agent installed and Windows, as the type of resource.

Example query result:

A few more examples:

  • type CONTAINS “Docker_Container” - To filter the Docker containers.
  • type CONTAINS “CRIO_Container” - To filter the CRI-O containers.
  • type = “CONTAINERD_CONTAINER” AND (tags.name CONTAINS “container” AND tags.value CONTAINS “production”) - To filter the ContainerD container using labels.
  • type = “Switch” AND make = “cisco systems” - To filter all switches whose make is Cisco Systems.
  • serialNumber STARTS WITH “abc” AND type = “linux” - To filter all resources whose resource type is Linux and serial number starts with “abc”.

Attributes

The dialog displays a list of attributes. Use the mouse or down-arrow key to highlight and select the attribute you want.

Attribute values

Attributes and attribute values form a key:value pair. Enclose non-integer attribute values in quotes: name = "Activemq". You do not need to quote integer value types.

Logical operators

OperatorDescription
ANDCompare two expressions and return true, if both expressions evaluate to true.
ORPerforms an inclusive OR operation on two expressions and returns true, if either or both expressions evaluate to true.

Precedence

Use parentheses to control the order of evaluation of the expressions. Expressions within parentheses are evaluated before non-parenthetical expressions. The most deeply nested parenthetical expression is evaluated first. This applies to the Advanced Query Mode.

OpsQL

OpsQL stands for OpsRamp Query Language and supports a flexible and powerful way to search for objects within the OpsRamp platform. OpsQL honors RBAC similar to the OpsRamp application user interface.

Elements of OpsQL

A valid OpsQL expression is comprised of: Attribute + Operator + Value

  • Attribute - Attributes are different types of information available on an object. Different objects possess different attributes. For instance, a resource has attributes such as make, ipAddress, and agentInstalled, while an alert has attributes such as priority, currentState and createdTime.
  • Operator - Operator is the key of the query. It relates the attribute to the value. Common operators include = , !=, LIKE, NOT LIKE.
  • Value - Value is what you query for. The non-numeric values should be enclosed within double quotes.

Multiple expressions can be combined using the following logical operators to form a single query.

ANDThis will return results, which match all segments within the query.
For example:
agentInstalled = "true" AND make = "LENOVO"
will return all the resources where make is equal to “Lenovo” and has the agent installed.
ORThis will return results, which match one or more segments within the query.
For example:
agentInstalled = "true" OR make = "LENOVO"
will return resources where either make is equal to “Lenovo” or has the agent installed.

Supported Attributes

The following resource attributes are supported in the OpsQL search:

agentInstalledagentVersionagentProxyIpAddressagentProxyNameagentConnectivity
agentProxyProfileUUIdaliasNamealternateIpAddressavailableAppNameavailabilityState
clientIdclientNamedeviceGroupsdiscoveryProfileIddnsName
hasRelationshiphostNameididentityinstalledAppName
ipAddresslastUpdatedlocationmacAddressmake
managementProfileIdmodelnamenativeTypeos
osTyperesourceNametyperootLocationserialNumber
serviceGroupsstatetagstimezone

The following alert attributes are supported in the OpsQL search:

alertCriticalWarningDurationalertTypeclientIdclientNamecomponent
correlatedAlertsCountcreatedTimecurrentStatedescriptiondnsName
incidentIdidinferenceIdipAddressisAvailabilityAlert
isInferenceAlertmetricobjectIdobjectNameobjectType
originalStateproblemArearepeatCountsourcestatus
subjecttriggeredTimeupdatedTime

Operators


=Equality check
For example:
make = “Lenovo”
!=Non equality check
For example:
make != “Lenovo”
LIKEUse in conjunction with a wildcard ‘%’ to match a specified pattern.
For example:
make LIKE "%Inc."
Matches resources where the value of make ends with “Inc.”

“%Inc” - match strings ending with “Inc”
“%Inc%” - match strings containing “Inc”
“Inc%” - match strings starting with “Inc”
NOT LIKEUse in conjunction with a wildcard ‘%’ to exclude matches with a specified pattern.
For example:
make NOT LIKE "%Inc."
Excludes resources where the value of make ends with “Inc.”

“%Inc” - match strings ending with “Inc” “%Inc%” - match strings containing “Inc” “Inc%” - match strings starting with “Inc”
>This operator is only available for numeric attributes and should be followed by numeric values. Matches value greater than
For example:
repeatCount > 5
<This operator is only available for numeric attributes and should be followed by numeric values. Matches value less than For example: repeatCount < 5
>=This operator is only available for numeric attributes. Matches value greater than or equal to
For example:
repeatCount >= 5
<=This operator is only available for numeric attributes and should be followed by numeric values. Matches value less than or equal to
For example:
repeatCount <= 5
CONTAINSUse this to search for a sequence of characters in a string.

For example:
Name CONTAINS "Ubuntu"
Matches resources where name contains the word “Ubuntu””
NOT CONTAINSUse this to search for strings that do not contain a specified sequence of characters.

For example:
name NOT CONTAINS "acme"
Matches resources where name does not contain the word “acme”
REGEXREGEX (Regular Expression) is used in OpsQL to perform advanced, pattern-based searches on resource attributes like name, alias, IP address, and custom fields. Unlike exact match filters, REGEX allows you to search for values that follow a specific pattern — such as names starting with app, IP addresses in a certain range, etc.
REGEX enhances flexibility, reduces the need for multiple OR conditions, and helps you efficiently filter and locate relevant resources based on complex criteria.

Examples:
  • To fetch all resources whose names start with the letter a:
    name REGEX "a.*
  • To fetch all resources whose names end with a number:
    name REGEX ".*[0-9]"
  • To fetch all resources that contain the word server in the name:
    name REGEX ".*server.*"
  • To fetch all resources whose names start with ubuntu followed by one or more digits.
    name REGEX "^ubuntu[0-9]"
Note: The maximum number of regex terms that can be used is 5.
REGEX NOTREGEX NOT is used in OpsQL to exclude resources that match a specific pattern in attributes like name, alias, IP address, or custom fields. REGEX NOT adds precision and control when you want to narrow down your search by removing unwanted naming patterns or formats.

Examples:
  • To fetch all resources whose names do not start with app:
    name REGEX NOT "app.*"
  • To fetch all resources whose names do not end in digits:
    name REGEX NOT ".*[0-9]"
  • To fetch all resources that do not contain the word server in the name:
    name REGEX NOT ".*server.*"
  • To fetch all resources whose IP addresses do not start with 127
    ipAddress REGEX NOT "127.*"
  • To fetch all resources whose site name does not start with US-EAST
    location REGEX NOT "US-EAST.*"
Note: The maximum number of regex terms that can be used is 5.
INUse this to search for strings specified in parentheses.

For example:
name IN ("centos_1", "centos_2")
Matches resources, which match either of the names “centos_1" or "centos_2"
NOT INUse this to search for strings other than those specified in parentheses.

For example:
name NOT IN ("centos_1", "centos_2")
Matches resources, which do not match either of the names “centos_1" or "centos_2"
STARTS WITHSearch for strings that start with a specified character or a sequence of characters.

For example:
serialNumber STARTS WITH "FOC"
Matches resources that have serial number starting with “FOC”
NOT STARTS WITHSearch for strings that do not start with a specified character or a sequence of characters.

For example:
resourceName NOT STARTS WITH "ASU"
Matches resources whose resource name do not start with “FOC”
ENDS WITHSearch for strings that end with a specified character or a sequence of characters.

For example:
serialNumber ENDS WITH "X2"
Matches resources that have serial number ending with “X2”
NOT ENDS WITHSearch for strings that do not end with a specified character or a sequence of characters.

For example:
model NOT ENDS WITH "5591"
Matches resources whose model do not end with “5591”

Keywords


IS NULLUsed to test for empty values
For example:
make IS NULL
IS NOT NULLUsed to test for non-empty values
For example:
make IS NOT NULL

Query Examples


Resources

QueryDescription
os = "windows" AND availabilityState = "down"All Windows os, which are currently down.
make = "Other" OR make IS NULLAll resources where the make is either Other or null.
type = "server" AND state = "active"All resources where resource type is Server and in active state.
agentInstalled = "false" AND type = "Linux"All resources, which have resource type as Linux and do not have the agent installed.
name CONTAINS "cent" AND type = "server"All resources whose resource name contains the string "cent" and resource type is server.
name NOT CONTAINS "data" AND state = "active"All resources, which are in active state and name does not contain the string "data".
availabilityState IN ("undefined", "unknown")All resources whose availability state is either "undefined" or "unknown".
name STARTS WITH "windows"All resources whose name starts with the string "windows".
serialNumber ENDS WITH "x2"All resources whose serial number ends with the string "x2".
dnsName NOT STARTS WITH "hyd"All resources whose dnsName do not start with the string "hyd".
name LIKE "%cluster%"All resources whose resource name contains the string "cluster".
model NOT ENDS WITH "5801"All resources whose model does not end with "5801".
name NOT LIKE "%netapp"Excludes resources whose name ends with "netapp".
installedAppName = "Aws"All the resources that are discovered under the AWS integration.
tags.name = "serial number"Fetches all the resources that have the Key (custom attribute key) as "serial number".
tags.value = "ABL-123"Fetches all the resources that have the value (custom attribute value) as "ABL-123".
agentInstalled = "true" AND
(ipAddress = "1.2.3.4" OR name CONTAINS "fedora")		Returns all agent installed resources with name containing "fedora" and resource with ipaddress as "1.2.3.4"
availabilityState = "DOWN" AND
(make = "VMware, Inc." OR os = "Ubuntu 14.04.6 LTS")		All resources whose availability state is DOWN and make is "VMware, Inc." and also OS is Ubuntu 14.04.6 LTS
state = "active" AND os IN ("CentOS Linux release 7.6.1810 (Core)","Microsoft Windows Server 2019","freebsd 12.1-release") OR
make = "VMware, Inc." AND agentInstalled = "true"		Returns all the agent installed resources with state as "active" and os is "CentOS Linux release 7.6.1810 (Core)", "Microsoft Windows Server 2019", "freebsd 12.1-release" and make is "VMware, Inc."
activeScheduleMaintenanceIds CONTAINS
"sm-fcdf5c74-e796-4d8c-8fc3-a63e1f002cad"		Returns all the resources that are currently undergoing scheduled maintenance associated with the specified maintenance ID.
scheduleMaintenanceIds CONTAINS
"sm-016db8b4-6682-42b0-b38d-ba22ba658b10,
sm-27617d14-f2d1-4ca3-b53b-572907e28c48,
sm-ac30bbf8-d774-4eb2-a2a7-4e4243bfe464,
sm-b388fec7-6ec6-4386-8080-ea07ce88bb50,
sm-fb2e4692-5a0d-48ef-ac96-a3f63c52e016"		Fetches all resources that are currently in a Pending or Suspended scheduled maintenance state, matching the specified maintenance IDs.
domainProperties['physicalLocationName'] = "Location1"
Fetches all SNMP-discovered resources where the domain attribute physical_location_name has the value Location1.

You can view the the DOMAIN ATTRIBUTES section in the resource details screen.
name REGEX "aws.*"
Fetches all resources whose names start with aws
location REGEX NOT "US-WEST-2.*"
Fetches all resources whose site name does not start with US-WEST-2


Alerts

QueryDescription
currentState = "Warning"Number of warning alerts.
triggeredTime >= "-7d"Lists all the alerts that have triggered over the last 7 days.
alertType = "MONITORING" AND status = "Open"Returns all the monitoring alerts whose status is Open.
isAvailabilityAlert = "true"Returns all the availability alerts.
subject CONTAINS "CPU is critical"Lists all the alerts that have subject as "CPU is critical".
createdTime > "-10d" AND status = "Open"Returns all the open alerts over the last 10 days.
currentState = "Critical" AND status = "Suppressed"Returns the number of suppressed critical alerts.
component = "cpu"Returns the number of alerts where component is CPU.
status IN ("Acknowledged","Ticketed")Returns the number of alerts whose status is either Acknowledged or Ticketed.
objectId STARTS WITH "5a"Returns all the alerts whose objectId or resource ID starts with "5a".
objectType = RESOURCE and objectName CONTAINS "host1"Returns all the alerts wherein object type is resource and objectName or resource name contains "host1".
repeatCount >= 2Returns all the alerts whose alert
occurrences >= 2.
source = "Email Alerts"Returns all the alerts which come from "Email Alerts" integration.
ipAddress STARTS WITH "172"Returns all the alerts for the resources whose IP address starts with "172".
priority = "P1"Returns all the alerts whose priority is "P1".


Sample Queries for Filtering Cloud-Native Resources:

Note: To execute these queries, Kubernetes 2.0 integration must be installed.

QueryDescription
discoveryManifestConfigId = 'ADAPTER-MANIFEST-676dc8d1-c95e-4aef-b42f-a6f7a136ad4f9'Filter with integration name / ID.
discoveryManifestConfigId = 'ADAPTER-MANIFEST-676dc8d1-c95e-4aef-b42f-a6f7a133354k9' AND nativeType = "K8s Pod"Filter all pods that are part of specific integration/app.
Filter all Pods that are part of a specific node.
discoveryManifestConfigId = 'ADAPTER-MANIFEST-676dc8d1-c95e-4aef-b42f-a6f7a9936pd5f9' AND nativeType = "K8s Pod" AND name STARTS WITH 'helm'Filter all pods that start with or contain ABC and part of specific integration/app.
nativeType = 'K8s Pod' AND topology.sourceId = 'cb7920db-8a43-46ae-8e75-393gts8defc42'Filter all Pods that are part of a specific node.
discoveryManifestConfigId = 'ADAPTER-MANIFEST-676dc8d1-b89p-4aef-b42f-a6f7a136d5f9' AND nativeType = "K8s Node"Filter all nodes that are part of a cluster.