PGX 20.2.2
Documentation

Filter Expressions

Filter expressions are employed in the following use cases:

  • Path-Finding: Include only specific vertices and edges in a path
  • Sub-Graphs: Include only specific vertices and edges in a subgraph
  • Set creation: Create a vertex or edge set and include only specific vertices or edges

There are two types of filter expressions:

  • Vertex filters: Are evaluated on each vertex
  • Edge filters: Are evaluated on each edge, including the two vertices it connects.

These filter expressions will evaluate to true if the current edge or vertex matches the expression or to false if it does not. Filter expressions are stateless and side-effect free.

The short example below will evaluate to true for all edges where the source vertex's string property name is "PGX".

src.name = "PGX"

Syntax

Note: The keywords in the filter expression are case-insensitive.

Trivial Expressions

Always evaluates to true:

true

Always evaluates to false:

false

Constants

Legal constants are integer, long and floating point numbers of single and double precision as well as strings literals and true and false. Long constants need to be suffixed with l or L. Floating point numbers are treated as double precision numbers by default. To force a certain precision you can use f or F for single precision and d or D for double precision floating point numbers. String literals are UTF-8 character sequences, surrounded by single or double quotation marks.

25
4294967296L
0.62f
0.33d
"Double quoted string"
'Single quoted string'

Vertex/Edge Identifiers

Depending on the filter type, different identifiers are valid.

Vertex Filter

Vertex filter expressions have only one keyword that addresses the vertex in the current context.

vertex denotes the vertex that is currently being evaluated by the filter expression.

vertex

Edge Filter

Edge filter expressions have several keywords that addresses the edge or its vertices in the current context.

edge denotes the edge that is currently being evaluated by the filter expression.

edge

dst denotes the destination vertex of the current edge. dst is only valid in the subgraph context.

dst

src denotes the destination vertex of the current edge. src is only valid in the subgraph context.

src

Properties

Filter expressions can access the values of vertex/edge properties.

<id>.<property>

<id> should be any vertex/edge identifier (i.e. src, dst, vertex, edge). <property> should be the name of a vertex or edge property. Note: This has to be the name of an edge property if the identifier is edge. Otherwise it has to be a vertex property.

If the property name is a reserved name in the filter expression syntax or contains spaces, it needs to be quoted in single or double quotes.

The following code snippet accesses the 'cost' property of the source vertex.

src.cost

Temporal properties support values comparison (constants and property values) using special constructors. The default temporal formats are shown in the following table:

Property Type Constructor
DATE date ('yyyy-MM-dd HH:mm:ss')
LOCAL_DATE date 'yyyy-MM-dd'
TIME time 'HH:mm:ss'
TIME_WITH_TIMEZONE time 'HH:mm:ss+/-XXX'
TIMESTAMP timestamp 'yyyy-MM-dd HH:mm:ss'
TIMESTAMP_WITH_TIMEZONE timestamp 'yyyy-MM-dd HH:mm:ss+/-XXX'

The following expression accesses the property 'timestamp_withTZ' of an edge and checks if it is equal to 3/27/2007 06:00+01:00.

edge.timestamp_withTZ = timestamp '2007-03-27 06:00:00+01:00'

Bg-info

Note: Properties of type date can only be checked for equality. date type usage is deprecated since version 2.5, instead use local date or timestamp types that support all operations.

Methods

Filter expressions support a few functions.

Degree Functions

outDegree returns the number of outgoing edges of the vertex identifier. degree is a synonym for outDegree.

int <id>.degree()
int <id>.outDegree()

The following example determines whether the out-degree of the source vertex is greater than three:

src.degree() > 3

inDegree returns the number of incoming edges of the vertex identifier.

int <id>.inDegree()

Label Functions

hasLabel checks if a vertex has a label.

boolean <id>.hasLabel('<label>')

The following expressions checks whether a vertex has the label "city":

vertex.hasLabel('city')

label returns the label of an edge.

string <id>.label()

The following expression checks whether the label of an edge is "clicked_by":

edge.label() = 'clicked_by'

Relational Expressions

To compare values (e.g., property values or constants), filter expressions provide the comparison operators listed below. Note: Both == and = are synonyms.

==
=
!=
<
<=
>
>=

The following example checks whether the "cost" property of the source vertex is lower than or equals to 1.23.

src.cost <= 1.23

Vertex ID Comparison

It is also possible to filter for vertices with a specific vertex ID.

<id> = <vertex_id>

The following example determines whether the source vertex of an edge has the vertex ID "San Francisco"

src = "San Francisco"

Regular Expressions

Strings can be matched using regular expressions.

<string expression> =~ '<regular expression>'

The following example checks if the edge label starts with a lowercase letter and ends with a number:

edge.label() =~ '^[a-z].*[0-9]$'

The syntax followed for the pattern on the right-hand side, is that of Java REGEX .

Type Conversions

The following syntax allows converting the type of <expression> to <type>.

(<type>) <expression>

The following example converts the value of the 'cost' property of the source vertex to an integer value:

(int) src.cost

Boolean Expressions

Filter expressions can be composed to form other filter expressions. This can be done using the Boolean operators && (and), || (or) and ! (not). Note: Only boolean operands can be composed.

(! true) || false
edge.cost < INF && dst.visited = false
src.degree() < 10 || !(dst.visited)

Arithmetic Expressions

Any numeric expression can be combined using arithmetic expressions. The available arithmetic operators are: +, -, *, /, %. Note: These operators only work on numeric operands.

1 + 5
-vertex.degree()
edge.cost * 2 > 5
src.value * 2.5 = (dst.inDegree() + 5) / dst.outDegree()

Operator Precedence

Operator precedences are shown in the following list, from highest precedence to the lowest. An operator on a higher level is evaluated before an operator on a lower level.

  1. + (unary plus), - (unary minus)
  2. *, /, %
  3. +, -
  4. =, !=, <, >, <=, >=, =~
  5. NOT
  6. AND
  7. OR

Syntactic Sugar

both and any denote the source and destination vertex of the current edge. They can be used to express a condition that should be true for both or at least either one of the two vertices. These keywords are only valid in an edge filter expression. To use them in a vertex filter results in a runtime type-checking exception.

both
any

The filter expressions inside the following examples are equivalent:

both.property = 1
src.property = 1 && dst.property = 1
any.degree() > 1
src.degree() > 1 || dst.degree() > 1

Type System

Filter expressions are a very simple type system, as there are only the following 13 types:

  • integer (can be abbreviated in expressions with int)
  • long
  • float
  • double
  • boolean
  • string
  • date
  • time
  • time with timezone
  • timestamp
  • timestamp with timezone
  • vertex
  • edge

Conversions are only allowed from one numeric type to another numeric type (i.e. integer, float, double, long).

Comparisons require both sides to be of the same (or convertible) type.

Path Finding Filters

Filters can be used to limit the analyzed edges when searching for a shortest path between a source and destination vertex in a graph.

An edge filter expression is evaluated against each edge that is visited during the traversal of the graph. If the filter evaluates to false on an edge, this edge will be ignored and will not appear in the resulting shortest path.

It is also possible to use a vertex filter for path finding.

A vertex filter expression is evaluated against each vertex that is visited during the traversal of the graph, except for the source and destination vertex.

If the filter evaluates to false on a vertex, the edge to this vertex and all outgoing edges of the vertex will be ignored. The vertex will not appear in the resulting shortest path.

The source and destination vertex can be any vertex in the graph and the filter is not evaluated for them.

Edge Path Finding Filter Example

The examples below refer to the following graph, in which the shortest path between the vertices labeled "Start" and "Dest" is searched:

path finding filter example graph

The path finding algorithm is then run with the following edge filter:

any.color = 'Blue'

Here only edges that connect to at least one blue vertex are considered for the path:

path finding edge_filter example which results in the following shortest path: path finding edge_filter example

Vertex Path Finding Filter Example

If the path finding algorithm is run with the following vertex filter:

vertex.color = 'White'

And here only those edges that connect white vertices are considered on the path, except for the start and destination vertex which can be of any color:

path finding edge_filter example which results in the following shortest path: path finding edge_filter example

Subgraph Filters

Edge Filters

An edge filter expression is evaluated for each edge in the graph. The edge filter has access to the source and destination vertex of each edge and all of its properties.

If the filter expression evaluates to true, the edge and both the source and destination vertex will appear in the subgraph.

Vertex Filters

A vertex filter expression is evaluated for every vertex in the graph.

Every vertex for which the filter expression evaluates to true will appear in the subgraph.

Every edge connecting two vertices for which the expression evaluates to true will also appear in the subgraph.

Result Set Filters

Result set edge/vertex filters allow the creation of edge/vertex sets out of a given PGQL result set.

Vertex/Edge Collection Filters

Vertex/Edge collection filters allow the creation of edge/vertex filters out of a given vertex/edge collection.

Operations on Filter Expressions

Defining Filter Expressions

To define a new vertex filter, the following syntax is used:

var vertexFilter = VertexFilter.fromExpression("vertex.name = 'PGX'")
VertexFilter vertexFilter = VertexFilter.fromExpression("vertex.name = 'PGX'");
vertex_filter = VertexFilter("vertex.name = 'PGX'")

To define a new edge filter, the following syntax is used:

var edgeFilter = EdgeFilter.fromExpression("edge.cost > 5")
EdgeFilter edgeFilter = EdgeFilter.fromExpression("edge.cost > 5");
vertex_filter = EdgeFilter("edge.cost > 5")

Defining Result Set Vertex Filters

// Evaluates query on graph g to obtain a result set
var resultSet = g.queryPgql("SELECT x FROM MATCH (x) WHERE x.age > 24")
// Define a filter on the result set for the column "x"
var vertexFilter = VertexFilter.fromPgqlResultSet(resultSet, "x")
// Obtain a vertex set
var vertexSet = g.getVertices(vertexFilter)
// Evaluates query on graph g to obtain result set
PgqlResultSet resultSet = g.queryPgql("SELECT x FROM MATCH (x) WHERE x.age > 24");
// Define a filter on the result set for the column "x"
VertexFilter vertexFilter = VertexFilter.fromPgqlResultSet(resultSet, "x");
// Obtain a vertex set
VertexSet vertexSet = g.getVertices(vertexFilter);

Defining Result Set Edge Filters

// Evaluates query on graph g to obtain result set
var resultSet = g.queryPgql("SELECT e FROM MATCH ()-[e]->() WHERE e.weight >= 8")
// Define a filter on the result set for the column "e"
var edgeFilter = EdgeFilter.fromPgqlResultSet(resultSet, "e")
// Obtain an edge set
var edgeSet = g.getEdges(edgeFilter)
// Evaluates query on graph g to obtain result set
PgqlResultSet resultSet = g.queryPgql("SELECT e FROM MATCH ()-[e]->() WHERE e.weight >= 8");
// Define a filter on the result set for the column "e"
EdgeFilter edgeFilter = EdgeFilter.fromPgqlResultSet(resultSet, "e");
// Obtain an edge set
EdgeSet edgeSet = g.getEdges(edgeFilter);

Creating a Subgraph from PGQL Result Set

A subgraph can be obtained from a PGQL result set using result set filters.

Result Set Vertex Filter

// Evaluates query on graph g to obtain result set
var resultSet = g.queryPgql("SELECT x FROM MATCH (x) WHERE x.age > 24")
// Define a filter on the result set for the column "x"
var resultSetVertexFilter = VertexFilter.fromPgqlResultSet(resultSet, "x")
// Create a subgraph of g containing the matched vertices in the resultSet and the edges that connect them if any.
var newGraph = g.filter(resultSetVertexFilter)
// Evaluates query on graph g to obtain result set
PgqlResultSet resultSet = g.queryPgql("SELECT x MATCH (x) WHERE x.age > 24")
// Define a filter on the result set for the column "x"
VertexFilter resultSetVertexFilter = VertexFilter.fromPgqlResultSet(resultSet, "x")
// Create a subgraph of g containing the matched vertices in the resultSet and the edges that connect them if any.
PgxGraph newGraph = g.filter(resultSetVertexFilter)

Result Set Edge Filter

// Evaluates query on graph g to obtain result set
var resultSet = g.queryPgql("SELECT e FROM MATCH ()-[e]->() WHERE e.cost < 100")
// Define a filter on the result set for the column "e"
var resultSetEdgeFilter = EdgeFilter.fromPgqlResultSet(resultSet, "e")
// Create a subgraph of g containing the matched edges in the resultSet and their corresponding source and destination vertices.
var newGraph = g.filter(resultSetEdgeFilter)
// Evaluates query on graph g to obtain result set
PgqlResultSet resultSet = g.queryPgql("SELECT e FROM MATCH ()-[e]->() WHERE e.cost < 100")
// Define a filter on the result set for the column "e"
EdgeFilter resultSetEdgeFilter = EdgeFilter.fromPgqlResultSet(resultSet, "e")
// Create a subgraph of g containing the matched edges in the resultSet and their corresponding source and destination vertices.
PgxGraph newGraph = g.filter(resultSetEdgeFilter)

Defining Vertex/edge Collection Filters

// Obtain a vertex collection from an algorithm, query execution or any other way
VertexCollection<?> vertexCollection = ...
// Define a filter from the collection
var vertexFilter = VertexFilter.fromCollection(vertexCollection)
// Obtain a vertex collection from an algorithm, query execution or any other way
VertexCollection<?> vertexCollection = ...
// Define a filter from the collection
VertexFilter vertexFilter = VertexFilter.fromCollection(vertexCollection);

Defining Result Set Edge Filters

// Obtain an edge collection from an algorithm, query execution or any other way
EdgeCollection edgeCollection = ...
// Define a filter from the collection
var edgeFilter = EdgeFilter.fromCollection(edgeCollection)
// Obtain an edge collection from an algorithm, query execution or any other way
EdgeCollection edgeCollection = ...
// Define a filter from the collection
EdgeFilter edgeFilter = EdgeFilter.fromCollection(edgeCollection);

Creating a Subgraph from Vertex/edge Collection Filters

A subgraph can be obtained by using vertex or edge collection filters.

Vertex Collection Filter

// Obtain a vertex collection from an algorithm, query execution or any other way
VertexCollection<?> vertexCollection = ...
// Define a filter from the collection
var vertexFilter = VertexFilter.fromCollection(vertexCollection)
// Create a subgraph of g containing the matched vertices in the vertex collection and the edges that connect them if any.
var newGraph = g.filter(vertexFilter)
// Obtain a vertex collection from an algorithm, query execution or any other way
VertexCollection<?> vertexCollection = ...
// Define a filter from the collection
VertexFilter vertexFilter = VertexFilter.fromCollection(vertexCollection);
// Create a subgraph of g containing the matched vertices in the vertex collection and the edges that connect them if any.
PgxGraph newGraph = g.filter(vertexFilter);

Edge Collection Filter

// Obtain an edge collection from an algorithm, query execution or any other way
EdgeCollection edgeCollection = ...
// Define a filter from the collection
var edgeFilter = EdgeFilter.fromCollection(edgeCollection)
// Create a subgraph of g containing the matched edges in the collection and their corresponding source and destination vertices.
var newGraph = g.filter(edgeFilter)
// Obtain an edge collection from an algorithm, query execution or any other way
EdgeCollection edgeCollection = ...
// Define a filter from the collection
EdgeFilter edgeFilter = EdgeFilter.fromCollection(edgeCollection);
// Create a subgraph of g containing the matched edges in the collection and their corresponding source and destination vertices.
PgxGraph newGraph = g.filter(edgeFilter);

Combining Filter Expressions

Any filter expression used for subgraph filtering, can be combined with any other filter expression to form a new filter expression.

Filters can be combined using the following operations:

  • intersection
  • union

The intersection of two filters will only keep a vertex or edge, if both filters would accept it.

The union of two filters will keep a vertex or edge, if one of the filters would accept it.

In the following example an edge filter is intersected with a vertex filter. The resulting subgraph will only include vertices that have the name 'PGX' and will only include edges that have a cost greater than 5.

var edgeFilter = EdgeFilter.fromExpression("edge.cost > 5")
var vertexFilter = VertexFilter.fromExpression("vertex.name = 'PGX'")
var combinedFilter = edgeFilter.intersect(vertexFilter)
EdgeFilter edgeFilter = EdgeFilter.fromExpression("edge.cost > 5");
VertexFilter vertexFilter = VertexFilter.fromExpression("vertex.name = 'PGX'");
GraphFilter combinedFilter = edgeFilter.intersect(vertexFilter);
edge_filter = EdgeFilter("edge.cost > 5")
vertex_filter = VertexFilter("vertex.name = 'PGX'")
combined_filter = edge_filter.intersect(vertex_filter)

In contrast, the subgraph created by the union of those filters will include vertices that either have the name 'PGX' or that has an incoming or outgoing edge with a cost greater than 5. It will also include edges with a cost greater than 5, as well as edges for which the source and destination vertex have the name 'PGX'.

For more on subgraphs and combined filters, refer to the Create Subgraphs tutorial.