INSERT 语句用于向 TCHouse-X 内表中插入、追加或覆盖数据。
注意：当前 TCHouse-X 在线引擎暂不支持外表写入。
一、语法
[WITH with_clause]INSERT { INTO | OVERWRITE } table_name [(column_list)] [ PARTITION (partition_clause)]{ select_statement | VALUES (value [, value …]) [, (value [, value …]) …]}partition_clause ::= col_name [= constant] [, col_name [= constant] …]
二、子句说明
| 子句 | 作用 | 说明 |
| INTO | 追加 | 保留表中现有数据，新数据追加写入 |
| OVERWRITE | 覆盖 | 替换表中现有数据，旧数据文件立即物理删除 |
| column_list | 目标列子集 | 指定插入列及顺序；未提及的列自动填充 NULL |
| PARTITION | 分区指定 | 指定目标分区；仅分区表可用，内表不支持 |
三、使用限制与注意事项
| 维度 | 说明 |
| 数据可见性 | INSERT 写入的数据不会立即可见，存在约 10 秒延迟。若需即时可见，请执行 ALTER TABLE table_name EXECUTE SYNC_DATA();强制同步 |
| 主键去重 | 若插入的主键值已存在，新数据覆盖旧数据（UPSERT 语义） |
| 数据类型不自动窄化 | 系统不会将大类型自动转换为小类型。例如将 DOUBLE 结果写入 FLOAT 列时，必须手动 CAST(): INSERT INTO t1 SELECT CAST(double_val AS FLOAT) … |
| VALUES 禁用于 ETL | INSERT … VALUES 每次操作生成独立小文件且无法并行，严禁用于大规模数据导入。仅适用于小型维度表维护或语法验证 |
| ORDER BY 被忽略 | INSERT … SELECT 中的 ORDER BY 会被优化器忽略，因为并行写入无法保证全局有序性 |
| 并发写入 | INSERT … SELECT 加表锁，不支持并发写入；INSERT … VALUES 不加锁 |
四、1. INSERT INTO — 基础追加
— 创建测试表CREATE TABLE t1 (id INT, name STRING, score FLOAT);– 单行插入INSERT INTO t1 VALUES (1, 'Alice', 95.5);– 多行插入INSERT INTO t1 VALUES (2, 'Bob', 88.0), (3, 'Carol', 92.3);
五、2. INSERT INTO + column_list — 指定列插入
— 仅插入部分列，未指定列填充 NULLINSERT INTO t1 (id, name) VALUES (4, 'Dave');– 预期结果 (4, 'Dave', NULL), 若查询为空,执行 ALTER TABLE t1 EXECUTE SYNC_DATA(); 强制同步后重试SELECT * FROM t1 WHERE id = 4;
六、3. INSERT INTO SELECT — 从查询结果插入
— 从源表筛选后插入目标表CREATE TABLE t2 LIKE t1;INSERT INTO t2SELECT id, name, score FROM t1 WHERE score > 90;– 带 WITH 子句的插入CREATE TABLE t3 LIKE t1;WITH high_scores AS ( SELECT id, name, score FROM t1 WHERE score > 95)INSERT INTO t3SELECT * FROM high_scores;
七、4. 主键表 INSERT — UPSERT 覆盖
— 创建主键表CREATE TABLE pk_table (id INT, val STRING, PRIMARY KEY (id));– 首次插入INSERT INTO pk_table VALUES (1, 'old');– 相同主键再次插入 → 新值覆盖旧值INSERT INTO pk_table VALUES (1, 'new');– 同步数据使其可见ALTER TABLE pk_table EXECUTE SYNC_DATA();– 结果：id=1 的值为 'new'SELECT * FROM pk_table;
八、5. INSERT INTO SELECT + CAST — 类型转换
— DOUBLE 函数结果必须显式转换为 FLOATCREATE TABLE cast_test_t1 (id INT, val FLOAT);CREATE TABLE cast_test_t2 (id INT, val DOUBLE);INSERT INTO cast_test_t1SELECT id, CAST(val AS FLOAT) valFROM cast_test_t2;
九、6. INSERT INTO SELECT + 去重 — 主键表安全写入
— 危险：SELECT 结果可能含重复主键，最终值不确定INSERT INTO pk_tableSELECT id, val FROM source_table;– 安全：显式去重后再写入INSERT INTO pk_tableSELECT id, MAX(val) AS valFROM source_tableGROUP BY id;
十、实践速查
| 场景 | 推荐方式 |
| 小量数据调试 | INSERT INTO … VALUES |
| 批量 ETL 导入 | INSERT INTO … SELECT |
| 主键表写入 | INSERT INTO … SELECT + GROUP BY 去重 |
| 写入后查询 | ALTER TABLE … EXECUTE SYNC_DATA() |
| 类型不匹配 | 手动 CAST() |