Skip to content

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.rs
index 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> END
let 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.slt
index c6c8f9b6bc..e0be63fe71 100644
--- a/datafusion/sqllogictest/test_files/joins.slt
+++ b/datafusion/sqllogictest/test_files/joins.slt
@@ -4687,14 +4687,22 @@ query TT
explain 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 TT
explain 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.slt
index 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 1
2 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 error
SELECT * 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) sub2
ORDER 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 expression
statement error OuterReferenceColumn
SELECT i1.i, sub.b
FROM integers i1
LEFT 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 match
statement error OuterReferenceColumn
SELECT i1.i, sub.b
FROM integers i1
LEFT 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 match
statement error OuterReferenceColumn
SELECT i1.i, sub.b
FROM 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_plan
09)--------------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 join
query TT
EXPLAIN SELECT t1.id, sub.data
diff --git a/docs/source/user-guide/sql/select.md b/docs/source/user-guide/sql/select.md
index 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 |
++-------+------+
+```
+
#### Limitations
The 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.