joinWith

Joins this DataFrame with the right DataFrame using the provided joinExpression.

A JoinExpression defines the matching condition between rows of the two DataFrames. It provides access to row values from both the left and right DataFrames and expects a Boolean result indicating whether the rows match. All combinations of rows from the left and right DataFrame that satisfy this condition are matched.

This method is useful when rows should be matched based on custom logic rather than simple value equality.

Creates a new DataFrame by combining rows from both inputs according to the joinExpression matching rule.

There are two categories of joins:

• Merging joins — merge matching rows from both DataFrames into a single row.

• Non-merging joins — select rows from the left DataFrame based on whether a match exists in the right one, without merging columns.

The exact behavior depends on the specified join type:

Merging joins:

• JoinType.Inner (default) — Includes only matching rows from both DataFrames; rows are merged.

• JoinType.Left — Includes all rows from the left DataFrame; matching rows are merged, unmatched right-side values are filled with null.

• JoinType.Right — Includes all rows from the right DataFrame; matching rows are merged, unmatched left-side values are filled with null.

• JoinType.Full — Includes all rows from both DataFrames; matching rows are merged, all mismatches are filled with null.

Non-merging joins:

• JoinType.Filter — Includes only rows from the left DataFrame that have a match in the right one; right-side columns are not merged.

• JoinType.Exclude — Includes only rows from the left DataFrame that do not have a match in the right one; right-side columns are not merged.

Each join type has a corresponding shortcut function: innerJoinWith, leftJoinWith, rightJoinWith, fullJoinWith, filterJoinWith, and excludeJoinWith.

See also join, which performs a join by exact value equality in the selected columns.

This can include column groups and nested columns.

For more information, See joinWith on the documentation website..

Examples

// Join rows where the `fullName` value in the left `DataFrame`
// contains the `firstName` value in the right `DataFrame`.
dfLeft.joinWith(dfRight) { left -> left.fullName.contains(right.firstName) }

// Join rows where the `date` value in the right `DataFrame`
// falls within the interval defined by the `startDate` and `endDate`
// values in the left `DataFrame`.
dfLeft.joinWith(dfRight) { right.date in startDate..endDate }

// String API; join rows where `score` value in the left `DataFrame` is higher than 3.4
// and the `passed` value in the right `DataFrame` is `true`.
dfLeft.joinWith(dfRight) { "score"<Int>() > 3.4 && right["passed"] as Boolean }

Parameters