toList

Converts a DataFrame into a List of data class instances, one per row, in the order of the rows.

toList()
toListOf<T>()

toListOf<T>() creates instances of the T you give in the call, whatever the type argument of the DataFrame is. Use it in most cases. toList() creates instances of the type argument of the DataFrame, so use it only when this type argument is known to be a data class.

Related operations: toDataFrame (the reverse operation), convertTo, toMap.

More info: Interop with Collections

How rows become objects

The rules are the same for toList, toListOf, toSequence and toSequenceOf.

T has to be a data class. An interface does not work, even one marked with @DataSchema. A generic data class works too, for example, Pair<String, Int>.
Each instance is created by the primary constructor of T. Each constructor parameter gets the value of the column with the same name, or with the name given in @ColumnName. Names are case-sensitive.
The order of the columns does not matter, and columns that match no parameter are ignored.
A parameter with a default value gets this value when there is no column for it.
When a column type differs from the parameter type, the values are converted the same way as in convertTo, for example, from Int to Long.
A ColumnGroup becomes a nested data class, and a FrameColumn becomes a List of data class instances, or a DataFrame. A frame that goes into a DataFrame<S> parameter is converted to the schema of S the same way as in convertTo, and its other columns stay. A frame that goes into a DataFrame<*> parameter is passed as it is.

An exception is thrown when:

T is not a data class;
there is no column for a constructor parameter without a default value;
a column has null values, but its parameter is not nullable;
a value cannot be converted to the parameter type;
a frame cannot be converted to the schema of its DataFrame<S> parameter, for example, because a column of S is missing.

toList

toList() creates instances of the type argument of the DataFrame, following the rules in How rows become objects.

Use it only when the type argument of the DataFrame is known to be a data class. On a DataFrame<*>, such as the result of dataFrameOf or of reading a file, toList() throws an exception, because there is no data class to create. With the compiler plugin, the same happens even right after toDataFrame() on a list of data class instances: the plugin gives the result a generated type argument, which is not a data class. In these cases, use toListOf, or cast the DataFrame to a data class first:

data class Input(val a: Int, val b: Int)

val df = dataFrameOf("a", "b")(1, 2, 3, 4)

df.cast<Input>().toList()

Output:

[Input(a=1, b=2), Input(a=3, b=4)]

toListOf

toListOf<T>() creates instances of the T given in the call, following the rules in How rows become objects. Use it in most cases. The type argument of the DataFrame does not matter, so it works on a DataFrame<*> too, and on a DataFrame whose type argument is generated by the compiler plugin.

Here the fullName column group becomes a nested FullName:

val df = dataFrameOf("name", "lastName", "age")("John", "Doe", 21)
    .group("name", "lastName").into("fullName")

data class FullName(val name: String, val lastName: String)

data class Person(val fullName: FullName, val age: Int)

df.toListOf<Person>()

Output:

[Person(fullName=FullName(name=John, lastName=Doe), age=21)]

toSequence and toSequenceOf

toSequence() and toSequenceOf<T>() are the same as toList() and toListOf<T>(), but they return a Sequence. The rules in How rows become objects apply to them too.

toSequence()
toSequenceOf<T>()

The columns are matched and converted when the function is called, so the exceptions are thrown right away. The instances are created only when the sequence is iterated, one per row that is read, and each iteration creates them again. Here only the first row becomes an object. The dataframes and the data classes are the ones from the toList and toListOf examples:

df.cast<Input>().toSequence().first()

Output:

Input(a=1, b=2)

df.toSequenceOf<Person>().first()

Output:

Person(fullName=FullName(name=John, lastName=Doe), age=21)

15 October 2026