Apache DataFusion SQL Query Engine
feat: Add support for `LEFT JOIN LATERAL` (#21352)
Neil Conway90a8117be6c5
diff --git a/datafusion/optimizer/src/decorrelate_lateral_join.rs b/datafusion/optimizer/src/decorrelate_lateral_join.rsindex b9c9fabb8e..ea25ab479f 100644--- a/datafusion/optimizer/src/decorrelate_lateral_join.rs+++ b/datafusion/optimizer/src/decorrelate_lateral_join.rs@@ -28,7 +28,7 @@ use datafusion_expr::{Expr, Join, expr};use datafusion_common::tree_node::{Transformed, TransformedResult, TreeNode, TreeNodeRecursion,};-use datafusion_common::{Column, DFSchema, Result, TableReference};+use datafusion_common::{Column, DFSchema, Result, ScalarValue, TableReference};use datafusion_expr::logical_plan::{JoinType, Subquery};use datafusion_expr::utils::conjunction;use datafusion_expr::{LogicalPlan, LogicalPlanBuilder, SubqueryAlias};@@ -71,14 +71,13 @@ impl OptimizerRule for DecorrelateLateralJoin {}}-// Build the decorrelated join based on the original lateral join query. For-// now, we only support cross/inner lateral joins.+// Build the decorrelated join based on the original lateral join query.+// Supports INNER and LEFT lateral joins.fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {- // TODO: Support outer joins- // <https://github.com/apache/datafusion/issues/21199>- if join.join_type != JoinType::Inner {+ if !matches!(join.join_type, JoinType::Inner | JoinType::Left) {return Ok(Transformed::no(LogicalPlan::Join(join)));}+ let original_join_type = join.join_type;// The right side is wrapped in a Subquery node when it contains outer// references. Quickly skip joins that don't have this structure.@@ -106,7 +105,7 @@ fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {let original_join_filter = join.filter.clone();// Walk the subquery plan bottom-up, extracting correlated filter- // predicates into join conditions and converting scalar aggregates+ // predicates into join conditions and converting ungrouped aggregates// into group-by aggregates keyed on the correlation columns.let mut pull_up = PullUpCorrelatedExpr::new().with_need_handle_count_bug(true);let rewritten_subquery = subquery_plan.clone().rewrite(&mut pull_up).data()?;@@ -120,12 +119,9 @@ fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {return Ok(Transformed::no(LogicalPlan::Join(join)));}- // We apply the correlation predicates (extracted from the subquery's WHERE)- // as the ON clause of the rewritten join. The original ON clause is applied- // as a post-join predicate. Semantically, this is important when the join- // is rewritten as a left join; we only want outer join semantics for the- // correlation predicates (which is required for "count bug" handling), not- // the original join predicates.+ // The correlation predicates (extracted from the subquery's WHERE) become+ // the rewritten join's ON clause. See below for discussion of how the+ // user's original ON clause is handled.let correlation_filter = conjunction(pull_up.join_filters);// Look up each aggregate's default value on empty input (e.g., COUNT → 0,@@ -157,23 +153,85 @@ fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {(rewritten_subquery, correlation_filter, original_join_filter)};- // Use a left join when a scalar aggregation was pulled up (preserves- // outer rows with no matches), otherwise keep inner join.- // SELECT * FROM t0, LATERAL (SELECT sum(v1) FROM t1 WHERE t0.v0 = t1.v0); → left join- // SELECT * FROM t0, LATERAL (SELECT * FROM t1 WHERE t0.v0 = t1.v0); → inner join- let join_type = if pull_up.pulled_up_scalar_agg {- JoinType::Left- } else {- JoinType::Inner- };+ // For LEFT lateral joins, verify that all column references in the+ // correlation filter are resolvable within the join's left and right+ // schemas. If the lateral subquery references columns from an outer scope,+ // the extracted filter will contain unresolvable columns and we must skip+ // decorrelation.+ //+ // INNER lateral joins do not need this check: later optimizer passes+ // (filter pushdown, join reordering) can restructure the plan to resolve+ // cross-scope references. LEFT joins cannot be freely reordered.+ if original_join_type == JoinType::Left+ && let Some(ref filter) = correlation_filter+ {+ let left_schema = join.left.schema();+ let right_schema = right_plan.schema();+ let has_outer_scope_refs = filter+ .column_refs()+ .iter()+ .any(|col| !left_schema.has_column(col) && !right_schema.has_column(col));+ if has_outer_scope_refs {+ return Ok(Transformed::no(LogicalPlan::Join(join)));+ }+ }++ // Use a left join when the user wrote LEFT LATERAL or when a scalar+ // aggregation was pulled up (preserves outer rows with no matches).+ let join_type =+ if original_join_type == JoinType::Left || pull_up.pulled_up_scalar_agg {+ JoinType::Left+ } else {+ JoinType::Inner+ };++ // The correlation predicates (extracted from the subquery's WHERE) are+ // turned into the rewritten join's ON clause. There are three cases that+ // determine how the user's original ON clause is handled:+ //+ // - INNER lateral: user ON clause becomes a post-join filter. This restores+ // inner-join semantics if the join is upgraded to LEFT for count-bug+ // handling.+ //+ // - LEFT lateral with grouped (or no) agg: user ON clause is merged into+ // the rewritten ON clause, alongside the correlation predicates. LEFT+ // join semantics correctly preserve unmatched rows with NULLs.+ //+ // - LEFT lateral with an ungrouped aggregate (which decorrelation converts+ // to a group-by keyed on the correlation columns): user ON clause cannot+ // be placed in the join condition (it would conflict with count-bug+ // compensation) or as a post-join filter (that would remove+ // left-preserved rows). Instead, a projection is added after count-bug+ // compensation that replaces each right-side column with NULL when the ON+ // condition is not satisfied:+ //+ // CASE WHEN (on_cond) IS NOT TRUE THEN NULL ELSE <col> END+ //+ // This simulates LEFT JOIN semantics for the user's ON clause without+ // interfering with count-bug compensation.+ let (join_filter, post_join_filter, on_condition_for_projection) =+ if original_join_type == JoinType::Left {+ if pull_up.pulled_up_scalar_agg {+ (correlation_filter, None, original_join_filter)+ } else {+ let combined = conjunction(+ correlation_filter.into_iter().chain(original_join_filter),+ );+ (combined, None, None)+ }+ } else {+ (correlation_filter, original_join_filter, None)+ };+let left_field_count = join.left.schema().fields().len();let new_plan = LogicalPlanBuilder::from(join.left)- .join_on(right_plan, join_type, correlation_filter)?+ .join_on(right_plan, join_type, join_filter)?.build()?;- // Handle the count bug: after a left join, unmatched outer rows get NULLs- // for all right-side columns. But COUNT(*) over an empty group should- // return 0, not NULL. Add a projection that wraps affected expressions:+ // Handle the count bug: in the rewritten left join, unmatched outer+ // rows get NULLs for all right-side columns. But some aggregates+ // have non-NULL defaults on empty input (e.g., COUNT returns 0, not+ // NULL). Add a projection that wraps those columns:// CASE WHEN __always_true IS NULL THEN <default> ELSE <column> ENDlet new_plan = if let Some(expr_map) = collected_count_expr_map {let join_schema = new_plan.schema();@@ -202,12 +260,7 @@ fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {)],else_expr: Some(Box::new(col)),});- proj_exprs.push(Expr::Alias(expr::Alias {- expr: Box::new(case_expr),- relation: qualifier.cloned(),- name: name.to_string(),- metadata: None,- }));+ proj_exprs.push(case_expr.alias_qualified(qualifier.cloned(), name));continue;}proj_exprs.push(col);@@ -220,8 +273,47 @@ fn rewrite_internal(join: Join) -> Result<Transformed<LogicalPlan>> {new_plan};- // Apply the original ON clause as a post-join filter.- let new_plan = if let Some(on_filter) = original_join_filter {+ // For LEFT lateral joins with an ungrouped aggregate, simulate LEFT JOIN+ // semantics for the user's ON clause by adding a projection that replaces+ // right-side columns with NULL when the ON condition is false (see+ // commentary above).+ //+ // Note: the ON condition expression is duplicated per column, so this+ // assumes it is deterministic.+ let new_plan = if let Some(on_cond) = on_condition_for_projection {+ let schema = Arc::clone(new_plan.schema());+ let mut proj_exprs: Vec<Expr> = vec![];++ for (i, (qualifier, field)) in schema.iter().enumerate() {+ let col = Expr::Column(Column::new(qualifier.cloned(), field.name()));++ if i < left_field_count {+ proj_exprs.push(col);+ continue;+ }++ let typed_null =+ Expr::Literal(ScalarValue::try_from(field.data_type())?, None);+ let case_expr = Expr::Case(expr::Case {+ expr: None,+ when_then_expr: vec![(+ Box::new(Expr::IsNotTrue(Box::new(on_cond.clone()))),+ Box::new(typed_null),+ )],+ else_expr: Some(Box::new(col)),+ });+ proj_exprs.push(case_expr.alias_qualified(qualifier.cloned(), field.name()));+ }++ LogicalPlanBuilder::from(new_plan)+ .project(proj_exprs)?+ .build()?+ } else {+ new_plan+ };++ // Apply the original ON clause as a post-join filter (INNER lateral only).+ let new_plan = if let Some(on_filter) = post_join_filter {LogicalPlanBuilder::from(new_plan).filter(on_filter)?.build()?diff --git a/datafusion/sqllogictest/test_files/joins.slt b/datafusion/sqllogictest/test_files/joins.sltindex c6c8f9b6bc..e0be63fe71 100644--- a/datafusion/sqllogictest/test_files/joins.slt+++ b/datafusion/sqllogictest/test_files/joins.slt@@ -4687,14 +4687,22 @@ query TTexplain SELECT j1_string, j2_string FROM j1 LEFT JOIN LATERAL (SELECT * FROM j2 WHERE j1_id < j2_id) AS j2 ON(true);----logical_plan-01)Left Join:-02)--TableScan: j1 projection=[j1_string]-03)--SubqueryAlias: j2-04)----Projection: j2.j2_string-05)------Subquery:-06)--------Filter: outer_ref(j1.j1_id) < j2.j2_id-07)----------TableScan: j2 projection=[j2_string, j2_id]-physical_plan_error This feature is not implemented: Physical plan does not support logical expression OuterReferenceColumn(Field { name: "j1_id", data_type: Int32, nullable: true }, Column { relation: Some(Bare { table: "j1" }), name: "j1_id" })+01)Projection: j1.j1_string, j2.j2_string+02)--Left Join: Filter: j1.j1_id < j2.j2_id+03)----TableScan: j1 projection=[j1_string, j1_id]+04)----SubqueryAlias: j2+05)------TableScan: j2 projection=[j2_string, j2_id]+physical_plan+01)NestedLoopJoinExec: join_type=Left, filter=j1_id@0 < j2_id@1, projection=[j1_string@0, j2_string@2]+02)--DataSourceExec: partitions=1, partition_sizes=[0]+03)--DataSourceExec: partitions=1, partition_sizes=[0]++# INNER lateral with multi-scope correlation: the subquery references+# j1 (grandparent scope) and j2 (parent scope). The optimizer+# restructures this into a valid plan via join reordering.+query TITITI+SELECT * FROM j1, (j2 CROSS JOIN LATERAL (SELECT * FROM j3 WHERE j1_id + j2_id = j3_id) AS j3_lat);+----query TTexplain SELECT * FROM j1, (j2 LEFT JOIN LATERAL (SELECT * FROM j3 WHERE j1_id + j2_id = j3_id) AS j3 ON(true));diff --git a/datafusion/sqllogictest/test_files/lateral_join.slt b/datafusion/sqllogictest/test_files/lateral_join.sltindex ec34d62a43..cae3e67153 100644--- a/datafusion/sqllogictest/test_files/lateral_join.slt+++ b/datafusion/sqllogictest/test_files/lateral_join.slt@@ -368,7 +368,230 @@ ORDER BY t1.id, sub.data;2 b z 1###########################################################-# Section 3: Nested LATERAL joins+# Section 3: LEFT JOIN LATERAL+#+# LEFT lateral joins preserve all outer rows, producing+# NULLs on the right side when the lateral subquery returns+# no matching rows.+###########################################################++# Basic LEFT JOIN LATERAL with ON true: unmatched outer rows get NULLs+query ITT+SELECT t1.id, t1.val, sub.data+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id+) sub ON true+ORDER BY t1.id, sub.data;+----+1 a x+1 a y+2 b z+3 c NULL++# LEFT JOIN LATERAL with non-trivial ON condition (no aggregate)+query ITT+SELECT t1.id, t1.val, sub.data+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id+) sub ON sub.data = 'x'+ORDER BY t1.id;+----+1 a x+2 b NULL+3 c NULL++# LEFT JOIN LATERAL with COUNT + ON true: count bug gives 0 for empty groups+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id+) sub ON true+ORDER BY t1.id;+----+1 a 2+2 b 1+3 c 0++# LEFT JOIN LATERAL with SUM + ON true: SUM returns NULL for empty groups+query ITI+SELECT t1.id, t1.val, sub.total+FROM t1 LEFT JOIN LATERAL (+ SELECT sum(t2.id) AS total FROM t2 WHERE t2.t1_id = t1.id+) sub ON true+ORDER BY t1.id;+----+1 a 30+2 b 30+3 c NULL++# LEFT JOIN LATERAL with COUNT + non-trivial ON: ON-nullification+# For t1.id=3, the lateral produces cnt=0 (count bug default), but+# ON 0>0 is false, so the LEFT join preserves the row with NULLs.+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id+) sub ON sub.cnt > 0+ORDER BY t1.id;+----+1 a 2+2 b 1+3 c NULL++# LEFT JOIN LATERAL with COUNT + non-trivial ON referencing both sides+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id+) sub ON sub.cnt * 2 > t1.id+ORDER BY t1.id;+----+1 a 2+2 b NULL+3 c NULL++# Multiple aggregates (COUNT + SUM) + non-trivial ON+# COUNT should be NULL (not 0) when ON fails; SUM should also be NULL+query ITII+SELECT t1.id, t1.val, sub.cnt, sub.total+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt, sum(t2.id) AS total+ FROM t2 WHERE t2.t1_id = t1.id+) sub ON sub.cnt > 0+ORDER BY t1.id;+----+1 a 2 30+2 b 1 30+3 c NULL NULL++# LEFT JOIN LATERAL with GROUP BY (not scalar agg, no count bug)+query ITTI+SELECT t1.id, t1.val, sub.data, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data, count(*) AS cnt FROM t2+ WHERE t2.t1_id = t1.id GROUP BY t2.data+) sub ON true+ORDER BY t1.id, sub.data;+----+1 a x 1+1 a y 1+2 b z 1+3 c NULL NULL++# LEFT JOIN LATERAL with inequality correlation+query II+SELECT i1.i, sub.j+FROM integers i1 LEFT JOIN LATERAL (+ SELECT i2.i AS j FROM integers i2 WHERE i2.i > i1.i+) sub ON true+ORDER BY i1.i, sub.j;+----+1 2+1 3+2 3+3 NULL+NULL NULL++# LEFT JOIN LATERAL where no inner rows match any outer row+query IT+SELECT t1.id, sub.data+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id AND t2.t1_id > 999+) sub ON true+ORDER BY t1.id;+----+1 NULL+2 NULL+3 NULL++# Validate: LEFT LATERAL with COUNT + ON true gives same result+# as comma LATERAL (both use count bug compensation)+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1, LATERAL (SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id) AS sub+ORDER BY t1.id;+----+1 a 2+2 b 1+3 c 0++# Post-join WHERE filter must eliminate NULL-producing LEFT lateral rows.+# Regression test for the class of bug in duckdb/duckdb#21609.+query ITT+SELECT t1.id, t1.val, sub.data+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id+) sub ON true+WHERE sub.data IS NOT NULL+ORDER BY t1.id, sub.data;+----+1 a x+1 a y+2 b z++# Post-join WHERE after count-bug compensation: the WHERE must see the+# compensated value (0 for COUNT, not NULL).+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id+) sub ON true+WHERE sub.cnt > 0+ORDER BY t1.id;+----+1 a 2+2 b 1++# Full pipeline: LEFT + COUNT + non-trivial ON + post-join WHERE.+# Decorrelation → count-bug compensation → ON-nullification → WHERE.+query ITI+SELECT t1.id, t1.val, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM t2 WHERE t2.t1_id = t1.id+) sub ON sub.cnt > 0+WHERE t1.id <= 2+ORDER BY t1.id;+----+1 a 2+2 b 1++# Empty left table + LEFT LATERAL produces 0 rows+query IT+SELECT t1.id, sub.data+FROM (SELECT 1 AS id WHERE false) t1+LEFT JOIN LATERAL (SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id) sub ON true;+----++# LEFT LATERAL + NULL correlation keys + COUNT: count-bug compensation+# must produce 0 when the correlation key is NULL (NULL=NULL is unknown).+query II+SELECT i1.i, sub.cnt+FROM integers i1 LEFT JOIN LATERAL (+ SELECT count(*) AS cnt FROM integers i2 WHERE i2.i = i1.i+) sub ON true+ORDER BY i1.i;+----+1 1+2 1+3 1+NULL 0++# LEFT JOIN LATERAL with GROUP BY + non-trivial ON: the ON condition+# is merged into the join condition (no ON-nullification needed).+query ITTI+SELECT t1.id, t1.val, sub.data, sub.cnt+FROM t1 LEFT JOIN LATERAL (+ SELECT t2.data, count(*) AS cnt FROM t2+ WHERE t2.t1_id = t1.id GROUP BY t2.data+) sub ON sub.data >= 'y'+ORDER BY t1.id, sub.data;+----+1 a y 1+2 b z 1+3 c NULL NULL++###########################################################+# Section 4: Nested LATERAL joins############################################################ Both levels correlate via WHERE with their sibling table@@ -403,8 +626,25 @@ ORDER BY t1.id, sub.t2_id;1 20 12 30 1+# Nested LEFT JOIN LATERAL: outer LEFT preserves unmatched outer rows+query III+SELECT t1.id, sub.t2_id, sub.t3_id+FROM t1 LEFT JOIN LATERAL (+ SELECT t2_sub.id AS t2_id, t3_sub.id AS t3_id+ FROM t2 AS t2_sub LEFT JOIN LATERAL (+ SELECT t3.id FROM t3 WHERE t3.t2_id = t2_sub.id+ ) AS t3_sub ON true+ WHERE t2_sub.t1_id = t1.id+) AS sub ON true+ORDER BY t1.id, sub.t2_id, sub.t3_id;+----+1 10 100+1 20 200+2 30 300+3 NULL NULL+###########################################################-# Section 4: Semantically invalid queries (permanent errors)+# Section 5: Semantically invalid queries (permanent errors)############################################################ FULL/RIGHT JOIN LATERAL are invalid per the SQL standard: the right@@ -426,13 +666,12 @@ statement errorSELECT * FROM integers, LATERAL (SELECT SUM(i) AS s) t;###########################################################-# Section 5: Currently unsupported patterns+# Section 6: Currently unsupported patterns#-# These are valid SQL that DataFusion cannot decorrelate yet.+# These are valid queries that DataFusion cannot decorrelate yet.# The primary limitation is that outer references must appear-# in WHERE clauses. Outer references in SELECT expressions,-# inside aggregate arguments, or in LEFT JOIN LATERAL are not-# yet supported.+# in WHERE clauses: outer references in SELECT expressions or+# inside aggregate arguments are not yet supported.############################################################ --- Outer reference in SELECT expression (not WHERE) ---@@ -460,23 +699,26 @@ FROM integers i1,LATERAL (SELECT sub1.j + 1 AS k) sub2ORDER BY i1.i;-# --- LEFT JOIN LATERAL ---+# --- LEFT JOIN LATERAL with outer ref in SELECT ---+# These fail because outer references in the SELECT list (not WHERE)+# cannot be decorrelated yet, not because LEFT lateral is unsupported.+# LEFT lateral with outer refs only in WHERE works — see Section 3.-# LEFT JOIN preserving unmatched outer rows with filter+# LEFT JOIN with outer ref in SELECT expressionstatement error OuterReferenceColumnSELECT i1.i, sub.bFROM integers i1LEFT JOIN LATERAL (SELECT i1.i AS b WHERE i1.i IN (1, 3)) sub ON (i1.i = sub.b)ORDER BY i1.i;-# LEFT JOIN where all rows match+# LEFT JOIN with outer ref in SELECT, all rows matchstatement error OuterReferenceColumnSELECT i1.i, sub.bFROM integers i1LEFT JOIN LATERAL (SELECT i1.i AS b) sub ON (i1.i = sub.b)ORDER BY i1.i;-# LEFT JOIN where no rows match (all NULLs on right)+# LEFT JOIN with outer ref in SELECT, no rows matchstatement error OuterReferenceColumnSELECT i1.i, sub.bFROM integers i1@@ -506,7 +748,7 @@ SELECT name, total FROM students,(SELECT SUM(grade) AS total FROM exams WHERE exams.sid = students.id) grades;###########################################################-# Section 6: EXPLAIN plan verification+# Section 7: EXPLAIN plan verification############################################################ Verify the COUNT bug fix: Left Join with CASE WHEN compensation@@ -536,6 +778,24 @@ physical_plan09)--------------AggregateExec: mode=Partial, gby=[t1_id@0 as t1_id], aggr=[count(Int64(1))]10)----------------DataSourceExec: partitions=1, partition_sizes=[1]+# Verify LEFT lateral without aggregate decorrelates to left join+# (no post-join filter — ON merged into join condition)+query TT+EXPLAIN SELECT t1.id, sub.data+FROM t1 LEFT JOIN LATERAL (SELECT t2.data FROM t2 WHERE t2.t1_id = t1.id) AS sub ON true;+----+logical_plan+01)Projection: t1.id, sub.data+02)--Left Join: t1.id = sub.t1_id+03)----TableScan: t1 projection=[id]+04)----SubqueryAlias: sub+05)------Projection: t2.data, t2.t1_id+06)--------TableScan: t2 projection=[t1_id, data]+physical_plan+01)HashJoinExec: mode=CollectLeft, join_type=Left, on=[(id@0, t1_id@1)], projection=[id@0, data@1]+02)--DataSourceExec: partitions=1, partition_sizes=[1]+03)--DataSourceExec: partitions=1, partition_sizes=[1]+# Verify non-aggregate lateral decorrelates to inner joinquery TTEXPLAIN SELECT t1.id, sub.datadiff --git a/docs/source/user-guide/sql/select.md b/docs/source/user-guide/sql/select.mdindex 7ab6ed1aea..3564884b04 100644--- a/docs/source/user-guide/sql/select.md+++ b/docs/source/user-guide/sql/select.md@@ -86,7 +86,7 @@ SELECT a FROM table WHERE a > 10## JOIN clause-DataFusion supports `INNER JOIN`, `LEFT OUTER JOIN`, `RIGHT OUTER JOIN`, `FULL OUTER JOIN`, `NATURAL JOIN`, `CROSS JOIN`, `LEFT SEMI JOIN`, `RIGHT SEMI JOIN`, `LEFT ANTI JOIN`, `RIGHT ANTI JOIN`, and `LATERAL JOIN`.+DataFusion supports `INNER JOIN`, `LEFT OUTER JOIN`, `RIGHT OUTER JOIN`, `FULL OUTER JOIN`, `NATURAL JOIN`, `CROSS JOIN`, `LEFT SEMI JOIN`, `RIGHT SEMI JOIN`, `LEFT ANTI JOIN`, `RIGHT ANTI JOIN`, `LATERAL JOIN`, and `LEFT JOIN LATERAL`.The following examples are based on this table:@@ -318,11 +318,53 @@ ORDER BY dept;+------+-------+-----+```+#### LEFT JOIN LATERAL++`LEFT JOIN LATERAL` preserves all rows from the left table. When the lateral+subquery produces no matching rows, the right-side columns are filled with+NULLs.++```sql+SELECT d.name AS dept, e.name AS emp+FROM departments d+LEFT JOIN LATERAL (+ SELECT employees.name FROM employees WHERE employees.dept_id = d.id+) AS e ON true+ORDER BY dept, emp;++-------+-------++| dept | emp |++-------+-------++| Eng | Carol |+| HR | Alice |+| HR | Bob |+| Sales | NULL |++-------+-------++```++The `ON` clause can also filter results. Rows that do not satisfy the `ON`+condition are preserved with NULLs, just like a regular `LEFT JOIN`:++```sql+SELECT d.name AS dept, sub.cnt+FROM departments d+LEFT JOIN LATERAL (+ SELECT count(*) AS cnt+ FROM employees WHERE employees.dept_id = d.id+) AS sub ON sub.cnt > 0+ORDER BY dept;++-------+------++| dept | cnt |++-------+------++| Eng | 1 |+| HR | 2 |+| Sales | NULL |++-------+------++```+#### LimitationsThe following patterns are not yet supported:-- `LEFT JOIN LATERAL` (lateral join with outer join semantics).- Outer references in the `SELECT` list of the lateral subquery (e.g., `LATERAL (SELECT outer.col + 1)`).- `HAVING` in lateral subqueries.