nontransactional dml FAQ about alias (#22523) (#22536)

Author: ti-chi-bot

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 '<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.
+
+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.

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).
+
 ## Synopsis
 
 ```ebnf+diagram