Filter Steps are CPGQL Steps which filter nodes in a traversal according to a criterion. Ocular supports four Generic Filter Steps which can be added to any other step, and number of specific filter steps called Property Filter Steps which can be used on nodes of a certain type.
The Generic Filter Steps are
whereNot. The Property Filter Steps for each node type correspond to the Property Directives it has defined.
We will look at the behaviour of each of these steps while analyzing a simple program named
Property Filter Steps
Property Filter Steps are Filter Steps which continue a traversal if the properties of the nodes they point to pass a certain criterion.
For example, to query the Code Property Graph for all CALL nodes which have the string
exit as the value for their NAME property, and return their CODE property:
The criterion is unique to every Property Filter Step. In the case of the
name Property Filter Step of the
call Node-Type Step, its criterion is a string that represents a regular expression; that is, all following queries will deliver the same result for the
Just like all other Filter Steps, Property Filter Steps can be chained together:
Unlike Property Directives, Property Filter Steps are usually greater in number than the properties defined on a node type. Most Property Filter Steps have their negated version available:
where Step is a Filter Step which continues a traversal for all nodes which pass its criterion. The criterion of the
where step is represented by an expression which has one argument, a variable that points to the node matched in the previous step, and which returns a boolean. For example, suppose you'd like to query the Code Property Graph of the
X42 program for all CALL nodes which have
exit as the value of their NAME property, and return their CODE property in a list:
where steps can be chained together:
And their expression can contain any combination of boolean statements:
One helpful trick is to use the shorthand
_ operator in
where expressions, which points to the single argument that is passed into it, that is, the node.
filter Step is a Filter Step (
ಠ~ಠ) which continues a traversal for all nodes which pass its criterion. The expression representing the criterion takes in one argument, a variable that represents the traversal of the previous step, and returns another traversal. Say you'd like to query the Code Property Graph of the
X42 program again for all CALL nodes which have
exit as the value of their NAME property, and return the value of their CODE property in a list:
filter's expression supports traversals of any length:
And just like
where, it supports chaining:
filterNot is the inverse operation of the
It supports chaining as well:
And traversals of any length: