pingcap · ti-chi-bot · Mar 6, 2026 · Mar 4, 2026 · Mar 4, 2026 · gemini-code-assist
diff --git a/non-transactional-dml.md b/non-transactional-dml.md
@@ -366,6 +366,27 @@ SELECT t2.id, t2.v, t3. FROM t2 JOIN t3 ON t2.id=t3.id
 +----------------+---------------+
 ```
 
+### The `Unknown column '<alias>.<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 `<alias>.<column>` format to reference columns in a `WHERE` clause or other expressions, an `Unknown column` error might occur.
-In the current version, the rewritten statements might not preserve the table aliases from the original DML statement. Therefore, if you use the `<alias>.<column>` format to reference columns in a `WHERE` clause or other expressions, an `Unknown column` error might occur.
+Because the rewritten statements might not preserve the table aliases from the original DML statement, you might get an `Unknown column` error if you use the `<alias>.<column>` format to reference columns in a `WHERE` clause or other expressions.
-In the current version, the rewritten statements might not preserve the table aliases from the original DML statement. Therefore, if you use the `<alias>.<column>` format to reference columns in a `WHERE` clause or other expressions, an `Unknown column` error might occur.
+Because the rewritten statements might not preserve the table aliases from the original DML statement, you might get an `Unknown column` error if you use the `<alias>.<column>` format to reference columns in a `WHERE` clause or other expressions.
+
+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](#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
 
 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
@@ -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 '<alias>.<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 '<alias>.<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. These rewritten statements might not preserve table aliases, which can result in errors such as `Unknown column '<alias>.<column>' in 'where clause'`. To avoid this issue, do not use table aliases. You can 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 '<alias>.<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. These rewritten statements might not preserve table aliases, which can result in errors such as `Unknown column '<alias>.<column>' in 'where clause'`. To avoid this issue, do not use table aliases. You can 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