Skip to content

Join

Combine two datasets by matching rows on one or more key columns (SQL-style joins).

When to use this

  • You have two files (or two upstream nodes) and you want to merge them on a shared key, for example to attach product master data to a transactions table, or unit costs to shipments

What you need

  • Two upstream data sources wired to the left and right inputs of the Join node
  • The column(s) to match on: one or more pairs of "left column = right column"

Parameters

Setting Options Description
Join Type Inner Join, Left Join, Right Join, Full Outer Join Set in the side panel. Which rows survive the join. See the table below.
Join Keys One or more left column = right column pairs Set in the side panel with Add key pair, or by your agent. Each side's column is picked from the table wired into that input. The columns for matching rows between left and right. All pairs must match (AND-combined).

A key's column name matches the data's column ignoring capitalization and surrounding spaces. Key values are compared as text, so 7 and 7.0 do not match.

Join Type

Type Behaviour
Inner Join Only rows that match in both inputs. If no row matches, the run fails and the Execution Report shows sample keys from both sides
Left Join All rows from left; a row with no match has no right columns at all
Right Join All rows from right; a row with no match has no left columns at all
Full Outer Join All rows from both inputs; an unmatched row has only its own side's columns

What you get

A single dataset with the left input's columns, then the right input's. A key column both sides name the same appears once; a key named differently on each side appears twice. Any other right-side column whose name is already taken is renamed with a _right suffix, then _right_2, _right_3 and so on. Downstream nodes must reference the suffixed name. These are known before the workflow runs, so a mapping node after the Join lists them.

Chained joins

For three or more inputs, chain Join nodes left to right. Each Join's output becomes the left input of the next:

flowchart LR
    n1["Import Data (A)"] --> n2["Join 1"]
    n2 --> n3["Join 2"]
    n3 --> n4["Save Data"]
    n5["Import Data (B)"] --> n2
    n6["Import Data (C)"] --> n3

Workflow wiring

flowchart LR
    n1["Import Data (sites.csv)"] --> n2["Join (site = site_id)"]
    n2 --> n3["Map Locations"]
    n3 --> n4["Create Scenario"]
    n5["Import Data (coordinates.csv)"] --> n2

Common mistakes

  • Wiring only one input. Join needs exactly two upstream connections
  • Forgetting the _right suffix on conflicting column names in downstream nodes
  • Using a Script to write a join in Python. Use Join first; it needs no code and is visible in the workflow
  • Adding multiple Join Keys expecting OR behaviour. All keys are AND-combined; every pair must match

Messages this node can show

A run gives this node 5 minutes. A node that takes longer stops with Time limit reached.

Like every node, it can also stop on the checks before a run and the run's limits.