List functions¶
length()¶
Returns the number of elements in a list.
The function length() can also be used to return the number of characters in a string or the length of a path. For more information, see String function length() and Graph function length().
Null behavior: default
Function signature¶
length(l: LIST) -> INT32
Examples¶
Get the length of a list¶
RETURN length(LIST [1,2, null ,4]) AS len
Return:
+-----+
| len |
+-----+
| 4 |
+-----+
Get the length of a list that is null¶
RETURN length(null)
Return:
+--------------+
| length(null) |
+--------------+
| null |
+--------------+
Get the number of nodes in a path¶
'''
USE movie
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p)
RETURN length(a) AS len LIMIT 1
'''
Return:
+-----+
| len |
+-----+
| 2 |
+-----+
cardinality()¶
Returns the number of elements in a list or record.
The function cardinality() can also be used to return the number of elements in a path. For more information, see Graph function cardinality().
Null behavior: default
Function signature¶
cardinality(input: LIST | RECORD) -> INT32
Examples¶
Get the number of elements in a list¶
RETURN cardinality([2,2,3]) AS a
Return:
+---+
| a |
+---+
| 3 |
+---+
Get the number of elements in a record¶
RETURN cardinality({a:1, b:true, c:null, d:null, e: 1}) AS a
Return:
+---+
| a |
+---+
| 5 |
+---+
size()¶
Returns the number of elements in a list, unique elements in a set, key-value pairs in a map, or the total rows in a table.
Null behavior: default
Function signature¶
size(list) -> INT32
size(set) -> INT32
size(map) -> INT32
size(table) -> INT64
Examples¶
Get the number of elements in a list¶
RETURN size(LIST[1,2,3]) AS l
Return:
+---+
| l |
+---+
| 3 |
+---+
Get the number of unique elements in a set¶
RETURN size(SET{1,2,3,2,1}) AS s
Return:
+---+
| s |
+---+
| 3 |
+---+
Get the number of unique key-value pairs in a map¶
RETURN size(MAP{"a":1, "b":2, "c":3, "a":1}) AS m
Return:
+---+
| m |
+---+
| 3 |
+---+
Get the number of rows in a table¶
TABLE t {s, d, id} = (1, 10, 1), (2, 20, 2) RETURN size(t) as s
Return:
+---+
| s |
+---+
| 2 |
+---+
Note on table updates: If a single statement performs both an update to a table (e.g., via EXPORT) and a call to size(), the size() function returns the row count before the update is applied.
In the following example (based on the example dataset ), size(result_table) is called during the EXPORT process. Even though rows are being added to the table, the value stored in sz reflects the state of the table before the current set of nodes was exported.
CREATE TEMPORARY GRAPH IF NOT EXISTS #movie_temporary_graph AS COPY OF movie
"""
USE #movie_temporary_graph {
TABLE result_table TYPED TABLE {id INT, sz INT64}
MATCH (a)
PER NODE (a) {
EXPORT a.id, size(result_table) INTO result_table
}
FOR x IN result_table
RETURN DISTINCT x.sz AS ori_size, size(result_table) AS now_size
}
"""
Return:
+----------+----------+
| ori_size | now_size |
+----------+----------+
| 0 | 4589 |
+----------+----------+
head()¶
Returns the first element of a list.
Null behavior: default
Function signature¶
head(l: LIST) -> E
E refers to all data types.
Examples¶
Get the first element of a list¶
RETURN head(LIST [1,2,null,4]) AS item
Return:
+------+
| item |
+------+
| 1 |
+------+
Get the first node in a path¶
'''
USE movie
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p)
RETURN head(a) LIMIT 1
'''
Return:
+----------------------------------------------------------------------+
| head(a) |
+----------------------------------------------------------------------+
| (289159802779598849@Movie:Movie{id:648,name:"Beauty and the Beast"}) |
+----------------------------------------------------------------------+
tail()¶
Removes the first element of a list.
Null behavior: default
Function signature¶
tail(l: LIST) -> LIST
Examples¶
Remove the first element of a list¶
RETURN tail(LIST [1,2,null,4]) AS item
Return:
+------------+
| item |
+------------+
| [2,null,4] |
+------------+
Remove the first node in a list of nodes¶
'''
USE movie
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p)
RETURN tail(a) LIMIT 1
'''
Return:
+--------------------------------------------+
| tail(a) |
+--------------------------------------------+
| [(289042090610917378@User:Person{id:521})] |
+--------------------------------------------+
back()¶
Returns the last element of a list.
Null behavior: default
Function signature¶
back(l: LIST) -> E
E refers to all data types.
Examples¶
Get the last element of a list¶
RETURN back(LIST [1,2,null,4]) AS item
Return:
+------+
| item |
+------+
| 4 |
+------+
Get the last node in a path¶
'''
USE movie
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p)
RETURN back(a) LIMIT 1
'''
Return:
+------------------------------------------+
| back(a) |
+------------------------------------------+
| (288997977001820161@User:Person{id:229}) |
+------------------------------------------+
range()¶
Returns a list of integers that starts from the start value and ends at the end value, where the difference step between any two consecutive values is a constant.
The value of step can be any non-zero integer and defaults to 1.
Null behavior: default
Function signature¶
range(start: INT, end: INT [, step: INT]) -> LIST<INT>
Examples¶
Get a list of integers with the default step¶
RETURN range(-3,2) AS l
Return:
+------------------+
| l |
+------------------+
| [-3,-2,-1,0,1,2] |
+------------------+
Get a list of integers with a positive step¶
RETURN range(-3,2,2) AS l
Return:
+-----------+
| l |
+-----------+
| [-3,-1,1] |
+-----------+
Get a list of integers with a negative step¶
RETURN range(10,0,-2) AS l
Return:
+----------------+
| l |
+----------------+
| [10,8,6,4,2,0] |
+----------------+
Returns an error if the step is 0¶
RETURN range(10, 0, 0)
Return:
Error: [NR003]: Invalid function argument: 0
list_slice()¶
Returns a slice of a list that starts from the start value and ends at the end value.
Null behavior: default
Function signature¶
list_slice(l: LIST<E>, start: INT32, end: INT32 [, step: INT32]) -> LIST<E>
E refers to all data types.
Parameters¶
l: The source list to be sliced.start: The zero-based position in the list (l) where the slice begins.end: The zero-based position in the list (l) where the slice ends.step(optional): The difference between any two consecutive values, which should be any non-zero integer and defaults to1.
Positive values of the parameters start, end and step count from the start of the list, while negative values from the end.
Examples¶
Get a slice with a positive step¶
'''
LET input = ["hello", "my", "beautiful", "garden"]
RETURN list_slice(input, 0, 3, 2) AS a
'''
Return:
+-------------------+
| a |
+-------------------+
| [hello,beautiful] |
+-------------------+
Get a slice with a negative step¶
'''
LET input = range(1,6)
RETURN list_slice(input, 5, 3, -2) AS a
'''
Return:
+-------+
| a |
+-------+
| [6,4] |
+-------+
Get a slice with negative input parameters¶
'''
LET input = range(1,6)
RETURN list_slice(input, -3, -1) AS a
'''
Return:
+---------+
| a |
+---------+
| [4,5,6] |
+---------+
Returns an error if the step is zero¶
'''
LET input = range(1,6)
RETURN list_slice(input, 1, 4, 0) AS a
'''
Return:
Error: [NR003]: Invalid function argument: Slice step cannot be zero
trim()¶
Returns a list after removing a specified number of elements from the end of the list.
The function trim() can also be used to return a string with the leading, trailing, or both characters removed. For more information, see String function trim().
Null behavior: default
Function signature¶
trim(l: LIST, trim_num: INT32) -> LIST
Parameters¶
l: The source list.trim_num: The number of elements to be removed from the end of the source list. The number must be greater than or equal to 0 and less than the length of the source list.
Examples¶
Remove the last 2 elements from a list of integers¶
RETURN trim([1,2,3,4], 2) AS a
Return:
+-------+
| a |
+-------+
| [1,2] |
+-------+
Remove the last 2 elements from a nested list¶
RETURN trim([[1.1,2,3], [3.0, null],[4.4,5,6]],2) AS a
Return:
+-------------+
| a |
+-------------+
| [[1.1,2,3]] |
+-------------+
zip()¶
Combines two lists, element for element, into a list of lists.
Null behavior: default
Function signature¶
zip(l1: LIST, l2: LIST) -> LIST
Parameters¶
l1orl2: The source list. The elements inl1andl2must be of the same data type.- The elements at the same positions in
l1andl2are paired together. Ifl1andl2differ in length, the result matches the length of the shorter list, ignoring extra elements in the longer list.
Examples¶
Pair elements from two lists of integers¶
RETURN zip([1,2,3],[4,5,6]) AS res
Return:
+---------------------+
| res |
+---------------------+
| [[1,4],[2,5],[3,6]] |
+---------------------+
Pair elements from two lists of strings¶
RETURN zip(["The","is","not"],["apple","big"]) AS lis
Return:
+------------------------+
| lis |
+------------------------+
| [[The,apple],[is,big]] |
+------------------------+
list_distinct()¶
Removes duplicate values from the input list and then returns a new list.
Null behavior: default
Function signature¶
list_distinct(l: LIST) -> LIST
Examples¶
Remove duplicate values from a list of integers¶
RETURN list_distinct([1,2,3,2,1,3,1,2,null]) AS res
Return:
+--------------+
| res |
+--------------+
| [3,1,2,null] |
+--------------+
Remove duplicate values from a list of strings¶
RETURN list_distinct(["a","b","a","c","b"]) AS res
Return:
+---------+
| res |
+---------+
| [a,c,b] |
+---------+
list_except()¶
Returns a list of the elements in list x but not in list y, without duplicates.
Null behavior: default
Function signature¶
list_except(x: LIST, y: LIST) -> LIST
Examples¶
RETURN list_except([1,2,3,4,5],[3,4,4,4,4,4,null]) AS res
Return:
+---------+
| res |
+---------+
| [1,2,5] |
+---------+
list_intersect()¶
Returns a list of the elements in the intersection of list x and list y, without duplicates.
Null behavior: default
Function signature¶
list_intersect(x: LIST, y: LIST) -> LIST
Examples¶
RETURN list_intersect([null,1,2,3],[2,3,null,4]) AS res
Return:
+------------+
| res |
+------------+
| [null,2,3] |
+------------+
list_join()¶
Concatenates the elements of the input list using the delimiter and an optional string to replace nulls.
Null behavior: default
Function signature¶
list_join(l: LIST, delimiter: STRING, replace_null: STRING) -> STRING
delimiter: A string used to separate the elements in the input list.replace_null: An optional string used to replace null values in the input list. If not specified, null values are replaced with empty strings.
Examples¶
Join a list of integers with a delimiter¶
RETURN list_join([1,null,3], ",") AS res
Return:
+------+
| res |
+------+
| 1,,3 |
+------+
Join a list of strings with a delimiter and replace nulls with a string¶
RETURN list_join([1,2,null,4], "-", "?") AS res
Return:
+---------+
| res |
+---------+
| 1-2-?-4 |
+---------+
list_max()¶
Returns the maximum value of the input list. Returns null if the list contains any null value. For more information about the comparison between values, see Comparison predicate.
Null behavior: default
Function signature¶
list_max(l: LIST) -> E
Examples¶
Get the maximum value of a list of integers¶
RETURN list_max([-5,-3,-1,0,1,3,5]) AS res
Return:
+-----+
| res |
+-----+
| 5 |
+-----+
Get the maximum value of a list of strings¶
RETURN list_max(["a","b","c"]) AS res
Return:
+-----+
| res |
+-----+
| c |
+-----+
Return null if the list contains any null value¶
RETURN list_max([1,2,null,3,null,4]) AS res
Return:
+------+
| res |
+------+
| null |
+------+
list_min()¶
Returns the minimum value of the input list. Returns null if the list contains any null value. For more information about the comparison between values, see Comparison predicate.
Null behavior: default
Function signature¶
list_min(l: LIST) -> E
Examples¶
Get the minimum value of a list of integers¶
RETURN list_min([-5,-3,-1,0,1,3,5]) AS res
Return:
+-----+
| res |
+-----+
| -5 |
+-----+
Get the minimum value of a list of strings¶
RETURN list_min(["a","b","c"]) AS res
Return:
+-----+
| res |
+-----+
| a |
+-----+
Return null if the list contains any null value¶
RETURN list_min([1,2,null,3,null,4]) AS res
Return:
+------+
| res |
+------+
| null |
+------+
list_union()¶
Returns a list of the elements in the union of x and y, without duplicates.
Null behavior: default
Function signature¶
list_union(x: LIST, y: LIST) -> LIST
Examples¶
Get the union of two lists of integers¶
RETURN list_union([1,2,3],[3,4,5]) AS res
Return:
+-------------+
| res |
+-------------+
| [1,2,3,4,5] |
+-------------+
Get the union of two lists of strings¶
RETURN list_union(["a","b","c"],["c","d","e"]) AS res
Return:
+-------------+
| res |
+-------------+
| [a,b,c,d,e] |
+-------------+
list_sort()¶
Returns the list sorted by values in ascending order. For more information about the comparison between values, see Comparison predicate.
Null behavior: default
Function signature¶
list_sort(l: LIST) -> LIST
Examples¶
Sort a list of integers in ascending order¶
RETURN list_sort([3,1,null,2,null]) AS res
Return:
+-------------------+
| res |
+-------------------+
| [1,2,3,null,null] |
+-------------------+
Sort a list of strings in ascending order¶
RETURN list_sort(["b","a",null,"c"]) AS res
Return:
+--------------+
| res |
+--------------+
| [a,b,c,null] |
+--------------+
list_sum()¶
Returns the sum of all non-null elements of the list. If there is no non-null elements, returns 0.0. The behavior is similar to aggregation function sum().
Null behavior: default
Function signature¶
list_sum(l: LIST) -> UINT64 | INT64 | DOUBLE | DECIMAL
Examples¶
Get the sum of a list of integers¶
RETURN list_sum([1,2,3,4,5]) AS res
Return:
+-----+
| res |
+-----+
| 15 |
+-----+
Get the sum of a list of arbitrary-precision numbers¶
RETURN list_sum([1.1,2.2,3.3]) AS res
Return:
+-----+
| res |
+-----+
| 6.6 |
+-----+
remove_nulls()¶
Removes all null values from the input list.
Null behavior: default
Function signature¶
remove_nulls(l: LIST) -> LIST
Examples¶
Remove null values from a list of integers¶
RETURN remove_nulls([1,2,null,3,null,4]) AS res
Return:
+-----------+
| res |
+-----------+
| [1,2,3,4] |
+-----------+
Remove null values from a list of strings¶
RETURN remove_nulls(["a",null,"b","c",null]) AS res
Return:
+---------+
| res |
+---------+
| [a,b,c] |
+---------+