List Functions

Data Setup

SELECT * from cypher('graph_name', $$
CREATE (A:Person {name: 'Alice', age: 38, eyes: 'brown'}),
	(B:Person {name: 'Bob', age: 25, eyes: 'blue'}),
	(C:Person {name: 'Charlie', age: 53, eyes: 'green'}),
	(D:Person {name: 'Daniel', age: 54, eyes: 'brown'}),
	(E:Person {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}),
	(A)-[:KNOWS]->(B),
	(A)-[:KNOWS]->(C),
	(B)-[:KNOWS]->(D),
	(C)-[:KNOWS]->(D),
	(B)-[:KNOWS]->(E)
$$) as (result agtype);

keys

keys returns a list containing the string representations for all the property names of a vertex, edge, or map.

Syntax: keys(expression)

Returns:

An Agtype list containing string agtype elements

Arguments:

Name Description
path An expression that returns a vertex, edge, or map.

Considerations:

  • keys(null) returns null.

Query:

SELECT * from cypher('graph_name', $$
	MATCH (a)
	WHERE a.name = 'Alice'
	RETURN keys(a)
$$) as (result agtype);

A list containing the names of all the properties on the vertex bound to a is returned.

Result:

keys
["age", "eyes", "name"]
1 rows

range

range() returns a list comprising all integer values within a range bounded by a start value start and end value end, where the difference step between any two consecutive values is constant; i.e. an arithmetic progression. The range is inclusive, and the arithmetic progression will therefore always contain start and—depending on the values of start, step and endend.

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

Returns:

An Agtype list containing integer elements

Arguments:

Name Description
start An expression that returns an integer value.
end An expression that returns an integer value.
step A numeric expression defining the difference between any two consecutive values, with a default of 1.

Query:

SELECT *
FROM cypher('graph_name', $$
	RETURN range(0, 10), range(2, 18, 3)
$$) as (no_step agtype, step agtype);

Two lists of numbers in the given ranges are returned.

Result:

no_step step
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] [2, 5, 8, 11, 14, 17]
1 row

labels

labels returns a list containing the string representations for all the labels of a node.

Syntax: labels(vertex)

Returns:

An Agtype list containing String elements

Arguments:

Name Description
vertex An expression that returns a single vertex.

Considerations:

  • labels(null) returns null.

Query:

SELECT *
FROM cypher('graph_name', $$
	MATCH (a)
	WHERE a.name = 'Alice'
	RETURN labels(a)
$$) as (edges agtype);

A list containing all the labels of the node bound to a is returned.

Result:

edges
["Person"]
1 row

nodes

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

Syntax: nodes(path)

Returns:

An Agtype list containing vertex entities

Arguments:

Name Description
path An expression that returns an Agtype path.

Considerations:

  • nodes(null) returns null.

Query:

SELECT *
FROM cypher('graph_name', $$
	MATCH p = (a)-[]->(b)-[]->(c)
	WHERE a.name = 'Alice' AND c.name = 'Eskil'
	RETURN nodes(a)
$$) as (vertices agtype);

A list containing all the vertices in the path p is returned.

Result:

vertices
[{"id": 844424930131969, "label": "Person", "properties": {"age": 38, "eyes": "brown", "name": "Alice"}}::vertex, {"id": 844424930131970, "label": "Person", "properties": {"age": 25, "eyes": "blue", "name": "Bob"}}::vertex, {"id": 844424930131973, "label": "Person", "properties": {"age": 41, "eyes": "blue", "name": "Eskil", "array": ["one", "two", "three"]}}::vertex]
1 row

relationships

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

Syntax: relationships(path)

Returns:

An Agtype list containing edge entities

Arguments:

Name Description
path An expression that returns an Agtype path.

Considerations:

  • relationships(null) returns null.

Query:

SELECT *
FROM cypher('graph_name', $$
	MATCH p = (a)-[]->(b)-[]->(c)
	WHERE a.name = 'Alice' AND c.name = 'Eskil'
	RETURN relationships(p)
$$) as (edges agtype);

A list containing all the edges in the path p is returned.

Result:

edges
[{"id": 1125899906842640, "label": "KNOWS", "end_id": 844424930131989, "start_id": 844424930131988, "properties": {}}::edge, {"id": 1125899906842644, "label": "KNOWS", "end_id": 844424930131992, "start_id": 844424930131989, "properties": {}}::edge]
1 row

toBooleanList

toBooleanList() converts a list of values and returns a list of boolean values. If any values are not convertible to boolean they will be null in the list returned.

Syntax: toBooleanList(list)

Returns:

An agtype list containing the converted elements; depending on the input value a converted value is either a boolean value or null.

Considerations:

  • Any null element in list is preserved.

  • Any boolean value in list is preserved.

  • If the list is null, null will be returned.

  • If the list is not a list, an error will be returned.

Query:

SELECT * FROM cypher('expr', $$
    RETURN toBooleanList(["true", "false", "true"])
$$) AS (toBooleanList agtype);

Result:

tobooleanlist
[true, false, true]
1 row