join_rows
Joins two lists of JSON rows on a shared key, like a SQL join or a spreadsheet VLOOKUP, and returns the combined rows plus a summary: how many rows matched on each side, match rates, and warnings for duplicate keys, rows missing the key and key fields that exist on no row. Use it to enrich a list with fields from a lookup table (left join), keep only the overlap (inner), combine two sources into one table (full), find rows in one list that are missing from the other (leftAnti or rightAnti), or stack two same-shape lists (union). Keys match case-insensitively with whitespace trimmed by default, and the key can have a different name on each side (email on the left, contact_email on the right). Input and output rows are capped per call; a many-to-many join that would exceed the output cap is refused with the predicted row count, never truncated. Call list_capabilities for the exact limits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| joinType | No | Which rows to keep. left (default): every left row, enriched where a match exists. inner: matched rows only. right: every right row. full: everything from both sides. leftAnti: left rows with no match on the right. rightAnti: right rows with no match on the left. union: stack both lists, no key needed. | |
| leftRows | Yes | The LEFT table: the main rows you want to keep or enrich. Each row is a JSON object; keys may differ between rows. | |
| rightRows | Yes | The RIGHT table: the lookup rows to pull matching fields from. Each row is a JSON object. | |
| keyMatching | No | normalized (default): case-insensitive, trimmed, repeated spaces collapsed, 123 matches "123". exact: values must be identical. | |
| rightFields | No | Only copy these fields from the matching right row, like choosing VLOOKUP return columns. Leave out to copy every right field. | |
| leftKeyFields | No | The field name(s) on the left rows to match on, for example ["email"], or ["firstName","lastName"] for a composite key. Required for every joinType except union. | |
| rightKeyFields | No | The matching field name(s) on the right rows, in the same order as leftKeyFields, for example ["contact_email"]. Leave out when the right rows use the same names as the left. | |
| includeJoinInfo | No | On by default: every row gets _joinStatus ("matched", "left_only", "right_only") and _matchCount. Set false for rows with only your own fields. | |
| multipleMatches | No | When one key matches several right rows. all (default): one output row per matching pair, like SQL. first: only the first matching right row, like VLOOKUP, so each left row appears once. | |
| onFieldConflict | No | When a right field has the same name as a left field. prefixRight (default): keep both, the right one renamed with rightFieldPrefix. keepLeft: ignore the right value. keepRight: overwrite the left value. | |
| rightFieldPrefix | No | Prefix for conflicting right fields when onFieldConflict is prefixRight. Default "right_", so price becomes right_price. |