TableFrame.join

methodView source ↗

def join(
    other: TableFrame,
    on: str | Expr | Sequence[str | Expr] | None = None,
    how: JoinStrategy = 'inner',
    left_on: str | Expr | Sequence[str | Expr] | None = None,
    right_on: str | Expr | Sequence[str | Expr] | None = None,
    suffix: str = '_right',
    join_nulls: bool = False,
    coalesce: bool | None = None,
) -> TableFrame

Categories: join

Join the TableFrame with another TableFrame.

Parameters

parameter

other

The TableFrame to join.

parameter

on

Name(s) of the columns to join on. The column name(s) must be in both TableFrame's. Don't use this parameter if using left_onandright_onparameters, or ifhow="cross"`.

parameter

how

Join strategy: * inner: An inner join. * left: A left join. * right: A rigth join. * full: A full join. * cross: The cartesian product. * semi: An inner join but only returning the columns from left TableFrame. * anti: Rows from the left TableFrame that have no match in the right TableFrame.

parameter

left_on

Name(s) of the columns to join on from the left TableFrame. It must be used together wit the right_on parameter. It cannot be used with the on parameter.

parameter

right_on

Name(s) of the columns to join on from the right TableFrame. It must be used together wit the left_on parameter. It cannot be used with the on parameter.

parameter

suffix

Duplicate columns on the right Table are appended this suffix.

parameter

join_nulls

If null value matches should produce join rows or not.

parameter

coalesce

Collapse join columns into a single column.

Examples

>>> import tabsdata as td
>>>
>>> tf1: td.TableFrame ...
>>>
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ str  ┆ i64  │
╞══════╪══════╡
│ A    ┆ 1    │
│ X    ┆ 10   │
│ C    ┆ 3    │
│ D    ┆ 5    │
│ M    ┆ 9    │
│ A    ┆ 100  │
│ M    ┆ 50   │
│ null ┆ 20   │
│ F    ┆ null │
└──────┴──────┘
>>>
>>> tf2: td.TableFrame ...
>>>
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ str  ┆ i64  │
╞══════╪══════╡
│ A    ┆ 3    │
│ Y    ┆ 4    │
│ Z    ┆ 5    │
│ A    ┆ 0    │
│ M    ┆ 6    │
│ null ┆ 8    │
│ F    ┆ null │
└──────┴──────┘
>>>
An inner join:
>>>
>>> tf1.join(tf2, on="a", how="inner")
>>>
┌─────┬──────┬─────────┐
│ a   ┆ b    ┆ b_right │
│ --- ┆ ---  ┆ ---     │
│ str ┆ i64  ┆ i64     │
╞═════╪══════╪═════════╡
│ A   ┆ 1    ┆ 3       │
│ A   ┆ 1    ┆ 0       │
│ M   ┆ 9    ┆ 6       │
│ A   ┆ 100  ┆ 3       │
│ A   ┆ 100  ┆ 0       │
│ M   ┆ 50   ┆ 6       │
│ F   ┆ null ┆ null    │
└─────┴──────┴─────────┘
>>>
A left join:
>>>
>>> tf1.join(tf2, on="a", how="left")
>>>
┌──────┬──────┬─────────┐
│ a    ┆ b    ┆ b_right │
│ ---  ┆ ---  ┆ ---     │
│ str  ┆ i64  ┆ i64     │
╞══════╪══════╪═════════╡
│ A    ┆ 1    ┆ 3       │
│ A    ┆ 1    ┆ 0       │
│ X    ┆ 10   ┆ null    │
│ C    ┆ 3    ┆ null    │
│ D    ┆ 5    ┆ null    │
│ …    ┆ …    ┆ …       │
│ A    ┆ 100  ┆ 3       │
│ A    ┆ 100  ┆ 0       │
│ M    ┆ 50   ┆ 6       │
│ null ┆ 20   ┆ null    │
│ F    ┆ null ┆ null    │
└──────┴──────┴─────────┘
>>>
Turning off column coalesce:
>>>
>>> tf1.join(tf2, on="a", coalesce=False)
>>>
┌─────┬──────┬─────────┬─────────┐
│ a   ┆ b    ┆ a_right ┆ b_right │
│ --- ┆ ---  ┆ ---     ┆ ---     │
│ str ┆ i64  ┆ str     ┆ i64     │
╞═════╪══════╪═════════╪═════════╡
│ A   ┆ 1    ┆ A       ┆ 3       │
│ A   ┆ 1    ┆ A       ┆ 0       │
│ M   ┆ 9    ┆ M       ┆ 6       │
│ A   ┆ 100  ┆ A       ┆ 3       │
│ A   ┆ 100  ┆ A       ┆ 0       │
│ M   ┆ 50   ┆ M       ┆ 6       │
│ F   ┆ null ┆ F       ┆ null    │
└─────┴──────┴─────────┴─────────┘