Skip to content

v0.38.0 - Full Join Support for DataFrame (2026-03-23)

What Changed?

This release completes the join API for DataFrame in src/v2/frame.ts. joinLeft, joinRight, and joinOuter are now fully implemented. The inner join was also optimized from O(n×m) to O(n+m) using a Map-based index, reducing the risk of GAS execution timeout on large DataFrames.

What's New

Main Feature: Full Join API (joinLeft, joinRight, joinOuter)

What it does: All four join types — inner, left, right, and outer — are now available on DataFrame. Unmatched rows are preserved with null filled in for missing columns.

How to use it:

TypeScript
const left  = DataFrame.fromColumns({ id: [1, 2, 3], name: ["Alice", "Bob", "Charlie"] });
const right = DataFrame.fromColumns({ id: [2, 3, 4], score: [80, 70, 60] });

// Left join: all left rows preserved
left.join(right, "id", "left");
// id | name    | score
// 1  | Alice   | null
// 2  | Bob     | 80
// 3  | Charlie | 70

// Right join: all right rows preserved
left.join(right, "id", "right");
// id | name    | score
// 2  | Bob     | 80
// 3  | Charlie | 70
// 4  | null    | 60

// Outer join: all rows from both DataFrames
left.join(right, "id", "outer");
// id | name    | score
// 1  | Alice   | null
// 2  | Bob     | 80
// 3  | Charlie | 70
// 4  | null    | 60

Added

  • DataFrame.joinLeft — left join with null-fill for unmatched right-side columns
  • DataFrame.joinRight — right join with null-fill for unmatched left-side columns
  • DataFrame.joinOuter — full outer join combining all rows from both DataFrames
  • Private helper assertJoinColumn — shared column validation for all join methods
  • Private helper buildJoinIndex — shared Map-based index builder for O(n+m) lookups
  • Tests for joinLeft, joinRight, joinOuter (matched rows, null-fill, 1-to-many, error cases)

Changed

  • joinInner optimized from O(n×m) nested loop to O(n+m) using buildJoinIndex
  • join dispatch updated to support all four join types (previously left/right/outer threw "not yet implemented")

Fixed

  • Fixed inaccurate docstring in joinInner that stated duplicate columns were excluded

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

All existing joinInner and join(..., "inner") calls continue to work with identical results. The only behavioral change is that join(..., "left"), join(..., "right"), and join(..., "outer") no longer throw an error.

Release Details

  • Date: 2026-03-23
  • Version: v0.38.0
  • gaslamp: version 81
  • pilotlamp: version 38
  • Files Changed: 143
  • Commits:
    • de06751 perf(frame): replace O(n*m) nested loop with Map index in joinInner
    • f419419 feat(frame): implement joinLeft with Map index for O(n+m) performance
    • 54410f0 feat(frame): implement joinRight with Map index for O(n+m) performance
    • 7e59ba8 feat(frame): implement joinOuter for full outer join
    • 48bc9e6 refactor(frame): extract assertJoinColumn and buildJoinIndex helpers
    • a690d7e test(frame): add tests for joinLeft, joinRight, joinOuter
    • f5e1ff1 docs(frame): update docstrings for join, joinInner, joinLeft, joinRight, joinOuter

Known Issues

  • joinLeft, joinRight, joinOuter are implemented only in src/v2/frame.ts. The src/torch/ DataFrame does not yet have these join methods.

Next Steps

  • Port join methods to src/torch/dataframe/
  • Add join support to LazyFrame