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
| Operator | Description |
|---|---|
AND | Compare two expressions and return 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. 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.
| 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. |
Supported Attributes
The following resource attributes are supported in the OpsQL search:
| agentInstalled | agentVersion | aliasName | alternateIpAddress | availableAppName |
| availabilityState | clientId | clientName | deviceGroups | discoveryProfileId |
| dnsName | hasRelationship | hostName | id | identity |
| installedAppName | ipAddress | lastUpdated | location | macAddress |
| make | managementProfileId | model | name | nativeType |
| os | osType | resourceName | type | rootLocation |
| serialNumber | serviceGroups | state | tags | timezone |
The following alert attributes are supported in the OpsQL search:
| alertCriticalWarningDuration | alertType | clientId | clientName | component |
| correlatedAlertsCount | createdTime | currentState | description | dnsName |
| incidentId | id | inferenceId | ipAddress | isAvailabilityAlert |
| isInferenceAlert | metric | objectId | objectName | objectType |
| originalState | problemArea | repeatCount | source | status |
| subject | triggeredTime | updatedTime |
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
Resources
| os = "windows" AND availabilityState = "down" | All Windows os, which are currently down. |
| make = "Other" OR make IS NULL | All 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". |
| 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 >= 2 | Returns 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". |