Querying Nodes, Links and Networks

Documented here are the specifics of queries supported by the Data Management API.

The same query expressions can be used to perform Traversal Queries via the Analysis API. Refer to those documentation sections for more detail.

Summary

Certain data management endpoints support querying the properties of nodes, links and networks at particular revisions using a parsed query language. Remote procedure calls of the Data Management API methods which use queries include FindNodes, FindLinks and FindNodesAndLinks. They accept as requests either NodeQuery, LinkQuery, or TraversalQuery and embedded within each will be a query field that must contain a query expression.

Query Expression Format

The core expression consists of a JSON path, an operator and a comparison value in the following format:

<dotted.json.path> <operator> <value>

For example, with a JSON dict {"a": 5, "b": [1,2,{"c": 22}]}, the following query would successfully match:

b.2.c = 22

This query would also match but must be quoted due to its complexity.

b = "[1,2,{""c"": 22}]"

Quote characters (e.g. “) are escaped by repetition. (e.g. ””)

All Results Query Format

In order to explicitly request all existing data it is possible and recommended to use a special query which consists of an asterisk symbol *. Such a query will match all existing Nodes, Links or Networks (depending on the API that was triggered).

Operators and Reserved Symbols

The query language supports the following operators which will be further described. If these symbols appear in a JSON path or in a value, that identifier must be surrounded in quotation marks (e.g. "quoted text"). Quotation marks may be escaped by repetition ("value containing a "" mark").

~ | & ! ? ( ) . != = @ <= >= > < "

The query language also reserves two top-level ‘special’ paths. These are:

revision element_id

These can be used as paths in a query with any operators. For example, one might pick out the latest revision of an element with ID 44 by specifying

element_id = 44

or select the latest versions of a group of elements using the @ query form. e.g.

element_id @ [23,44,57,77]

Finally, one might filter elements that are newer than a specific revision with a query of the form:

revision > 2028

JSON paths

The dotted JSON path serves as an identifier for the object to be compared against. It takes the form of multiple identifiers or numbers joined by periods .. e.g.

name a.b.c settings.global.identifier config.array.5.property (you can use array indices in the JSON path)

Exists query

You can query nodes, links and networks that have a particular property defined using ? symbol.

? a.b.c

Grouping (parentheses)

Parentheses may be used to override order of evaluation. Normally, the ampersand (AND) operator takes precedence over the pipe (OR) operator.

a = 5 | b = 2 & c = 3

In the following query, parentheses are used to force the pipe to evaluate first.

(a = 5 | b = 2) & c = 3

Revision specifier

The tilde operator ~ allows the user to specify a ceiling on the “latest” revision which will be returned by the query. It must only be specified at the beginning of the query. e.g.

<revision id> ~ <query>

If the tilde operator is omitted, the “latest” revision is considered to be the largest possible revision number (2⁶³ - 1).

Logical operators (& and |)

The pipe | and ampersand & operators allow logical combination of queries. The pipe | symbol corresponds to the OR operation and the & symbol corresponds to the AND operation. For example, the following query would match all records which match BOTH query1 and query2.

<query1> & <query2>

Similarly, this query would match any objects which match query1, query2 or both.

<query1> | <query2>

It is also possible to chain queries. The ampersand operator takes precedence over the pipe operator.

<query1> | <query2> & <query3>

Negation (!)

If a query is prefixed with the NOT sign !, it is negated and will exclude those results rather than include them. e.g.

! b = 5, or ! (b = 5) ! (z = 22 | b = "[8,3,{""d"": 11}]" & c = "[1,2,{""c"": 68}]")

The NOT sign may be included immediately before a JSON path or before a parenthesis (.

Equality and Relational operators (!= = <= >= > < @)

The equality and relational operators are

• != “not equal to”

• = “equal to”

• <= “less than or equal to”

• >= “greater than or equal to”

• > “greater than”

• < “less than”

• @ “IN”

Most of these are intended for use with a single text or numerical value and will compare the LHS object (obtained from the JSON path) to the RHS object (provided by the user and SQL CAST to JSONB).

The at-sign (@) is a special case. The user should provide a bracketed list of JSONB objects to compare against.

a.b.c @ [1,2,3]