Path-scoped predicate

A path-scoped predicate is a WHERE clause that is limited by a path. Like the path-scoped projection, the path-scoped predicate is a tool for solving problems that come up when you want to limit the search to find more relevant information, without losing the relationships between different pieces of information.

In a path-scoped predicate, the predicate is evaluated using a common path prefix. As an illustration, consider the following query:

SELECT *
FROM /network/device
WHERE interface/name='eth0' 
AND interface/oper_status = 1

This query will find all devices which have an interface named eth0 and an interface that has a status of 1. Note that it is not necesary for the name and the oper_status to be on the same interface. Path-scoped predicates allow us to write a query that will only find devices that have at least one interface named eth0, and which also have a status of 1.

interface/(name='eth0' AND interface/oper_status = 1)

The predicate clause name='eth0' AND interface/oper_status = 1 will be executed within the context of the path prefix interface.

Example 1: Limiting by `AND`

The following example requests all information about all devices with interfaces that match the given name and MAC address:

SELECT *
FROM /network/device
WHERE interface/(name='eth0' 
AND mac_address='01:01:02:03:04:05')

When run against the sample database, this query finds one device that has a matching interface:

row
  *
    system
      name 5627
      computed_vendor LANIER
      computed_model 5627
      computed_class printer
      computed_score 115
    os
      version LANIER 5627 5.20
    interface
      name eth0
      mac_address 01:01:02:03:04:05
      in_octets 1995335536
      out_octets 248342455
      oper_status 1

If you are surprised by these results, note that the path-scoped predicate limits the search to devices that have interfaces with matching parameters, but it doesn't limit the results. The projection (the SELECT * clause) asks for the results to include everything. Therefore, the results include both the matching and the unmatching interfaces because they are both part of the same device.

Example 2: Limiting by `OR`

In a second example of path-scoped predicate, the path projects through — or restricts — the WHERE clause. This query fetches all data from the /device node for any device that has matches any criteria:

SELECT * 
FROM /network/device
WHERE interface/(name = 'eth1' 
OR mac_address = '01:01:02:03:04:05')

When run against the sample database, this query returns results that include the entire sample database. This is because every device has an interface named eth1 except the Lanier printer, which has a MAC address of 01:01:02:03:04:05, and so matches one of the criteria:

row 
  * 
    network 
      device 
        system 
          name 5627 
          computed_vendor LANIER 
          computed_model 5627 
          computed_class printer 
          computed_score 115 
        os 
          version LANIER 5627 5.20 
        interface 
          name eth0 
          mac_address 01:01:02:03:04:05 
          in_octets 1995335536 
          out_octets 248342455 
          oper_status 1 
      device 
        system 
          name ESMITH 
          computed_vendor Intel 
          computed_class server 
          computed_score 10 
        os 
          version Linux 
        interface 
          name eth0 
          mac_address 02:A1:A2:A3:A4:A4 
          in_octets 1229592351 
          out_octets 1472928781 
          oper_status 1 
        interface 
          nameeth1 
          mac_address 03:A1:A2:A3:A4:A5 
          in_octets 0 
          out_octets 0 
          oper_status 0 
      device 
        system 
          name AJONES 
      . . .

To see the entire database, see sample database.

Example 3: Limiting searches to the wrong level

You might also request the same information as Example 1 by limiting the search to the interface node in the FROM clause, like this:

SELECT * 
FROM /network/device/interface                           
WHERE name = 'eth0' 
AND mac_address = '01:01:02:03:04:05'

The query works, but it results in a narrower hitlist than in Example 1. When run against the sample database, the query returns all the data about the interface, but no data about the device that it is on:

row
  *
    name eth0
    mac_address 01:01:02:03:04:05
    in_octets 1995335536
    out_octets 248342455
    oper_status 1

Example 4: Historical memory usage on a server

This query finds the history of memory usage on a specified server:

SELECT history(
  totalphysicalmemory, 
  totalvirtualmemory, 
  totalpagefilespace, 
  availablevirtualmemory, 
  from_time => '1 day ago', 
  resolution => '15 minutes'
  )
FROM /network/device/wmi/win32_logicalmemoryconfiguration 
WHERE ../win32_computersystem/name = 'NISSINGETTY'

Depending on the database, this query returns results similar to this:

row
  history(totalphysicalmemory, totalvirtualmemory, 
          totalpagefilespace, availablevirtualmemory, 
          from_time => 1 day ago, resolution => 15 minutes)
    history
      when2008-05-04T23:42:41.880614Z
      totalphysicalmemory1039640
      totalvirtualmemory2510656
      totalpagefilespace1471016
      availablevirtualmemory2063460
    history
      when2008-05-04T23:57:51.353958Z
      totalphysicalmemorynull
      totalvirtualmemorynull
      totalpagefilespacenull
      availablevirtualmemory2063460
    history
      when2008-05-05T00:13:00.827302Z 
    . . .

Path-scoped predicate

Example 1: Limiting by AND

Example 2: Limiting by OR

Example 3: Limiting searches to the wrong level

Example 4: Historical memory usage on a server

How do I find out more?

Example 1: Limiting by `AND`

Example 2: Limiting by `OR`