From 62c69781806d442de6bfcd255165699c1770601b Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 4 Mar 2026 15:49:32 +0800 Subject: [PATCH 1/2] nontransactional dml FAQ about alias --- non-transactional-dml.md | 21 +++++++++++++++++++++ sql-statements/sql-statement-batch.md | 4 ++++ 2 files changed, 25 insertions(+) diff --git a/non-transactional-dml.md b/non-transactional-dml.md index 248d9077d23db..ff61867c45c9b 100644 --- a/non-transactional-dml.md +++ b/non-transactional-dml.md @@ -366,6 +366,27 @@ SELECT t2.id, t2.v, t3.id FROM t2 JOIN t3 ON t2.id = t3.id +----------------+---------------+ ``` +### The `Unknown column '.' in 'where clause'` error occurs when using table aliases in non-transactional DML statements + +When you execute a non-transactional DML statement, TiDB internally constructs a query for dividing batches and then generates the actual split execution statements. You can use [`DRY RUN QUERY`](/non-transactional-dml.md#query-the-batch-dividing-statement) and [`DRY RUN`](/non-transactional-dml.md#query-the-statements-corresponding-to-the-first-and-the-last-batches) to view these two types of statements, respectively. + +In the current version, the rewritten statements might not preserve the table aliases from the original DML statement. Therefore, if you use the `.` format to reference columns in a `WHERE` clause or other expressions, an `Unknown column` error might occur. + +For example, the following statement might return an error in some cases: + +```sql +BATCH ON t_old.id LIMIT 5000 +INSERT INTO t_new +SELECT * FROM t_old AS t +WHERE t.c1 IS NULL; +``` + +To avoid this error, follow these recommendations: + +- Avoid using table aliases in non-transactional DML statements. For example, rewrite `t.c1` as `c1` or `t_old.c1`. +- When specifying the [shard column](#parameters), do not use table aliases. For example, rewrite `BATCH ON t.id` as `BATCH ON db.t_old.id` or `BATCH ON t_old.id`. +- Before execution, use `DRY RUN QUERY` or `DRY RUN` to preview the rewritten statements and verify that they meet your expectations. + ### The actual batch size is not the same as the specified batch size During the execution of a non-transactional DML statement, the size of data to be processed in the last batch might be smaller than the specified batch size. diff --git a/sql-statements/sql-statement-batch.md b/sql-statements/sql-statement-batch.md index 3f8451a6a4865..af8848d3a4808 100644 --- a/sql-statements/sql-statement-batch.md +++ b/sql-statements/sql-statement-batch.md @@ -27,6 +27,10 @@ BATCH ON id LIMIT 1 INSERT INTO t SELECT t2.id, t2.v, t3.v FROM t2 JOIN t3 ON t2 Non-transactional DML, shard column must be fully specified ``` +> **Note:** +> +> The `BATCH` statement is internally rewritten and split into multiple DML statements during execution. In the current version, table aliases might not be preserved, which can result in errors such as `Unknown column ... in 'where clause'`. To avoid this issue, do not use table aliases. Before execution, use `DRY RUN QUERY` or `DRY RUN` to preview the split statements before execution. For more information, see [Non-Transactional DML Statements](/non-transactional-dml.md). + ## Synopsis ```ebnf+diagram From 1811e5871f8448612f2deb8efa0685ea580ba116 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 4 Mar 2026 16:27:06 +0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: xixirangrang --- non-transactional-dml.md | 2 +- sql-statements/sql-statement-batch.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/non-transactional-dml.md b/non-transactional-dml.md index ff61867c45c9b..bcace30d98378 100644 --- a/non-transactional-dml.md +++ b/non-transactional-dml.md @@ -384,7 +384,7 @@ WHERE t.c1 IS NULL; To avoid this error, follow these recommendations: - Avoid using table aliases in non-transactional DML statements. For example, rewrite `t.c1` as `c1` or `t_old.c1`. -- When specifying the [shard column](#parameters), do not use table aliases. For example, rewrite `BATCH ON t.id` as `BATCH ON db.t_old.id` or `BATCH ON t_old.id`. +- When specifying the [shard column](#parameter-description), do not use table aliases. For example, rewrite `BATCH ON t.id` as `BATCH ON db.t_old.id` or `BATCH ON t_old.id`. - Before execution, use `DRY RUN QUERY` or `DRY RUN` to preview the rewritten statements and verify that they meet your expectations. ### The actual batch size is not the same as the specified batch size diff --git a/sql-statements/sql-statement-batch.md b/sql-statements/sql-statement-batch.md index af8848d3a4808..ed87e0aa4f0f6 100644 --- a/sql-statements/sql-statement-batch.md +++ b/sql-statements/sql-statement-batch.md @@ -29,7 +29,7 @@ Non-transactional DML, shard column must be fully specified > **Note:** > -> The `BATCH` statement is internally rewritten and split into multiple DML statements during execution. In the current version, table aliases might not be preserved, which can result in errors such as `Unknown column ... in 'where clause'`. To avoid this issue, do not use table aliases. Before execution, use `DRY RUN QUERY` or `DRY RUN` to preview the split statements before execution. For more information, see [Non-Transactional DML Statements](/non-transactional-dml.md). +> The `BATCH` statement is internally rewritten and split into multiple DML statements during execution. In the current version, table aliases might not be preserved, which can result in errors such as `Unknown column '.' in 'where clause'`. To avoid this issue, do not use table aliases. Before execution, use `DRY RUN QUERY` or `DRY RUN` to preview the split statements before execution. For more information, see [Non-Transactional DML Statements](/non-transactional-dml.md). ## Synopsis