# Table.join
URL: https://lsd.tools/docs/api-table-join
Updated: 2026-07-17

## Parameters

| name | type | default | description |
|---|---|---|---|
| `other` | `Table` | — | the right-hand table to join against |
| `on` | `str` \| `list[str]` | — | key column(s) present in both tables |
| `how` | `str` | `"inner"` | join type: `"inner"`, `"left"`, `"right"`, or `"outer"` |

## Example

```python
orders.join(customers, on="customer_id")
```

Keep every left row, filling unmatched right columns with nulls:

```python
orders.join(customers, on="customer_id", how="left")
```

## Notes

`how` accepts `"inner"` (default), `"left"`, `"right"`, and `"outer"`. Join on multiple
keys by passing a list to `on`. Every call returns a **new** `Table`.

## See also

**API:** [group_by](/docs/api-table-group-by) · [select](/docs/api-table-select) · [with_column](/docs/api-table-with-column)

**Guides:** [Tables & data flow](/docs/tools-tables)