Overview

In UQL, a filter is used to set conditions for retrieving nodes and edges based on their schemas and properties.

Filters are implemented within the methods of query commands that represent nodes or edges. For example, the nodes() method of the find() command, or the edge_filter() method of the ab() command.

Syntax

A filter is an expression enclosed within curly braces { }. Typically, it involves references of the schemas and properties of nodes and edges.

Example: Find @user nodes and @movie nodes with a rating above 3.

find().nodes({@user || @movie.rating > 3}) as n
return n{*}

A filter evaluates either a boolean value or null. It determines the validity of a node or edge by returning true when the filter condition is met.

In cases where the expression of the filter does not yield a boolean value or null, the result is converted to either true or false based on its type and value:

Example: Find @user nodes whose ages, when subtracted by 33, result in a non-zero value.

find().nodes({@user.age - 33}) as n
return n{*}

Examples

General Filter

In any query clause, you can filter nodes and edges by comparing their schemas and properties with some constant values and/or aliases.

find().nodes({@user.registeredOn >= "2021-09-01 09:00:00"}) as u1
with max(u1.age) as maxAge
find().nodes({@user.age == maxAge}) as u2
return u2

n(as start).e()[3].n({level == start.level}) as p
return p

Note: The second node template n() calls the alias defined in the first node template.

Generally, properties referenced in the filter can be used directly without any indexing. However, different types of indexing should be contemplated when seeking to expedite the query process. Please refer to Acceleration for more information.

Inter-Step Filter

In a template-based query clause, you can employ the system aliases prev_n and prev_e to facilitate inter-step filtering.

n({@card}).e({@transfersTo.time > prev_e.time})[3].n({@card}) as p
return p

The properties referenced by prev_n and prev_e (such as the time property in the example) must be LTE-ed for acceleration.

The methods path_ascend() and path_descend() in certain path query commands like ab() serve the same purpose of inter-step comparison, and they necessitate the subject property to be LTE-ed as well. However, the input for these methods does not take the form of a filter.

ab().src({_id == "A"}).dest({_id == "E"}).depth(:3).path_ascend(@default.weight) as p
return p{*}

Full-Text Filter

In any query clause, nodes and edges can be filtered using a created full-text index.

find().nodes({~content CONTAINS "graph computing parallel"}) as n
return n{*}