joinWith kdocs

Author: AndreiKingsley

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/join.kt

@@ -42,8 +42,10 @@ private interface JoinBehavior
  *
  * @include [JoinBehavior]
  *
- * See also shortcuts with each of join types:
- * [innerJoin], [leftJoin], [rightJoin], [fullJoin], [filterJoin], [excludeJoin].
+ * Each join type has a corresponding shortcut function:
+ * [innerJoin], [leftJoin], [rightJoin], [fullJoin], [filterJoin], and [excludeJoin].
+ *
+ * See also [joinWith], which performs a join by matching row values condition.
  *
  * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
  *
@@ -95,7 +97,7 @@ private interface SelectingColumnsJoinDsl
  * @include [JoinDocs]
  * @include [SelectingColumnsJoinDsl]
  * @param other [DataFrame] to join with.
- * @param type [JoinType] defining how rows are matched and combined.
+ * @param type [JoinType] defining how the resulting rows are constructed.
  * @param selector [JoinColumnsSelector] specifying join columns;
  * if `null`, same-name columns are used.
  * @return joined [DataFrame].
@@ -123,7 +125,7 @@ private interface JoinStringApiExample
  * @include [JoinStringApiExample]
  * @param other [DataFrame] to join with.
  * @param columns [Column Names][String] specifying join columns.
- * @param type [JoinType] defining how rows are matched and combined.
+ * @param type [JoinType] defining how the resulting rows are constructed.
  * @return joined [DataFrame].
  */
 public fun <A, B> DataFrame<A>.join(
@@ -582,19 +584,19 @@ public typealias JoinColumnsSelector<A, B> = JoinDsl<A, B>.(ColumnsContainer<A>)
 public enum class JoinType {
 
     /**
-     * Includes all rows from the left [DataFrame]; rows with matching keys are merged,
+     * Includes all rows from the left [DataFrame]; matching rows are merged,
      * unmatched right-side values are filled with `null`.
      */
     Left,
 
     /**
-     * Includes all rows from the right [DataFrame]; rows with matching keys are merged,
+     * Includes all rows from the right [DataFrame]; matching rows are merged,
      * unmatched left-side values are filled with `null`.
      */
     Right,
 
     /**
-     * Includes only rows with matching keys from both [DataFrame]s;
+     * Includes only matching rows from both [DataFrame]s;
      * rows are merged.
      */
     Inner,

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt

@@ -5,14 +5,96 @@ import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.Selector
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
 import org.jetbrains.kotlinx.dataframe.annotations.Refine
+import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
+import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Join
+import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnGroupsAndNestedColumnsMention
 import org.jetbrains.kotlinx.dataframe.impl.api.joinWithImpl
 
+/**
+ * A [JoinExpression] defines the matching condition between [rows][DataRow] of the two [DataFrame]s.
+ * It provides access to row values from both the left and right [DataFrame]s
+ * and expects a [Boolean] result indicating whether the rows match.
+ * All combinations of rows from the left and right [DataFrame]s that satisfies
+ * this condition are matched.
+ *
+ * This method is useful when the data was not originally designed relationally, or when
+ * rows should be matched based on custom logic rather than simple equality.
+ *
+ * Creates a new [DataFrame] by combining [rows][DataRow]
+ * from both inputs according to the [\joinExpression] matching rule.
+ */
+@ExcludeFromSources
+private interface JoinWithCommonDescription
+
+// `joinWith` method used in the example
+private interface JoinWithMethod
+
+/**
+ * ### Examples
+ * ```kotlin
+ * // Join rows where the `fullName` value in the left DataFrame
+ * // contains the `firstName` value in the right DataFrame.
+ * dfLeft.{@get [JoinWithMethod] 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.{@get [JoinWithMethod] joinWith}(dfRight) { right.date in startDate..endDate }
+ * ```
+ */
+private interface JoinWithExample
+
+/**
+ * A specialized [DataRow] used in a [JoinExpression].
+ *
+ * Represents a row from the left [DataFrame] (as the receiver)
+ * and provides access to the row from the right [DataFrame] via [right].
+ */
 public interface JoinedDataRow<out A, out B> : DataRow<A> {
     public val right: DataRow<B>
 }
 
+/**
+ * A special [row][DataRow] expression used to define
+ * the row-matching condition in a [joinWith] operation.
+ *
+ * Provides the [row][DataRow] of the left [DataFrame] both
+ * as the receiver (`this`) and as the argument (`it`),
+ * allowing you to reference its values directly.
+ *
+ * The [row][DataRow] of the right [DataFrame] is available
+ * via [right][JoinedDataRow.right].
+ *
+ * The expression must return a [Boolean] indicating whether
+ * the rows from the left and right [DataFrame]s match.
+ */
 public typealias JoinExpression<A, B> = Selector<JoinedDataRow<A, B>, Boolean>
 
+/**
+ * Joins this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * {@include [JoinTypeDescription]}
+ *
+ * Each join type has a corresponding shortcut function:
+ * [innerJoinWith], [leftJoinWith], [rightJoinWith], [fullJoinWith], [filterJoinWith], and [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample]
+ * @param [right] [DataFrame] to join with.
+ * @param [type] [JoinType] defining how rows are matched and combined.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("JoinWith")
 public fun <A, B> DataFrame<A>.joinWith(
@@ -21,31 +103,163 @@ public fun <A, B> DataFrame<A>.joinWith(
     joinExpression: JoinExpression<A, B>,
 ): DataFrame<A> = joinWithImpl(right, type, addNewColumns = type.addNewColumns, joinExpression)
 
+/**
+ * Performs [inner join][JoinType.Inner] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Inner]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Inner].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [leftJoinWith], [rightJoinWith], [fullJoinWith], [filterJoinWith], [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] innerJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("InnerJoinWith")
 public fun <A, B> DataFrame<A>.innerJoinWith(right: DataFrame<B>, joinExpression: JoinExpression<A, B>): DataFrame<A> =
     joinWith(right, JoinType.Inner, joinExpression)
 
+/**
+ * Performs [left join][JoinType.Left] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Left]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Left].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [innerJoinWith], [rightJoinWith], [fullJoinWith], [filterJoinWith], [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] leftJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("LeftJoinWith")
 public fun <A, B> DataFrame<A>.leftJoinWith(right: DataFrame<B>, joinExpression: JoinExpression<A, B>): DataFrame<A> =
     joinWith(right, JoinType.Left, joinExpression)
 
+/**
+ * Performs [right join][JoinType.Right] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Right]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Right].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [innerJoinWith], [leftJoinWith], [fullJoinWith], [filterJoinWith], [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] rightJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("RightJoinWith")
 public fun <A, B> DataFrame<A>.rightJoinWith(right: DataFrame<B>, joinExpression: JoinExpression<A, B>): DataFrame<A> =
     joinWith(right, JoinType.Right, joinExpression)
 
+/**
+ * Performs [full join][JoinType.Full] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Full]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Full].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [leftJoinWith], [rightJoinWith], [innerJoinWith], [filterJoinWith], [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] fullJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("FullJoinWith")
 public fun <A, B> DataFrame<A>.fullJoinWith(right: DataFrame<B>, joinExpression: JoinExpression<A, B>): DataFrame<A> =
     joinWith(right, JoinType.Full, joinExpression)
 
+/**
+ * Performs [filter join][JoinType.Filter] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Filter]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Filter].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [leftJoinWith], [rightJoinWith], [fullJoinWith], [innerJoinWith], [excludeJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] filterJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("FilterJoinWith")
 public fun <A, B> DataFrame<A>.filterJoinWith(right: DataFrame<B>, joinExpression: JoinExpression<A, B>): DataFrame<A> =
-    joinWithImpl(right, JoinType.Inner, addNewColumns = false, joinExpression)
+    joinWithImpl(right, JoinType.Filter, addNewColumns = false, joinExpression)
 
+/**
+ * Performs [exclude join][JoinType.Exclude] of this [DataFrame] with the [right][\right] [DataFrame]
+ * using the provided [\joinExpression]. {@include [JoinType.Exclude]}
+ *
+ * This is a shortcut for [joinWith] with [JoinType.Exclude].
+ *
+ * @include [JoinWithCommonDescription]
+ *
+ * See also general [joinWith] as well as other shortcuts with each of join types:
+ * [leftJoinWith], [rightJoinWith], [fullJoinWith], [filterJoinWith], [innerJoinWith].
+ *
+ * See also [join], which performs a join by simply matching columns.
+ *
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ *
+ * For more information, {@include [DocumentationUrls.JoinWith]}.
+ *
+ * @include [JoinWithExample] {@set [JoinWithMethod] excludeJoinWith}
+ * @param [right] [DataFrame] to join with.
+ * @param [joinExpression] [JoinExpression] specifying rows join condition.
+ * @return joined [DataFrame].
+ */
 @Refine
 @Interpretable("ExcludeJoinWith")
 public fun <A, B> DataFrame<A>.excludeJoinWith(

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt

@@ -182,4 +182,7 @@ internal interface DocumentationUrls {
 
     /** [See `join` on the documentation website.]({@include [Url]}/join.html) */
     interface Join
+
+    /** [See `joinWith` on the documentation website.]({@include [Url]}/joinWith.html) */
+    interface JoinWith
 }