Ciaren

Join — join

Combine two inputs (left, right) on a key. Join is one of two multi-input nodes — connect one upstream node to its left handle and another to its right handle.

Use cases

  • Enrich transactions with customer attributes.
  • Look up reference data (region names, prices) by key.

What it does

Join combines the left and right inputs on a shared key. The how parameter controls which rows survive — inner keeps only matches, left keeps all rows from the left input (filling nulls for unmatched right-side columns).

Left input
  1. Transform
    Left input
    orders aggregated by customer_id
Right input
  1. Input
    Right input
    customers.csv
  1. Join
    Join
    on: customer_id · how: left
  2. Transform
    Enriched result
    transactions + customer name/country
Join (on=customer_id, how=left)
Before
customer_idtotal_spent
1100
2500
315
3 rows · 2 cols
After
customer_idtotal_spentnamenewcountrynew
1100AdaUK
2500GraceUS
315LinusFI
3 rows · 4 cols

Configuration

Config keyTypeRequiredDescription
onstring | string[]ConditionalKey(s) present in both frames
left_on / right_onstring | string[]ConditionalUse when key names differ (supply both)
howstringNoinner (default), left, right, outer
suffixes[string, string]NoSuffixes for overlapping columns (default _x, _y)

Provide either on (same key name on both sides) or both left_on and right_on (different names).

Generated Python code

python
df_3 = df_1.merge(df_2, on='customer_id', how='left')

Tips & common mistakes

  • how controls which rows survive: inner keeps matches only; left/right keep all rows from one side; outer keeps everything (unmatched cells become null).
  • Overlapping non-key columns get suffixes. Rename or drop them upstream to avoid _x/_y columns.
  • A shared-key (on=) outer join produces a single key column (the keys are coalesced), matching pandas — verified across both engines.
  • Join takes two inputs at a time; chain join nodes to combine three or more.

See also