Skip to content

List functions

This topic describes the list functions supported by Nebula Graph. Some of the functions have different syntax in native nGQL statements and openCypher-compatible statements.

Precautions

  • Like SQL, the position index in nGQL starts from 1, while in the C language it starts from 0.
  • If the argument is NULL, the output is undefined.

General

range()

range() returns the list containing all the fixed-length steps in [start,end].

Syntax: range(start, end [, step])

  • step: Optional parameters. step is 1 by default.
  • Result type: List

Example:

nebula> RETURN range(1,9,2);
+-----------------+
| range(1,9,2)    |
+-----------------+
| [1, 3, 5, 7, 9] |
+-----------------+

reverse()

reverse() returns the list reversing the order of all elements in the original list.

Syntax: reverse(<list>)

  • Result type: List

Example:

nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids \
        RETURN reverse(ids);
+-----------------------------------+
| reverse(ids)                      |
+-----------------------------------+
| [487, 521, "abc", 4923, __NULL__] |
+-----------------------------------+

tail()

tail() returns all the elements of the original list, excluding the first one.

Syntax: tail(<list>)

  • Result type: List

Example:

nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids \
        RETURN tail(ids);
+-------------------------+
| tail(ids)               |
+-------------------------+
| [4923, "abc", 521, 487] |
+-------------------------+

head() returns the first element of a list.

Syntax: head(<list>)

  • Result type: Same as the element in the original list.

Example:

nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids \
        RETURN head(ids);
+-----------+
| head(ids) |
+-----------+
| __NULL__  |
+-----------+

last()

last() returns the last element of a list.

Syntax: last(<list>)

  • Result type: Same as the element in the original list.

Example:

nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids \
        RETURN last(ids);
+-----------+
| last(ids) |
+-----------+
| 487       |
+-----------+

reduce()

reduce() applies an expression to each element in a list one by one, chains the result to the next iteration by taking it as the initial value, and returns the final result. This function iterates each element e in the given list, runs the expression on e, accumulates the result with the initial value, and store the new result in the accumulator as the initial value of the next iteration. It works like the fold or reduce method in functional languages such as Lisp and Scala.

openCypher compatibility

In openCypher, the reduce() function is not defined. nGQL will implement the reduce() function in the Cypher way.

Syntax: reduce(<accumulator> = <initial>, <variable> IN <list> | <expression>)

  • accumulator: A variable that will hold the accumulated results as the list is iterated.
  • initial: An expression that runs once to give an initial value to the accumulator.
  • variable: A variable in the list that will be applied to the expression successively.
  • list: A list or a list of expressions.
  • expression: This expression will be run on each element in the list once and store the result value in the accumulator.
  • Result type: Depends on the parameters provided, along with the semantics of the expression.

Example:

nebula> RETURN reduce(totalNum = -4 * 5, n IN [1, 2] | totalNum + n * 2) AS r;
+-----+
| r   |
+-----+
| -14 |
+-----+

nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \
        RETURN  nodes(p)[0].age AS src1,  nodes(p)[1].age AS dst2,  \
        reduce(totalAge = 100, n IN nodes(p) | totalAge + n.age) AS sum;
+------+------+-----+
| src1 | dst2 | sum |
+------+------+-----+
| 34   | 31   | 165 |
| 34   | 29   | 163 |
| 34   | 33   | 167 |
| 34   | 26   | 160 |
| 34   | 34   | 168 |
| 34   | 37   | 171 |
+------+------+-----+

nebula> LOOKUP ON player WHERE player.name == "Tony Parker" YIELD id(vertex) AS VertexID \
        |  GO FROM $-.VertexID over follow \
        WHERE properties(edge).degree != reduce(totalNum = 5, n IN range(1, 3) | properties($$).age + totalNum + n) \
        YIELD properties($$).name AS id, properties($$).age AS age, properties(edge).degree AS degree;
+---------------------+-----+--------+
| id                  | age | degree |
+---------------------+-----+--------+
| "Tim Duncan"        | 42  | 95     |
| "LaMarcus Aldridge" | 33  | 90     |
| "Manu Ginobili"     | 41  | 95     |
+---------------------+-----+--------+

For nGQL statements

keys()

keys() returns a list containing the string representations for all the property names of vertices or edges.

Syntax: keys({vertex | edge})

  • Result type: List

Example:

nebula> LOOKUP ON player \
        WHERE player.age  > 45 \
        YIELD keys(vertex);
+-----------------+
| keys(VERTEX)    |
+-----------------+
| ["age", "name"] |
| ["age", "name"] |
+-----------------+

labels()

labels() returns the list containing all the tags of a vertex.

Syntax: labels(verte)

  • Result type: List

Example:

nebula> FETCH PROP ON * "player101", "player102", "team204" \
        YIELD labels(vertex);
+----------------+
| labels(VERTEX) |
+----------------+
| ["player"]     |
| ["player"]     |
| ["team"]       |
+----------------+

For statements compatible with openCypher

keys()

keys() returns a list containing the string representations for all the property names of vertices, edges, or maps.

Syntax: keys(<vertex_or_edge>)

  • Result type: List

Example:

nebula> MATCH (v:player{name:"Tim Duncan"})-[e]->() \
        RETURN keys(e);
+----------------------------+
| keys(e)                    |
+----------------------------+
| ["end_year", "start_year"] |
| ["degree"]                 |
| ["degree"]                 |
+----------------------------+

labels()

labels() returns the list containing all the tags of a vertex.

Syntax: labels(<vertex>)

  • Result type: List

Example:

nebula> MATCH (v)-[e:serve]->() \
        WHERE id(v)=="player100" \
        RETURN labels(v);
+------------+
| labels(v)  |
+------------+
| ["player"] |
+------------+

nodes()

nodes() returns the list containing all the vertices in a path.

Syntax: nodes(<path>)

  • Result type: List

Example:

nebula> MATCH p=(v:player{name:"Tim Duncan"})-->(v2) \
        RETURN nodes(p);
+-------------------------------------------------------------------------------------------------------------+
| nodes(p)                                                                                                    |
+-------------------------------------------------------------------------------------------------------------+
| [("player100" :player{age: 42, name: "Tim Duncan"}), ("team204" :team{name: "Spurs"})]                      |
| [("player100" :player{age: 42, name: "Tim Duncan"}), ("player101" :player{age: 36, name: "Tony Parker"})]   |
| [("player100" :player{age: 42, name: "Tim Duncan"}), ("player125" :player{age: 41, name: "Manu Ginobili"})] |
+-------------------------------------------------------------------------------------------------------------+

relationships()

relationships() returns the list containing all the relationships in a path.

Syntax: relationships(<path>)

  • Result type: List

Example:

nebula> MATCH p=(v:player{name:"Tim Duncan"})-->(v2) \
        RETURN relationships(p);
+-------------------------------------------------------------------------+
| relationships(p)                                                        |
+-------------------------------------------------------------------------+
| [[:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}]] |
| [[:follow "player100"->"player101" @0 {degree: 95}]]                    |
| [[:follow "player100"->"player125" @0 {degree: 95}]]                    |
+-------------------------------------------------------------------------+

Last update: August 12, 2022