Skip to content
Kùzu
Blog

LIST and ARRAY

Kùzu supports two list-like data types: (i) variable-length lists, simply called LIST, and (ii) fixed-length lists, called ARRAY.

LIST

A LIST can contain an arbitrary number of values, but they must all be of the same type. The types inside a LIST can be any of those supported by Kùzu, including nested/complex types. Some examples are shown below:

  • STRING[] is a LIST of STRING values
  • INT64[] is a LIST of INT64 values
  • STRING[][] is a LIST of LIST of STRING values
  • MAP(STRING, STRING)[] is a LIST of MAP(STRING, STRING) values

Create a LIST

In Cypher, enclosing comma-separated values in square brackets will store the values as a LIST. The type of the elements is inferred by the query parser during the binding stage.

RETURN ["Alice", "Bob"] AS l;

Output:

---------------
| l           |
---------------
| [Alice,Bob] |
---------------

You can also create a LIST by explicitly calling the creation function as follows.

RETURN list_creation(1,2,3,4) AS l;

Output:

-------------
| l         |
-------------
| [1,2,3,4] |
-------------

UNWIND a LIST

UNWIND [[1,2], [3], [4, 5]] AS x
UNWIND x as y
RETURN y;

Output:

-----
| y |
-----
| 1 |
-----
| 2 |
-----
| 3 |
-----
| 4 |
-----
| 5 |
-----
(6 tuples)
(1 column)

ARRAY

ARRAY is a special case of LIST, in which the number of elements is fixed. Just like a LIST, all values in ARRAY must be of the same type. The number of elements is specified as an integer inside square brackets. Some examples are shown below:

  • INT64[256] is an ARRAY of INT64 values, with 256 elements
  • DOUBLE[512] is an ARRAY of DOUBLE values, with 512 elements

An ARRAY is useful for storing items like embeddings (for use in similarity search or in machine learning via our PyTorch Geometric integration), where the number of elements is fixed and known in advance.

You can create an array of any data type and size, including nested types using explicit casting. Some examples are listed below:

ARRAY of type INT64 and size 4

This is an example of creating an array with elements that are primitive types (integers).

RETURN CAST([3,4,12,11], 'INT64[4]');

Output:

--------------------------------------------
| CAST(LIST_CREATION(3,4,12,11), INT64[4]) |
--------------------------------------------
| [3,4,12,11]                              |
--------------------------------------------

ARRAY of LISTs of type INT64 and size 3

This is an example of creating an array whose elements are nested types that are themselves LISTs containing elements of a primitive type (integers).

RETURN CAST([[5,2,1],[2,3],[15,64,74]], 'INT64[][3]');

Output:

----------------------------------------------------------------------------------------------------
| CAST(LIST_CREATION(LIST_CREATION(5,2,1),LIST_CREATION(2,3),LIST_CREATION(15,64,74)), INT64[][3]) |
----------------------------------------------------------------------------------------------------
| [[5,2,1],[2,3],[15,64,74]]                                                                       |
----------------------------------------------------------------------------------------------------

UNWIND an ARRAY

UNWINDing an ARRAY works exactly as shown above for the LIST type.

UNWIND CAST([[1,2,3],[3],[4,5]], 'INT64[][3]') AS x UNWIND x AS y RETURN y;

Output:

-----
| y |
-----
| 1 |
-----
| 2 |
-----
| 3 |
-----
| 3 |
-----
| 4 |
-----
| 5 |
-----
(6 tuples)
(1 column)