PGX 20.1.1
Documentation
Documentation
Filter expressions are employed in the following use cases:
There are two types of filter expressions:
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"
Note: The keywords in the filter expression are case-insensitive.
Always evaluates to true:
true
Always evaluates to false:
false
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'
Depending on the filter type, different identifiers are valid.
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 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
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.
Filter expressions support a few 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()
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'
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
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"
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 .
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
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)
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 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.
+ (unary plus), - (unary minus)*, /, %+, -=, !=, <, >, <=, >=, =~NOTANDORboth 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
Filter expressions are a very simple type system, as there are only the following 13 types:
int)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.
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.
The examples below refer to the following graph, in which the shortest path between the vertices labeled "Start" and "Dest" is searched:
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:
which results in the following shortest path:
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:
which results in the following shortest path:
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.
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 edge/vertex filters allow the creation of edge/vertex sets out of a given PGQL result set.
Vertex/Edge collection filters allow the creation of edge/vertex filters out of a given vertex/edge collection.
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'");
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");
// 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);
// 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);
A subgraph can be obtained from a PGQL result set using result set filters.
// 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)
// 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)
// 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);
// 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);
A subgraph can be obtained by using vertex or 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) // 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);
// 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);
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:
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);
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.