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 query syntax:

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

Example query result:

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
ANDCompares two expressions and returns 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.

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”
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

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
resourceType = "server" AND state = "active"All resources where resource type is Server and in active state
agentInstalled = "false" AND resourceType = "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"
Alerts

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"
objectName CONTAINS "host1"Returns all the alerts whose 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"