id: tabular_join
name: Join
description: >
  Join two tables on matching columns. Supports inner, left, right, outer,
  and cross join types. Produces a combined table with columns from both inputs.
version: 1.0.0
category: combine
type: table-to-table
default_implementation: duckdb

inputs:
  - name: left
    type: table
    format: parquet
    description: Left table
    required: true
  - name: right
    type: table
    format: parquet
    description: Right table
    required: true

requires: {}  # structural — operates on any pair of tables

outputs:
  - name: result
    type: table
    format: parquet
    description: Joined table

params:
  on:
    type: string
    description: >
      Column name to join on. If both tables share the column name,
      a single string suffices. For different column names, use
      left_on/right_on params instead.
  left_on:
    type: string
    description: Column name in left table (when join columns differ)
  right_on:
    type: string
    description: Column name in right table (when join columns differ)
  how:
    type: string
    default: inner
    enum: [inner, left, right, outer, cross]
    description: Join type
  suffix:
    type: string
    default: "_right"
    description: Suffix appended to duplicate column names from the right table

# backends: audited 2026-08-14 (defect 50). A key means a runtime that DISPATCHES this op —
# folia-engine `dispatch_op` (products/sdk/folia-engine/src/lib.rs), a `registerOp`/OP_TABLE
# entry in packages/compute, `_BUILTIN_OP_MAP` in folia/compute.py, or a backend manifest
# (folia/backends/*/backend.yaml).
backends:
  rust-engine:
    op: tabular_join
    function: throughput_tabular_host::tabular_join_op
    dispatch: products/sdk/folia-engine/src/lib.rs:844
  js:
    function: tabular_join
    dispatch: packages/compute/src/ops/tabular-sql.ts
  python:
    function: tabular.ops.join
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  table:
    renderer: tanstack-table