Introduction

Advanced search provides the ability to find resources by leveraging a query language based on resource attributes.

Search queries allow:

  • Searching for resources by a combination of resource attributes.
  • Performing actions on selected resources.
  • Gaining insight into discovered resources.

Functionality

To form a query, start with the dollar sign ($) and then use a combination of the following:

  • Clause operators (for example, AND and OR)
  • Mathematical operators (for example, = and !=)
  • Key value pairs (for example, $key = value) .

Clause operators

Clause operators behave in the following manner:

  • An AND clause operator returns results if and only if both conjuncts (the key and value pair on either side of the AND operator) evaluate as true.
  • An OR clause operator returns results if either of the disjuncts (the key and value pair on either side of the OR operator) evaluates as true.

The following table shows the supported clause operators:

Clause Operators
OperatorFunction
ANDANDEvaluates two key value pairs and returns true if and only if both conjuncts are true .
OREvaluates two key value pairs and returns true if either disjuncts are true .
Parentheses ()Separates clauses into logical disjuncts or conjuncts. Used to assign a primary clause operator in the case of an AND/OR race condition.
Quotations ""For values in key value pairs that contain non-integer values.

For example: $key = "abc"

Mathematical operators

The following table shows the supported mathematical operators:

Mathematical Operators
OperatorFunction
!=Expresses whether either operand is not equal to each other.
=Expresses whether either operand is equal to each other.
CONTAINSString matching that searches for similar text strings in the value.
NOT CONTAINSString matching that searches for dissimilar text strings in the value.
ISEvaluates for binary values such as EMPTY or NOT EMPTY.
IS NULLEvaluates whether the token value does not contains any entry.
For example: $key: ""
IS NOT NULLEvaluates whether the token value contains any entry and is not empty.
For example: $key: "abc"

Key value pairs

For advanced search, key value pairs:

  • Represent a resource attribute and its value.
  • Are evaluated against the mathematical operators that combine them. For example, $key = value.
  • Two key value pairs are separated by either an AND or an OR.

For example, the following query syntax shows two key value pairs:

key = value AND $key = value

Attributes

The following table shows the available attributes:

.
Attributes
AttributesDescription
NativeIncludes all native OpsRamp resource attributes.
For example: hostname, resourcetype, approles.name
CustomIncludes all user assigned custom attributes.
For example: customattribute1, customattribute2

Note: Custom attributes are listed under $tags.name and $tags.value

Examples

Example: Using the AND operator

For the following query example:

  • If both conditions are met, the query evaluation is true and results are returned.
  • If the conditions are not met, the query evaluation is false and no results are returned.
$hostname = 123 AND $DNSName = www

Example: Using the OR operator

For the following query example:

  • If one condition is met, the query evaluation is true and results are returned.
  • If no conditions are met, the query evaluation is false and no results are returned.
$hostname = 123 OR $DNSName = www

Example: Using multiple clause operators

When queries contain multiple clause operations, the following occurs:

  1. The AND operator is evaluated first.
  2. The OR operator is evaluated second.

For example:

$hostname = 123 OR $DNSName = www AND $approle.name = SQL

Example: Assigning primary clause operators

To assign a primary clause operator in a query, use parentheses () to close the clause.

For example:

$hostname= 123 OR ($DNSName = www AND $approle.name = SQL)

Example: Using parentheses

When parentheses are added, the following occurs:

  • The query against the primary operator is evaluated first.
  • Clauses in the parentheses are treated as a single disjunct or conjunct.

In the following example:

  • A single truth value is assigned (true or false).

For example:

($DNSName = www AND $approle.name = SQL)

Assuming the following evaluations:

  • $hostname = 123 evaluates as true.
  • $DNSName = www AND $approle.name = SQL evaluates as true.

The expected result returns all resources for one of the following conditions:

  • $hostname = 123.
  • $DNSName = www and $approle.name = SQL.