gather

Reshapes the DataFrame by gathering specified columns into two columns: keys and values (or into just one of them).

By default, the "key" column contains the names of the gathered columns, and the "value" column holds the corresponding cell values. The original columns selected for gathering are removed from the result, while all other columns remain unchanged — except that their values are duplicated for each generated key-value pair.

This function does not perform the reshaping immediately — it returns a Gather object, which serves as an intermediate step. Before applying the final transformation, you may:

• filter values (where, notNull);

• explode list-columns (explodeLists);

• transform keys (mapKeys) or values (mapValues);

• cast the value type (cast).

Finally, reshape the DataFrame using one of the following methods:

• into

• keysInto

• valuesInto

Each of these methods returns a new reshaped DataFrame.

This operation is the reverse of pivot.

This can include column groups and nested columns.

For more information: See gather on the documentation website.

See Grammar.

This Gather Overload

Select or express columns using the Columns Selection DSL.

This DSL is initiated by a Columns Selector lambda, which operates in the context of the Columns Selection DSL and expects you to return a SingleColumn or ColumnSet (so, a ColumnsResolver). This is an entity formed by calling any (combination) of the functions in the DSL that is or can be resolved into one or more columns.

The Columns Selection DSL allows using Extension Properties for specifying columns type- and name-safe.

Check out: Columns Selection DSL Grammar

See Column Selectors on the documentation website.

Examples

// Gather `resultA` and `resultB` columns into a single "value" column,
// with the "series" column containing a key derived from the last letter
// of the corresponding original column name (i.e., 'A' or 'B').
df.gather { resultA and resultB }.mapKeys { it.last() }.into("series", "value")

// Gather values of all `String` columns
// into a single "tag" column, omitting the key column.
df.gather { colsOf<String>() }.valuesInto("tag")

Parameters

Reshapes the DataFrame by gathering specified columns into two columns: keys and values (or into just one of them).

By default, the "key" column contains the names of the gathered columns, and the "value" column holds the corresponding cell values. The original columns selected for gathering are removed from the result, while all other columns remain unchanged — except that their values are duplicated for each generated key-value pair.

This function does not perform the reshaping immediately — it returns a Gather object, which serves as an intermediate step. Before applying the final transformation, you may:

• filter values (where, notNull);

• explode list-columns (explodeLists);

• transform keys (mapKeys) or values (mapValues);

• cast the value type (cast).

Finally, reshape the DataFrame using one of the following methods:

• into

• keysInto

• valuesInto

Each of these methods returns a new reshaped DataFrame.

This operation is the reverse of pivot.

This can include column groups and nested columns.

For more information: See gather on the documentation website.

See Grammar.

This Gather Overload

Select single or multiple columns using their names as Strings. (String API).

Example

df.gather("resultA", "resultB").mapKeys { it.last() }.into("series", "value")

Parameters