Query Language

Search expressions

The query language provides a natural mechanism for searching and processing the data model. The basic format of a search expression is:
SEARCH [in partition] <kinds> [where clause] [traversals] [ordering] [show clause] [processing]

`[in partition]`	Used to search in a named partition.
`<kinds>`	Used to specify the kinds of nodes (objects) to find.
`[where clause]`	Used to filter the current set of nodes.
`[traversals]`	Used to define a traverse from one node to another in order to access attributes and relationships from related nodes.
`[ordering]`	Used to define a sort order for the results.
`[show clause]`	Used to define the information to return in the search results.
`[processing]`	Used to post-process the results of a search.

There is a limit to the query length and complexity. For example: Using more that 200 expressions in the where clause may lead to an error.

These are described in detail in the following sections.

Examples

As a simple example, the following query retrieves all Host objects where the operating system is Windows. It displays each host's name and how much RAM it has; the results are sorted by name:

SEARCH Host WHERE os_type = 'Windows' ORDER BY name SHOW name, ram

The following example finds all nodes that mention Microsoft:

SEARCH * WHERE * HAS SUBWORD "microsoft"

In this example, both the ordering and show clauses are absent. The search service therefore uses the taxonomy definitions to choose defaults. The results are ordered by the label attributes of each node kind found and the attributes to show are set according to the corresponding summary lists. (If no definitions are given in the taxonomy for a node kind, the results are not sorted and just the node ids are shown.)

The following example searches the _System partition for Users:

search in "_System" FoundationUser show username

When writing search queries, you should be aware that an unconstrained search may have a serious performance impact on the appliance. For example, SEARCH * would return details of every node in the entire datastore!

The sets resulting from searches (and traversals) can be named and combined using set operations. This is described in Results Post Processing.

LOOKUP expressions

Instead of performing a SEARCH, a search can be performed with a LOOKUP that simply finds one or more nodes with their node id:

An example finding a single node:

LOOKUP "845981da735bb875d1246b496e486f7374" SHOW hostname

An example finding multiple nodes:

LOOKUP "845981da735bb875d1246b496e486f7374", "88ee6097f60d047c3557dc4a6e486f7374", "88edfa88f60d047c3557dc4a6e486f7374" SHOW hostname

A LOOKUP cannot have a WHERE clause. It is usually used in conjunction with one or more traversals.

Comments

Search queries can contain comments on lines starting // . Everything is ignored from // to the end of line.

Literal strings

Literal strings used in search expressions can take a number of forms.

`'string'`	A string terminated by an unescaped ' character. Cannot include newlines.
`"string"`	A string terminated by an unescaped " character. Cannot include newlines.
`'''string'''`	A string terminated by an unescaped ''' character sequence. Can include newlines.
`"""string"""`	A string terminated by an unescaped """ character sequence. Can include newlines.

In normal string literals, escape characters start with backslash \ characters. Usual C-style escapes are permitted.
Strings can be 'qualified' to change their interpretation, by prefixing the string literal with a word as follows:

`raw`	Backslash characters do not resolve to escape sequences.
`regex`	Backslash characters do not resolve to escape sequences. Intended for use in `MATCHES` expressions.
`path`	Backslash characters do not resolve to escape sequences. Intended for use with filesystem paths.
`unix_cmd`	Expanded into a regular expression suitable for matching a Unix command by prefixing with `'\b'` and suffixing with `'$'`.
`windows_cmd`	Expanded into a regular expression suitable for matching a Windows command by prefixing with `'(?i)\b'` and suffixing with `'\.exe$'`.

Keywords

In this document, query language keywords appear in upper case to make them stand out. Keywords are actually case insensitive, so they can be specified in lower case or mixed case. All other parts of query expressions are case sensitive.

To use an identifier that clashes with a keyword, prefix it with a $ character to prevent the parser reporting a syntax error:

SEARCH * WHERE $search = 123

For backwards-compatibility, keywords can also be escaped with the ~ character.
The keywords are as follows:

`AND`	Logical operator when defining conditions. See Logical Operators.
`AS`	Modifier defining default heading shown. See The SHOW Clause. Use in function result naming. See Name binding.
`BY`	Used in ORDER BY clause. See Ordering.
`DEFINED`	Used in Definition Boolean condition. See Conditions.
`DESC`	Changes sort order from ascending to descending. See Ordering.
`EXPAND`	Used for repeated traversals. See Traversals.
`EXPLODE`	Used to 'explode' the items in the list into multiple output rows. See Explode.
`FLAGS`	Used to modify behavior with destroyed nodes, result segmentation and other characteristics. See Search Flags.
`HAS`	Used in substring and subword Boolean conditions. See Conditions.
`IN`	Used in containment Boolean conditions. See Conditions. Used with STEP when performing traversals, to move from a set of nodes to a set of relationships. See Traversals.
`IS`	Used in definition Boolean conditions. See Conditions.
`LIKE`	Deprecated synonym for `MATCHES`.
`LOCALE`	Used to show localized column headings in queries. See The SHOW Clause.
`LOOKUP`	Finds a single node.
`MATCHES`	Used in Boolean conditions when matching regular expressions. See Conditions.
`NODECOUNT`	Returns number of nodes when performing traverses. See NODECOUNT Expressions.
`NODES`	Returns a list of the traversed-to nodes. See NODECOUNT Expressions.
`NOT`	Used in substring and subword Boolean conditions. See Conditions. Logical operator when defining conditions. See Logical Operators.
`OR`	Logical operator when defining conditions. See Logical Operators.
`ORDER`	Used in ORDER BY clause. See Ordering.
`OUT`	Used with STEP when performing traversals, to move from a set of relationships to a set of nodes. See Traversals.
`PROCESS`	Used to summarize or modify the search results. See Results Post-Processing.
`PROCESSWITH`	Used to summarize or modify the search results. See Results Post-Processing.
`SEARCH`	Runs a search. See Query Language.
`SHOW`	Defines the columns to return in the search results. See The SHOW Clause.
`STEP`	Used with IN and OUT when performing traversals, to move between nodes and relationships. See Traversals.
`SUBSTRING`	Used in substring Boolean condition. See Conditions.
`SUBWORD`	Used in subword Boolean condition. See Conditions.
`SUMMARY`	Used to show the taxonomy-defined summary list in the search results. See The SHOW Clause.
`TAXONOMY`	Used to order by the taxonomy-defined label and to refer to named attribute lists. See Ordering.
`TRAVERSE`	Used to traverse from one node to another in order to access attributes and relationships from related nodes. See Traversals.
`WHERE`	Filters the current set of nodes according to a Boolean condition. See Logical and arithmetic expressions.
`WITH`	Used with the PROCESS keyword to specify the post processing function to use. See Results Post-Processing. Used in function result naming. See Name binding.

Kind Selection

A search expression must specify the kinds of nodes to search. The specification must either be a single * character, meaning to search all kinds, or a comma-separated list of node kinds. The majority of queries specify a single kind.

BMC Software