Paths

Use paths to locate trees, sub-trees, and nodes in the PQL database. There are two types of path, simple path which does not contain any conditions, and conditional path (or just path) which contains conditions. Paths in PQL can be considered analagous to paths in a file system, with one significant difference: a single path in PQL can refer to many sub-trees or nodes across the PQL database.

Syntax

`simple_path`	`::=`	`[/] identifier *`
`path`	`::=`	`[/] path_component *`
`path_component`	`::=`	`.. \| identifier \| identifier[boolean_expression]`

Description

The elements of a path are:

Identifiers

A path is a sequence of identifiers that specify tree nodes by name, separated by slashes, very much like directory paths in file systems. Paths can be absolute or relative. Absolute paths begin with a slash which indicates that the path starts at the root of the PQL database. Relative paths begin with an identifier, which indicates that the path starts relative to a tree node which is specified another way, depending on the context in which the tree is used.

Paths must not end with a trailing slash.

The .. (parent) operator can be used at the start of any path in a statement to move to the parent node, but never in the middle of a path. Multiple sequences of the .. parent operator can be used to refer to the ancestors. The .. parent operator can only be used with relative paths.

Conditions

If the identifier in a path can be augmented with a condition in square brackets. If a condition is present, then only trees with the same name as the identifier and for which the boolean_expression evaluates to true, are matched by the path.

Paths are used throughout PQL to refer to sub-trees or nodes in the PQL database. Paths can be considered as being evaluated in left-to-right sequential fashion, at each point in the path navigating down one level in the tree where the name of the node matches the identifier in the path. Since it is possible for a tree to have multiple children with the same name, it is possible for a path to refer to multiple branches in the tree, and thus ultimately many nodes.

Conditions can be used to restrict exactly which nodes a path refers to. These conditions work in a similar way to the predicate in a PQL SELECT statement and so conditional paths can be thought of as a shorthand way of writing predicates.

Examples

Example 1. How paths select nodes

In PQL, paths must be used in the context of a statement (such as SELECT, MERGE, or UPDATE), but these 5 examples show simply how paths select nodes, and so are not valid PQL statements by themselves.

foo

/foo/bar/baz

foo/bar

/foo/bar[a = 1]/baz

../../bar

Example 2. Using the .. parent operator

PQL supports the .. parent operator to move to the parent node when writing paths in queries. Paths can begin with any number of .. sequences, such as:

 SELECT ../win32_computersystem/name as "System", 
 Command, Location, Name, User 
 FROM /network/device/wmi/win32_startupcommand 
 ORDER BY 1, 2

You can use the .. parent operator anywhere that you can use a path, including the predicate:

 SELECT ../win32_computersystem/name as "System", 
 Command, Location, Name, User 
 FROM /network/device/wmi/win32_startupcommand 
 WHERE ../../interface/inet/ip_address = '10.10.10.5'

Note: The .. parent operator can only be used at the start of a path, never in the middle. So this is not valid work:

 SELECT /network/device/wmi/../interface/mac_address

Path types

Paths are the basis of many aspects of PQL and are also have some specialized variations which can be used to select nodes from the PQL database in interesting ways. The types of paths include:

Absolute paths — Paths that start from the root, such as /network/device.
Relative paths — Paths that do not start from the root, such as interface/name or interface/mac_address.
Qualified Paths — Paths that are restricted with conditions, such as interface[name = 'eth0']/mac_address.
Unqualified paths — Paths that have no conditions, such as interface/name or interface/mac_address.
Path-scoped predicate — A WHERE clause that is limited by a path, such as: WHERE interface/(name = 'eth0' and mac_address = '01:01:02:03:04:05').
Path-scoped projection — A SELECT clause that is limited by a path, such as SELECT interface/name and mac_address).