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]
Used to search in a named partition. | |
| Used to specify the kinds of nodes to find. |
Used to filter the current set of nodes. | |
Used to define a traverse from one node to another in order to access attributes and relationships from related nodes. | |
Used to define a sort order for the results. | |
Used to define the information to return in the search results. | |
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 version | Returns a single row of data with three columns: version number, release number, release code name |
LOOKUP partitions | Returns a single column of data in which the rows list the names of the partitions within the datastore |
LOOKUP partition_ids | Returns two columns of data in which the rows list the names and IDs of the partitions within the datastore |
LOOKUP counts | Returns 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.
| A string terminated by an unescaped ' character. Cannot include newlines. |
| A string terminated by an unescaped " character. Cannot include newlines. |
| A string terminated by an unescaped ''' character sequence. Can include newlines. |
| 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:
| Backslash characters do not resolve to escape sequences. |
| Backslash characters do not resolve to escape sequences. Intended for use in |
| Backslash characters do not resolve to escape sequences. Intended for use with filesystem paths. |
| Expanded into a regular expression suitable for matching a UNIX command by prefixing with |
| Expanded into a regular expression suitable for matching a Windows command by prefixing with |
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:
| Logical operator when defining conditions. See Logical Operators. |
| Modifier defining default heading shown. See The SHOW Clause. Use in function result naming. See Name binding. |
| Used in ORDER BY clause. See Ordering. |
| Used in Definition Boolean condition. See Conditions. |
| Changes sort order from ascending to descending. See Ordering. |
| Used for repeated traversals. See Traversals. |
| Used to 'explode' the items in the list into multiple output rows. See Explode. |
| Used to modify behavior with destroyed nodes, result segmentation and other characteristics. See Search Flags. |
| Used in substring and subword Boolean conditions. See Conditions. |
| 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. |
| Used in definition Boolean conditions. See Conditions. |
| Deprecated synonym for |
| Used to show localized column headings in queries. See The SHOW Clause. |
| Finds a single node. |
| Used in Boolean conditions when matching regular expressions. See Conditions. |
| Returns number of nodes when performing traverses. See NODECOUNT Expressions. |
| Returns a list of the traversed-to nodes. See NODECOUNT Expressions. |
| Used in substring and subword Boolean conditions. See Conditions. Logical operator when defining conditions. See Logical Operators. |
| Logical operator when defining conditions. See Logical Operators. |
| Used in ORDER BY clause. See Ordering. |
| Used with STEP when performing traversals, to move from a set of relationships to a set of nodes. See Traversals. |
| Used to summarize or modify the search results. See Results after processing. |
| Used to summarize or modify the search results. See Results after processing. |
| Runs a search. See Using the Query Language. |
| Defines the columns to return in the search results. See The SHOW Clause. |
| Used with IN and OUT when performing traversals, to move between nodes and relationships. See Traversals. |
| Used in substring Boolean condition. See Conditions. |
| Used in subword Boolean condition. See Conditions. |
| Used to show the taxonomy-defined summary list in the search results. See The SHOW Clause. |
| Used to order by the taxonomy-defined label and to refer to named attribute lists. See Ordering. |
| Used to traverse from one node to another in order to access attributes and relationships from related nodes. See Traversals. |
| Filters the current set of nodes according to a Boolean condition. See Logical and arithmetic expressions. |
| 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.
Comments
Log in or register to comment.