Documentation is now available for the Fall 2020 Update release!

Provides rules and syntax for using the Advance Resource Search query language feature.

## Introduction

Advanced search provides the ability to find resources by leveraging a query language based on resource attributes. By default, the resource attributes displayed on the Resources page are inherited.

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
`AND`Evaluates two key value pairs and returns true if and only if both conjuncts are true .
`OR`Evaluates 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.
`CONTAINS`String matching that searches for similar text strings in the value.
`NOT CONTAINS`String matching that searches for dissimilar text strings in the value.
`IS`Evaluates for binary values such as EMPTY or NOT EMPTY.
`IS NULL`Evaluates whether the token value does not contains any entry.
For example: `\$key: ""`
`IS NOT NULL`Evaluates 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"`.
• 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).

``(\$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"`.