Unsupported content

 

This version of the product is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Using the Query Language

This topic provides information and instructions for using the 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 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.

Example of a query

As a simple example, the following query retrieves all Host objects where the OS is Microsoft 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 all attributes 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 can 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.

Metadata LOOKUP expressions

LOOKUP is also used to retrieve a number of system metadata results:

LOOKUP versionReturns a single row of data with three columns: version number, release number, release code name
LOOKUP partitionsReturns a single column of data in which the rows list the names of the partitions within the datastore
LOOKUP partition_idsReturns two columns of data in which the rows list the names and IDs of the partitions within the datastore
LOOKUP countsReturns counts of nodes and relationships separated by node kind and partition

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 lowercase or mixed case.

Note

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 after processing.

PROCESSWITH

Used to summarize or modify the search results. See Results after processing.

SEARCH

Runs a search. See Using the 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 after 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.

Related topics

Key expressions

Query Language Functions

Working with queries


Was this page helpful? Yes No Submitting... Thank you

Comments