From 4d1e17d248249682be17fa293cd0c699353efe50 Mon Sep 17 00:00:00 2001 From: tpp Date: Wed, 18 Mar 2026 11:27:54 -0700 Subject: [PATCH 1/8] docs: add LATERAL derived tables documentation Document the LATERAL derived table syntax support added in pingcap/tidb#67076. Includes a new page with syntax, examples, and current limitations, plus updates to mysql-compatibility.md and TOC.md. Co-Authored-By: Claude Sonnet 4.6 --- TOC.md | 1 + lateral-derived-tables.md | 66 +++++++++++++++++++++++++++++++++++++++ mysql-compatibility.md | 2 +- 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 lateral-derived-tables.md diff --git a/TOC.md b/TOC.md index 494098945fadd..6b088d2fcedf1 100644 --- a/TOC.md +++ b/TOC.md @@ -279,6 +279,7 @@ - [Subquery Related Optimizations](/subquery-optimization.md) - [Column Pruning](/column-pruning.md) - [Decorrelation of Correlated Subquery](/correlated-subquery-optimization.md) + - [LATERAL Derived Tables](/lateral-derived-tables.md) - [Eliminate Max/Min](/max-min-eliminate.md) - [Predicates Push Down](/predicate-push-down.md) - [Partition Pruning](/partition-pruning.md) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md new file mode 100644 index 0000000000000..a49acac63b830 --- /dev/null +++ b/lateral-derived-tables.md @@ -0,0 +1,66 @@ +--- +title: LATERAL Derived Tables +summary: Learn how to use LATERAL derived tables in TiDB. +--- + +# LATERAL Derived Tables + +A **lateral derived table** is a subquery in the `FROM` clause that can reference columns from tables that appear earlier in the same `FROM` clause. This makes it more powerful than a standard derived table, whose subquery cannot reference outer columns in the same `FROM` clause. + +TiDB recognizes the `LATERAL` syntax for derived tables, following MySQL 8.0 compatibility ([WL#8652](https://dev.mysql.com/worklog/task/?id=8652)). + +> **Note:** +> +> Currently, TiDB supports parsing LATERAL derived table syntax, but execution is not yet supported and will return an error. Full execution support is tracked in [#40328](https://github.com/pingcap/tidb/issues/40328). + +## Syntax + +```sql +SELECT ... FROM table_ref, LATERAL (subquery) [AS] alias [(col_list)] ... +SELECT ... FROM table_ref [LEFT] JOIN LATERAL (subquery) [AS] alias [(col_list)] ON ... +``` + +- The `LATERAL` keyword must precede the derived table subquery. +- A table alias is required after the closing parenthesis of the subquery. +- The `AS` keyword before the alias is optional. +- An optional derived column list can follow the alias: `LATERAL (...) AS dt(col1, col2)`. + +## Examples + +### Comma join + +```sql +SELECT * FROM t1, LATERAL (SELECT * FROM t2 WHERE t2.id = t1.id) AS dt; +``` + +In this example, the subquery references `t1.id`, a column from the preceding table `t1`. A regular derived table (without `LATERAL`) cannot do this. + +### LEFT JOIN with a derived column list + +```sql +SELECT t1.id, dt.val +FROM t1 +LEFT JOIN LATERAL (SELECT t2.val FROM t2 WHERE t2.id = t1.id LIMIT 1) AS dt(val) +ON TRUE; +``` + +The derived column list `(val)` renames the columns produced by the subquery. + +## Comparison with standard derived tables + +| Feature | Standard derived table | LATERAL derived table | +|---|---|---| +| Can reference outer `FROM` columns | No | Yes | +| Alias required | Yes | Yes | +| Derived column list | Supported | Supported | + +## MySQL compatibility + +TiDB's LATERAL derived table syntax is compatible with MySQL 8.0. Once full execution support is available, queries that use `LATERAL` in MySQL should also work in TiDB. + +## See also + +- [Subquery Related Optimizations](/subquery-optimization.md) +- [Decorrelation of Correlated Subquery](/correlated-subquery-optimization.md) +- [Explain Statements That Use Subqueries](/explain-subqueries.md) +- [MySQL Compatibility](/mysql-compatibility.md) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index ad765d8e93924..bd6901cf0e91a 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -71,7 +71,7 @@ You can try out TiDB features on [TiDB Playground](https://play.tidbcloud.com/?u + "Session Tracker: Add GTIDs context to the OK packet" + Descending Index [#2519](https://github.com/pingcap/tidb/issues/2519) + `SKIP LOCKED` syntax [#18207](https://github.com/pingcap/tidb/issues/18207) -+ Lateral derived tables [#40328](https://github.com/pingcap/tidb/issues/40328) ++ Lateral derived tables (syntax is recognized but execution is not yet supported) [#40328](https://github.com/pingcap/tidb/issues/40328). For syntax details, see [LATERAL Derived Tables](/lateral-derived-tables.md). ## Differences from MySQL From 9cfbdfa73e2830add25ecaff572bc4dff22af5b4 Mon Sep 17 00:00:00 2001 From: tpp Date: Wed, 18 Mar 2026 11:57:48 -0700 Subject: [PATCH 2/8] docs: add LATERAL as reserved keyword LATERAL was added as a reserved keyword in pingcap/tidb#67076. Co-Authored-By: Claude Sonnet 4.6 --- keywords.md | 1 + 1 file changed, 1 insertion(+) diff --git a/keywords.md b/keywords.md index 5b080f17fb632..73a1feec7cd05 100644 --- a/keywords.md +++ b/keywords.md @@ -395,6 +395,7 @@ The following list shows the keywords in TiDB. Reserved keywords are marked with - LASTVAL - LEAD (R-Window) - LEADING (R) +- LATERAL (R) - LEAVE (R) - LEFT (R) - LESS From f600b3048d7136fea034fca6a11a2bd3ad1ca97f Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 11:59:09 -0700 Subject: [PATCH 3/8] Update lateral-derived-tables.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index a49acac63b830..e60f6fde057c8 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -44,7 +44,7 @@ LEFT JOIN LATERAL (SELECT t2.val FROM t2 WHERE t2.id = t1.id LIMIT 1) AS dt(val) ON TRUE; ``` -The derived column list `(val)` renames the columns produced by the subquery. +The derived column list `(val)` renames the columns that the subquery returns. ## Comparison with standard derived tables From 29ada8778ad3060191c3cf73f49f5c910dbd0617 Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 11:59:19 -0700 Subject: [PATCH 4/8] Update lateral-derived-tables.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index e60f6fde057c8..f8cbc0dc0b86d 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -11,7 +11,7 @@ TiDB recognizes the `LATERAL` syntax for derived tables, following MySQL 8.0 com > **Note:** > -> Currently, TiDB supports parsing LATERAL derived table syntax, but execution is not yet supported and will return an error. Full execution support is tracked in [#40328](https://github.com/pingcap/tidb/issues/40328). +Currently, TiDB supports parsing the `LATERAL` derived table syntax, but its execution is not yet supported and will return an error. You can track the progress for full execution support in issue [#40328](https://github.com/pingcap/tidb/issues/40328). ## Syntax From 9a2db584c30218c61d9b2b3d685320c1576c3ca9 Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 21:49:27 -0700 Subject: [PATCH 5/8] Update lateral-derived-tables.md Co-authored-by: Grace Cai --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index f8cbc0dc0b86d..0a15b4a8519dc 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -1,6 +1,6 @@ --- title: LATERAL Derived Tables -summary: Learn how to use LATERAL derived tables in TiDB. +summary: Learn the syntax and current limitations of LATERAL derived tables in TiDB. --- # LATERAL Derived Tables From 4932c5c0204e3a875f8c13720958465bd7538ffb Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 21:49:37 -0700 Subject: [PATCH 6/8] Update lateral-derived-tables.md Co-authored-by: Grace Cai --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index 0a15b4a8519dc..5f057f361e80e 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -11,7 +11,7 @@ TiDB recognizes the `LATERAL` syntax for derived tables, following MySQL 8.0 com > **Note:** > -Currently, TiDB supports parsing the `LATERAL` derived table syntax, but its execution is not yet supported and will return an error. You can track the progress for full execution support in issue [#40328](https://github.com/pingcap/tidb/issues/40328). +> Currently, TiDB supports parsing the `LATERAL` derived table syntax, but its execution is not yet supported and will return an error. You can track the progress for full execution support in issue [#40328](https://github.com/pingcap/tidb/issues/40328). ## Syntax From 1f798508eda6f27960c8c24aebd7692c62ec5994 Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 21:49:50 -0700 Subject: [PATCH 7/8] Update lateral-derived-tables.md Co-authored-by: Grace Cai --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index 5f057f361e80e..76bcc9dff3051 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -56,7 +56,7 @@ The derived column list `(val)` renames the columns that the subquery returns. ## MySQL compatibility -TiDB's LATERAL derived table syntax is compatible with MySQL 8.0. Once full execution support is available, queries that use `LATERAL` in MySQL should also work in TiDB. +TiDB's LATERAL derived table syntax is compatible with MySQL 8.0 at the syntax level. ## See also From 68dcfad3d8a9d4acfd81341d5c46b1c80182e2ea Mon Sep 17 00:00:00 2001 From: tpp <146148086+terry1purcell@users.noreply.github.com> Date: Wed, 18 Mar 2026 21:49:59 -0700 Subject: [PATCH 8/8] Update lateral-derived-tables.md Co-authored-by: Grace Cai --- lateral-derived-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lateral-derived-tables.md b/lateral-derived-tables.md index 76bcc9dff3051..0f85c8f12b02f 100644 --- a/lateral-derived-tables.md +++ b/lateral-derived-tables.md @@ -7,7 +7,7 @@ summary: Learn the syntax and current limitations of LATERAL derived tables in T A **lateral derived table** is a subquery in the `FROM` clause that can reference columns from tables that appear earlier in the same `FROM` clause. This makes it more powerful than a standard derived table, whose subquery cannot reference outer columns in the same `FROM` clause. -TiDB recognizes the `LATERAL` syntax for derived tables, following MySQL 8.0 compatibility ([WL#8652](https://dev.mysql.com/worklog/task/?id=8652)). +TiDB recognizes the `LATERAL` syntax for derived tables, following the MySQL 8.0 syntax ([WL#8652](https://dev.mysql.com/worklog/task/?id=8652)). > **Note:** >