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.

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


All Windows os, which are currently downos = "windows" AND availabilityState = "down"
All resources where the make is either Other or nullmake = "Other" OR make IS NULL
All resources where resource type is Server and in active stateresourceType = "server" AND state = "active"
All resources, which have resource type as Linux and do not have the agent installedagentInstalled = "false" AND resourceType = "Linux"
All resources whose resource name contains the string "cent" and resource type is servername CONTAINS "cent" AND type = "server"
All resources, which are in active state and name does not contain the string "data"name NOT CONTAINS "data" AND state = "active"
All resources whose availability state is either "undefined" or "unknown"availabilityState IN ("undefined", "unknown")
All resources whose name starts with the string "windows"name STARTS WITH "windows"
All resources whose serial number ends with the string "x2"serialNumber ENDS WITH "x2"
All resources whose dnsName do not start with the string "hyd"dnsName NOT STARTS WITH "hyd"
All resources whose resource name contains the string "cluster"name LIKE "%cluster%"
All resources whose model does not end with "5801"model NOT ENDS WITH "5801"
Excludes resources whose name ends with "netapp"name NOT LIKE "%netapp"