跳到主要内容
版本：Latest-3.3

INSERT

功能​

向 StarRocks 表中插入或覆盖写入数据。关于该种导入数据方式适用的场景请参考 INSERT INTO 导入。

您可以通过 SUBMIT TASK 创建异步 INSERT 任务。

语法​

  • 导入:

    INSERT { INTO | OVERWRITE } [db_name.]<table_name>
    [ PARTITION (<partition_name> [, ...] ) ]
    [ TEMPORARY PARTITION (<temporary_partition_name> [, ...] ) ]
    [ WITH LABEL <label>]
    [ (<column_name>[, ...]) ]
    { VALUES ( { <expression> | DEFAULT } [, ...] ) | <query> }

  • 导出:

    INSERT INTO FILES()
    [ WITH LABEL <label> ]
    { VALUES ( { <expression> | DEFAULT } [, ...] ) | <query> }

参数说明​

参数说明
INTO将数据追加写入目标表。
OVERWRITE将数据覆盖写入目标表。
table_name导入数据的目标表。可以为 db_name.table_name 形式。
PARTITION导入的目标分区。此参数必须是目标表中存在的分区，多个分区名称用逗号（,）分隔。如果指定该参数，数据只会被导入相应分区内。如果未指定，则默认将数据导入至目标表的所有分区。
TEMPORARY PARTITION指定要把数据导入哪些临时分区。
label导入作业的标识，数据库内唯一。如果未指定，StarRocks 会自动为作业生成一个 Label。建议您指定 Label。否则，如果当前导入作业因网络错误无法返回结果，您将无法得知该导入操作是否成功。如果指定了 Label，可以通过 SQL 命令 SHOW LOAD WHERE label="label"; 查看任务结果。关于 Label 命名要求，参见系统限制。
column_name导入的目标列，必须是目标表中存在的列。该参数的对应关系与列名无关，但与其顺序一一对应。如果不指定目标列，默认为目标表中的所有列。如果源表中的某个列在目标列不存在，则写入默认值。如果当前列没有默认值，导入作业会失败。如果查询语句的结果列类型与目标列的类型不一致，会进行隐式转化，如果不能进行转化，那么 INSERT INTO 语句会报语法解析错误。
说明
自 v3.3.1 起，INSERT INTO 导入主键表时指定 Column List 会执行部分列更新（而在先前版本中，指定 Column List 仍然导致 Full Upsert）。如不指定 Column List，系统执行 Full Upsert。
expression表达式，用以为对应列赋值。
DEFAULT为对应列赋予默认值。
query查询语句，查询的结果会导入至目标表中。查询语句支持任意 StarRocks 支持的 SQL 查询语法。
FILES()表函数 FILES()。您可以通过该函数将数据导出至远端存储。更多信息，请参考 使用 INSERT INTO FILES() 导出数据.

注意事项​

  • 当前版本中，StarRocks 在执行 INSERT 语句时，如果有数据不符合目标表格式的数据（例如字符串超长等情况），INSERT 操作默认执行失败。您可以通过设置会话变量 enable_insert_strict 为 false 以确保 INSERT 操作过滤不符合目标表格式的数据，并继续执行。

  • 执行 INSERT OVERWRITE 语句后，系统将为目标分区创建相应的临时分区，并将数据写入临时分区，最后使用临时分区原子替换目标分区来实现覆盖写入。其所有过程均在在 Leader FE 节点执行。因此，如果 Leader FE 节点在覆盖写入过程中发生宕机，将会导致该次 INSERT OVERWRITE 导入失败，其过程中所创建的临时分区也会被删除。

示例​

以下示例基于表 test，其中包含两个列 c1 和 c2。c2 列有默认值 DEFAULT。

示例一：向 test 表中导入一行数据​

INSERT INTO test VALUES (1, 2);
INSERT INTO test (c1, c2) VALUES (1, 2);
INSERT INTO test (c1, c2) VALUES (1, DEFAULT);
INSERT INTO test (c1) VALUES (1);
  • 在不指定目标列时，使用表中的列顺序来作为默认的目标列导入顺序。因此以上示例中，第一条、第二条 SQL 语句导入效果相同。
  • 如果有目标列未插入数据或使用 DEFAULT 作为值插入数据，该列将使用默认值作为导入数据。因此以上示例中，第三条、第四条语句导入效果相同。

示例二：向 test 表中一次性导入多行数据​

INSERT INTO test VALUES (1, 2), (3, 2 + 2);
INSERT INTO test (c1, c2) VALUES (1, 2), (3, 2 * 2);
INSERT INTO test (c1) VALUES (1), (3);
INSERT INTO test (c1, c2) VALUES (1, DEFAULT), (3, DEFAULT);
  • 因表达式结果相同，以上示例中，第一条、第二条 SQL 语句导入效果相同。
  • 第三条、第四条语句使用 DEFAULT 作为值插入数据，因此导入效果相同。

示例三：向 test 表中导入一个查询语句结果​

INSERT INTO test SELECT * FROM test2;
INSERT INTO test (c1, c2) SELECT * from test2;

示例四：向 test 表中导入一个查询语句结果，并指定分区和 Label​

INSERT INTO test PARTITION(p1, p2) WITH LABEL `label1` SELECT * FROM test2;
INSERT INTO test WITH LABEL `label1` (c1, c2) SELECT * from test2;

示例五：向 test 表中覆盖写入一个查询语句结果，并指定分区和 Label​

INSERT OVERWRITE test PARTITION(p1, p2) WITH LABEL `label1` SELECT * FROM test3;
INSERT OVERWRITE test WITH LABEL `label1` (c1, c2) SELECT * from test3;

示例六：从 AWS S3 中导入 Parquet 数据文件​

以下示例将 AWS S3 存储桶 inserttest 内 Parquet 文件 parquet/insert_wiki_edit_append.parquet 中的数据插入至表 insert_wiki_edit 中：

INSERT INTO insert_wiki_edit
    SELECT * FROM TABLE(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "xxxxxxxxxx",
        "aws.s3.secret_key" = "yyyyyyyyyy",
        "aws.s3.region" = "aa-bbbb-c"
);