Querying Nodes, Links and Networks
==================================

.. index:: Query Expressions; Nodes, Query Expressions; Links, Query Expressions; Networks
.. _element-expressions:

Documented here are the specifics of queries supported by the :doc:`Data
Management API </data_api/index>`.

The same query expressions can be used to perform :doc:`Traversal
Queries <traversal_query>` via the :doc:`Analysis
API </analysis_api/index>`. 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 <../api_reference.html#datamanagement>`__ which use queries
include ``FindNodes``, ``FindLinks`` and ``FindNodesAndLinks``. They
accept as requests either
`NodeQuery <../api_reference.html#are-v1-data_management-NodeQuery>`__,
`LinkQuery <../api_reference.html#are-v1-data_management-LinkQuery>`__,
or
`TraversalQuery <../api_reference.html#are-v1-data_management-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\ :sup:`63` - 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]``