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
| Operator | Description |
|---|---|
AND | Compares two expressions and returns true, if both expressions evaluate to true. |
OR | Performs 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.
| AND | This 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. |
|---|---|
| OR | This 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” |
| LIKE | Use 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 LIKE | Use 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 |
| CONTAINS | Use 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 CONTAINS | Use 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” |
| IN | Use 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 IN | Use 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 WITH | Search 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 WITH | Search 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 WITH | Search 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 WITH | Search 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 NULL | Used to test for empty values For example: make IS NULL |
|---|---|
| IS NOT NULL | Used to test for non-empty values For example: make IS NOT NULL |
Query Examples
| All Windows os, which are currently down | os = "windows" AND availabilityState = "down" |
| All resources where the make is either Other or null | make = "Other" OR make IS NULL |
| All resources where resource type is Server and in active state | resourceType = "server" AND state = "active" |
| All resources, which have resource type as Linux and do not have the agent installed | agentInstalled = "false" AND resourceType = "Linux" |
| All resources whose resource name contains the string "cent" and resource type is server | name 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" |