Column arithmetics

Kotlin DataFrame provides operators for applying simple arithmetic, logical, string, and comparison operations to DataColumn and ColumnReference values. These operations include, for example, adding a value to each cell in a column, multiplying a column by a value, and comparing elements in a column with a value.

When useful

In most transformations, these column operations are usually not the preferred approach in Kotlin DataFrame, because the library provides row-based APIs such as add, update, and map, which are usually recommended.

Also, the expr function is particularly useful in this context, as it allows you to write row expressions inside the Columns Selection DSL. In other words, expr works as an adapter between a column selector and a row expression.

For example,

orders.groupBy { status + " orders" }

is equivalent to

orders.groupBy { expr("status") { status + " orders" } }

but in the first case, status is used as a DataColumn of String values, and in the second case, status is treated as a String.

However, column arithmetics might still be useful in some cases. For example, when building temporary plotting expressions. If distance is stored in meters, but you need to plot it in kilometers, you can convert it directly in the plotting expression without having to create a temporary column in your dataframe just for plotting.

df.plot {
    line {
        x(day)
        y((distanceMeters / 1000.0) named "distanceKm")
    }
}

Not

Negates Boolean values in a DataColumn (ColumnReference). Returns a result of the same type.

df.select { !isHappy }
// or
!df.isHappy

Nullable Boolean columns preserve null values.

Plus

Adding a value to a column and concatenation of a column with a String are supported. In all cases, a DataColumn (ColumnReference) is returned.

Column plus value or value plus column

Adds the value to each element of the column. The value can appear on either side of the operator.

transactions.amount + 10
5.0 + transactions.amount

null values are not changed by this operation.

Column plus String

Converts each element of the column to a String and concatenates it with the value.

weather.select { temperature + " °C" }
// or
weather.temperature + " °C"

null values are converted to the string "null".

Minus

Column minus value

Subtracts the value from each element of the column.

transactions.amount - 10.0

null values are not changed by this operation.

Value minus column

Subtracts each element of the column from the value and returns a DataColumn (ColumnReference) with the results of the subtractions.

100 - transactions.amount

null values from the original column remain null values in the resulting column.

Unary minus

Flips the sign of each element in the column.

-transactions.amount

null values are not changed by this operation.

Times

Multiplies each element of the column by the value.

routes.distanceKm * 1000.0
products.price * BigDecimal("1.20")

null values are not changed by this operation.

Div

Division by zero follows Kotlin semantics of the underlying type.

Divide column by value

Divides each element of the column by the value.

products.weightGrams / 1000.0

Divide value by column

Divides the value by each element of the column and returns a DataColumn (ColumnReference) with the results of the divisions.

40 / tasks.hoursPerTask

If an element of the column is null, the corresponding value in the resulting column is also null.

Compare

eq, neq, gt, and lt are available for DataColumn. Each of them returns a DataColumn of Boolean values.

eq

Compares each element of a DataColumn with the value for equality using the == operator.

orders.status eq "canceled"

neq

Compares each element of a DataColumn with the value for inequality using the != operator.

orders.status neq "completed"

gt

Compares each element of a DataColumn with the value using the > operator.

orders.cost gt 1000.0

lt

Compares each element of a DataColumn with the value using the < operator.

orders.cost lt 20.0

05 May 2026