Joining Tables

perspective.join() creates a read-only Table by joining two source tables on a shared key column. The result is reactive — it updates automatically when either source table changes. See Join for conceptual details.

Basic Inner Join

orders = perspective.table([
    {"id": 1, "product_id": 101, "qty": 5},
    {"id": 2, "product_id": 102, "qty": 3},
    {"id": 3, "product_id": 101, "qty": 7},
])

products = perspective.table([
    {"product_id": 101, "name": "Widget"},
    {"product_id": 102, "name": "Gadget"},
])

joined = perspective.join(orders, products, "product_id")
view = joined.view()
json = view.to_json()

Join Types

Pass join_type to select inner, left, or outer join behavior:

# Left join: all left rows, nulls for unmatched right columns
left_joined = perspective.join(left, right, "id", join_type="left")

# Outer join: all rows from both tables
outer_joined = perspective.join(left, right, "id", join_type="outer")

Reactive Updates

The joined table recomputes automatically when either source table is updated:

left = perspective.table([{"id": 1, "x": 10}])
right = perspective.table([{"id": 2, "y": "b"}])

joined = perspective.join(left, right, "id")
view = joined.view()

json = view.to_json()
# [] — no matching keys yet

right.update([{"id": 1, "y": "a"}])
json = view.to_json()
# [{"id": 1, "x": 10, "y": "a"}] — new match detected

Async Client

The async client has the same API:

joined = await client.join(orders, products, "product_id", join_type="left")