polars join for lazyframe

Joins a lazy frame with other lazy frame.

This command requires a plugin

The polars join command resides in the polars plugin. To use this command, you must install and register nu_plugin_polars. See the Plugins chapter in the book for more information.

Signature

> polars join {flags} (other) (left_on) (right_on)

Flags

  • --inner, -i: inner joining between lazyframes (default)
  • --left, -l: left join between lazyframes
  • --full, -f: full join between lazyframes
  • --cross, -c: cross join between lazyframes
  • --coalesce-columns: Sets the join coalesce strategy to colesce columns. Most useful when used with --full, which will not otherwise coalesce.
  • --suffix, -s {string}: Suffix to use on columns with same name

Parameters

  • other: LazyFrame to join with
  • left_on: Left column(s) to join on
  • right_on: Right column(s) to join on

Input/output types:

inputoutput
anyany

Examples

Join two lazy dataframes

> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-lazy)
    let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy)
    $df_a | polars join $df_b a foo | polars collect
╭───┬───┬───┬───┬─────┬─────╮
│ # │ a │ b │ c │ bar │ ham │
├───┼───┼───┼───┼─────┼─────┤
│ 0 │ 1 │ a │ 0 │ a   │ let │
│ 1 │ 2 │ b │ 1 │ c   │ var │
│ 2 │ 1 │ c │ 2 │ a   │ let │
│ 3 │ 1 │ c │ 3 │ a   │ let │
╰───┴───┴───┴───┴─────┴─────╯

Join one eager dataframe with a lazy dataframe

> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-df)
    let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy)
    $df_a | polars join $df_b a foo
╭───┬───┬───┬───┬─────┬─────╮
│ # │ a │ b │ c │ bar │ ham │
├───┼───┼───┼───┼─────┼─────┤
│ 0 │ 1 │ a │ 0 │ a   │ let │
│ 1 │ 2 │ b │ 1 │ c   │ var │
│ 2 │ 1 │ c │ 2 │ a   │ let │
│ 3 │ 1 │ c │ 3 │ a   │ let │
╰───┴───┴───┴───┴─────┴─────╯

Perform a full join of two dataframes and coalesce columns

> let table1 = [[A B]; ["common" "common"] ["table1" "only"]] | polars into-df
                let table2 = [[A C]; ["common" "common"] ["table2" "only"]] | polars into-df
                $table1 | polars join -f $table2 --coalesce-columns A A
╭───┬────────┬────────┬────────╮
│ # │   A    │   B    │   C    │
├───┼────────┼────────┼────────┤
│ 0 │ common │ common │ common │
│ 1 │ table2 │        │ only   │
│ 2 │ table1 │ only   │        │
╰───┴────────┴────────┴────────╯

Join one eager dataframe with another using a cross join

> let tokens = [[monopoly_token]; [hat] [shoe] [boat]] | polars into-df
    let players = [[name, cash]; [Alice, 78] [Bob, 135]] | polars into-df
    $players | polars select (polars col name) | polars join --cross $tokens | polars collect
╭───┬───────┬────────────────╮
│ # │ name  │ monopoly_token │
├───┼───────┼────────────────┤
│ 0 │ Alice │ hat            │
│ 1 │ Alice │ shoe           │
│ 2 │ Alice │ boat           │
│ 3 │ Bob   │ hat            │
│ 4 │ Bob   │ shoe           │
│ 5 │ Bob   │ boat           │
╰───┴───────┴────────────────╯