planner: lateral join support | tidb-test=pr/2664

errors.toml

@@ -2701,6 +2701,11 @@ error = '''
 Variable '%s' might not be affected by SET_VAR hint.
 '''
 
+["planner:3809"]
+error = '''
+Invalid use of LATERAL: %s
+'''
+
 ["planner:8006"]
 error = '''
 `%s` is unsupported on temporary tables.

pkg/errno/errcode.go

@@ -919,6 +919,7 @@ const (
 	ErrDefValGeneratedNamedFunctionIsNotAllowed              = 3770
 	ErrFKIncompatibleColumns                                 = 3780
 	ErrFunctionalIndexRowValueIsNotAllowed                   = 3800
+	ErrInvalidLateralJoin                                    = 3809
 	ErrNonBooleanExprForCheckConstraint                      = 3812
 	ErrColumnCheckConstraintReferencesOtherColumn            = 3813
 	ErrCheckConstraintNamedFunctionIsNotAllowed              = 3814

pkg/errno/errname.go

@@ -913,6 +913,7 @@ var MySQLErrName = map[uint16]*mysql.ErrMessage{
 	ErrFunctionalIndexOnField:                                mysql.Message("Expression index on a column is not supported. Consider using a regular index instead", nil),
 	ErrFKIncompatibleColumns:                                 mysql.Message("Referencing column '%s' and referenced column '%s' in foreign key constraint '%s' are incompatible.", nil),
 	ErrFunctionalIndexRowValueIsNotAllowed:                   mysql.Message("Expression of expression index '%s' cannot refer to a row value", nil),
+	ErrInvalidLateralJoin:                                    mysql.Message("Invalid use of LATERAL: %s", nil),
 	ErrNonBooleanExprForCheckConstraint:                      mysql.Message("An expression of non-boolean type specified to a check constraint '%s'.", nil),
 	ErrColumnCheckConstraintReferencesOtherColumn:            mysql.Message("Column check constraint '%s' references other column.", nil),
 	ErrCheckConstraintNamedFunctionIsNotAllowed:              mysql.Message("An expression of a check constraint '%s' contains disallowed function: %s.", nil),

pkg/parser/BUILD.bazel

@@ -43,6 +43,7 @@ go_test(
         "digester_test.go",
         "hintparser_test.go",
         "keywords_test.go",
+        "lateral_test.go",
         "lexer_test.go",
         "main_test.go",
         "parser_test.go",

pkg/parser/ast/dml.go

@@ -535,6 +535,15 @@ type TableSource struct {
 
 	// AsName is the alias name of the table source.
 	AsName CIStr
+
+	// Lateral indicates whether this is a LATERAL derived table.
+	// MySQL 8.0+ syntax: FROM t1, LATERAL (SELECT ...) AS dt
+	// LATERAL allows the derived table to reference columns from tables to its left.
+	Lateral bool
+
+	// ColumnNames is the optional column alias list for derived tables.
+	// e.g. LATERAL (SELECT ...) AS dt(c1, c2)
+	ColumnNames []CIStr
 }
 
 func (*TableSource) resultSet() {}
@@ -547,6 +556,11 @@ func (n *TableSource) Restore(ctx *format.RestoreCtx) error {
 		needParen = true
 	}
 
+	// Output LATERAL keyword if this is a LATERAL derived table
+	if n.Lateral {
+		ctx.WriteKeyWord("LATERAL ")
+	}
+
 	if tn, tnCase := n.Source.(*TableName); tnCase {
 		if needParen {
 			ctx.WritePlain("(")
@@ -592,6 +606,16 @@ func (n *TableSource) Restore(ctx *format.RestoreCtx) error {
 		if asName := n.AsName.String(); asName != "" {
 			ctx.WriteKeyWord(" AS ")
 			ctx.WriteName(asName)
+			if len(n.ColumnNames) > 0 {
+				ctx.WritePlain("(")
+				for i, col := range n.ColumnNames {
+					if i > 0 {
+						ctx.WritePlain(", ")
+					}
+					ctx.WriteName(col.String())
+				}
+				ctx.WritePlain(")")
+			}
 		}
 	}
 

pkg/parser/keywords_test.go

@@ -36,15 +36,15 @@ func TestKeywords(t *testing.T) {
 }
 
 func TestKeywordsLength(t *testing.T) {
-	require.Equal(t, 676, len(parser.Keywords))
+	require.Equal(t, 677, len(parser.Keywords))
 
 	reservedNr := 0
 	for _, kw := range parser.Keywords {
 		if kw.Reserved {
 			reservedNr += 1
 		}
 	}
-	require.Equal(t, 232, reservedNr)
+	require.Equal(t, 233, reservedNr)
 }
 
 func TestKeywordsSorting(t *testing.T) {

pkg/parser/lateral_test.go

@@ -0,0 +1,196 @@
+// Copyright 2026 PingCAP, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package parser_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/pingcap/tidb/pkg/parser"
+	"github.com/pingcap/tidb/pkg/parser/ast"
+	"github.com/pingcap/tidb/pkg/parser/format"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLateralParsing(t *testing.T) {
+	p := parser.New()
+
+	testCases := []struct {
+		name         string
+		sql          string
+		expectError  bool
+		checkLateral bool // whether to verify Lateral flag is set
+		columnNames  []string
+	}{
+		{
+			name:         "LATERAL with comma syntax",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT t1.a) AS dt",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with LEFT JOIN",
+			sql:          "SELECT * FROM t1 LEFT JOIN LATERAL (SELECT t1.b) AS dt ON true",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with CROSS JOIN",
+			sql:          "SELECT * FROM t1 CROSS JOIN LATERAL (SELECT t1.c) AS dt",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with RIGHT JOIN",
+			sql:          "SELECT * FROM t1 RIGHT JOIN LATERAL (SELECT t1.d) AS dt ON true",
+			expectError:  false, // Parser allows it, planner will reject
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with INNER JOIN",
+			sql:          "SELECT * FROM t1 JOIN LATERAL (SELECT t1.e) AS dt ON true",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with complex subquery",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT t1.a, COUNT(*) FROM t2 WHERE t2.x = t1.x GROUP BY t1.a) AS dt",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with nested subquery",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT * FROM (SELECT t1.a) AS inner_dt) AS dt",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "Multiple LATERAL joins",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT t1.a) AS dt1, LATERAL (SELECT t1.b) AS dt2",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:        "Non-LATERAL derived table",
+			sql:         "SELECT * FROM t1, (SELECT a FROM t2) AS dt",
+			expectError: false,
+			// Lateral flag should be false for non-LATERAL
+		},
+		{
+			name:         "LATERAL with WHERE clause",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT * FROM t2 WHERE t2.x = t1.x) AS dt WHERE dt.y > 10",
+			expectError:  false,
+			checkLateral: true,
+		},
+		{
+			name:         "LATERAL with column list",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT t1.a, t1.b) AS dt(c1, c2)",
+			expectError:  false,
+			checkLateral: true,
+			columnNames:  []string{"c1", "c2"},
+		},
+		{
+			name:         "LATERAL with column list no AS",
+			sql:          "SELECT * FROM t1, LATERAL (SELECT t1.a) dt(col1)",
+			expectError:  false,
+			checkLateral: true,
+			columnNames:  []string{"col1"},
+		},
+		{
+			name:         "LATERAL with column list and JOIN",
+			sql:          "SELECT * FROM t1 LEFT JOIN LATERAL (SELECT t1.a, t1.b, t1.c) AS dt(x, y, z) ON true",
+			expectError:  false,
+			checkLateral: true,
+			columnNames:  []string{"x", "y", "z"},
+		},
+		{
+			name:        "LATERAL without alias is rejected",
+			sql:         "SELECT * FROM t1, LATERAL (SELECT t1.a)",
+			expectError: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			stmt, err := p.ParseOneStmt(tc.sql, "", "")
+
+			if tc.expectError {
+				require.Error(t, err, "Expected parsing to fail for: %s", tc.sql)
+				return
+			}
+
+			require.NoError(t, err, "Failed to parse: %s", tc.sql)
+			require.NotNil(t, stmt)
+
+			// Test round-trip: parse -> restore -> parse again
+			var sb strings.Builder
+			restoreCtx := format.NewRestoreCtx(format.RestoreStringSingleQuotes, &sb)
+			err = stmt.Restore(restoreCtx)
+			require.NoError(t, err, "Failed to restore statement")
+
+			restored := sb.String()
+			if tc.checkLateral {
+				// Verify LATERAL keyword is preserved in restoration
+				require.Contains(t, restored, "LATERAL", "LATERAL keyword missing in restored SQL: %s", restored)
+			}
+
+			// Parse the restored SQL to ensure it's valid (round-trip test)
+			stmt2, err := p.ParseOneStmt(restored, "", "")
+			require.NoError(t, err, "Failed to parse restored SQL: %s", restored)
+			require.NotNil(t, stmt2)
+
+			// Verify AST flag: check if LATERAL table sources exist
+			if tc.checkLateral {
+				selectStmt, ok := stmt.(*ast.SelectStmt)
+				require.True(t, ok, "Statement should be SelectStmt")
+				require.NotNil(t, selectStmt.From, "FROM clause should not be nil")
+
+				// Verify at least one LATERAL table source exists in the FROM clause
+				lateralTS := findLateralTableSource(selectStmt.From.TableRefs)
+				require.NotNil(t, lateralTS, "LATERAL TableSource not found in AST for: %s", tc.sql)
+
+				// Verify column names if expected
+				if len(tc.columnNames) > 0 {
+					require.Len(t, lateralTS.ColumnNames, len(tc.columnNames), "column name count mismatch")
+					for i, expected := range tc.columnNames {
+						require.Equal(t, expected, lateralTS.ColumnNames[i].L, "column name mismatch at index %d", i)
+					}
+				}
+			}
+		})
+	}
+}
+
+// findLateralTableSource recursively searches for the first LATERAL TableSource in a ResultSetNode.
+func findLateralTableSource(node ast.ResultSetNode) *ast.TableSource {
+	if node == nil {
+		return nil
+	}
+
+	switch n := node.(type) {
+	case *ast.TableSource:
+		if n.Lateral {
+			return n
+		}
+		return findLateralTableSource(n.Source)
+	case *ast.Join:
+		if ts := findLateralTableSource(n.Left); ts != nil {
+			return ts
+		}
+		return findLateralTableSource(n.Right)
+	}
+
+	return nil
+}

pkg/parser/misc.go

@@ -508,6 +508,7 @@ var tokenMap = map[string]int{
 	"LAST_BACKUP":                    lastBackup,
 	"LAST":                           last,
 	"LASTVAL":                        lastval,
+	"LATERAL":                        lateral,
 	"LEADER":                         leader,
 	"LEADER_CONSTRAINTS":             leaderConstraints,
 	"LEADING":                        leading,

pkg/parser/mysql/errcode.go

@@ -948,6 +948,7 @@ const (
 	ErrFunctionalIndexOnField                                = 3762
 	ErrFKIncompatibleColumns                                 = 3780
 	ErrFunctionalIndexRowValueIsNotAllowed                   = 3800
+	ErrInvalidLateralJoin                                    = 3809
 	ErrDependentByFunctionalIndex                            = 3837
 	ErrInvalidJSONType                                       = 3853
 	ErrInvalidJsonValueForFuncIndex                          = 3903 //nolint: revive