EXPORT

Name

EXPORT

Description

EXPORT 命令用于将指定表的数据导出为文件到指定位置。目前支持通过 Broker 进程，S3 协议或 HDFS 协议，导出到远端存储，如 HDFS，S3，BOS，COS（腾讯云）上。

EXPORT是一个异步操作，该命令会提交一个EXPORT JOB到 Doris，任务提交成功立即返回。执行后可使用 SHOW EXPORT 命令查看进度。

语法：

EXPORT TABLE table_name
[PARTITION (p1[,p2])]
[WHERE]
TO export_path
[opt_properties]
WITH BROKER/S3/HDFS
[broker_properties];

说明：

table_name

当前要导出的表的表名。支持 Doris 本地表、视图 View、Catalog 外表数据的导出。
partition

可以只导出指定表的某些指定分区，只对 Doris 本地表有效。
export_path

导出的文件路径。可以是目录，也可以是文件目录加文件前缀，如hdfs://path/to/my_file_
opt_properties

用于指定一些导出参数。
```
[PROPERTIES ("key"="value", ...)]
```
可以指定如下参数：
- label: 可选参数，指定此次 Export 任务的 Label，当不指定时系统会随机生成一个 Label。
- column_separator：指定导出的列分隔符，默认为 \t，支持多字节。该参数只用于 CSV 文件格式。
- line_delimiter：指定导出的行分隔符，默认为 \n，支持多字节。该参数只用于 CSV 文件格式。
- columns：指定导出表的某些列。
- format：指定导出作业的文件格式，支持：parquet, orc, csv, csv_with_names、csv_with_names_and_types。默认为 CSV 格式。
- max_file_size：导出作业单个文件大小限制，如果结果超过这个值，将切割成多个文件。max_file_size取值范围是[5MB, 2GB], 默认为 1GB。（当指定导出为 orc 文件格式时，实际切分文件的大小将是 64MB 的倍数，如：指定 max_file_size = 5MB, 实际将以 64MB 为切分；指定 max_file_size = 65MB, 实际将以 128MB 为切分）
- parallelism：导出作业的并发度，默认为1，导出作业会开启parallelism个数的线程去执行select into outfile语句。（如果 Parallelism 个数大于表的 Tablets 个数，系统将自动把 Parallelism 设置为 Tablets 个数大小，即每一个select into outfile语句负责一个 Tablets）
- delete_existing_files: 默认为 false，若指定为 true，则会先删除export_path所指定目录下的所有文件，然后导出数据到该目录下。例如："export_path" = "/user/tmp", 则会删除"/user/"下所有文件及目录；"file_path" = "/user/tmp/", 则会删除"/user/tmp/"下所有文件及目录。
- with_bom: 默认为 false，若指定为 true，则导出的文件编码为带有 BOM 的 UTF8 编码（只对 csv 相关的文件格式生效）。
- data_consistency: 可以设置为 none / partition ，默认为 partition 。指示以何种粒度切分导出表，none 代表 Tablets 级别，partition代表 Partition 级别。
- timeout：导出作业的超时时间，默认为 2 小时，单位是秒。
- compress_type：(自 2.1.5 支持) 当指定导出的文件格式为 Parquet / ORC 文件时，可以指定 Parquet / ORC 文件使用的压缩方式。Parquet 文件格式可指定压缩方式为 SNAPPY，GZIP，BROTLI，ZSTD，LZ4 及 PLAIN，默认值为 SNAPPY。ORC 文件格式可指定压缩方式为 PLAIN，SNAPPY，ZLIB 以及 ZSTD，默认值为 ZLIB。该参数自 2.1.5 版本开始支持。（PLAIN 就是不采用压缩）
:::caution 注意要使用 delete_existing_files 参数，还需要在 fe.conf 中添加配置enable_delete_existing_files = true并重启 fe，此时 delete_existing_files 才会生效。delete_existing_files = true 是一个危险的操作，建议只在测试环境中使用。 :::

WITH BROKER

可以通过 Broker 进程写数据到远端存储上。这里需要定义相关的连接信息供 Broker 使用。

语法：
WITH BROKER "broker_name"
("key"="value"[,...])
 
Broker 相关属性：
  username: 用户名
  password: 密码
  hadoop.security.authentication: 指定认证方式为 kerberos
  kerberos_principal: 指定 kerberos 的 principal
  kerberos_keytab: 指定 kerberos 的 keytab 文件路径。该文件必须为 Broker 进程所在服务器上的文件的绝对路径。并且可以被 Broker 进程访问

WITH HDFS

可以直接将数据写到远端 HDFS 上。

语法：
WITH HDFS ("key"="value"[,...])
 
HDFS 相关属性：
  fs.defaultFS: namenode 地址和端口
  hadoop.username: hdfs 用户名
  dfs.nameservices: name service 名称，与 hdfs-site.xml 保持一致
  dfs.ha.namenodes.[nameservice ID]: namenode 的 id 列表，与 hdfs-site.xml 保持一致
  dfs.namenode.rpc-address.[nameservice ID].[name node ID]: Name node 的 rpc 地址，数量与 namenode 数量相同，与 hdfs-site.xml 保
 
  对于开启kerberos认证的Hadoop 集群，还需要额外设置如下 PROPERTIES 属性:
  dfs.namenode.kerberos.principal: HDFS namenode 服务的 principal 名称
  hadoop.security.authentication: 认证方式设置为 kerberos
  hadoop.kerberos.principal: 设置 Doris 连接 HDFS 时使用的 Kerberos 主体
  hadoop.kerberos.keytab: 设置 keytab 本地文件路径

WITH S3

可以直接将数据写到远端 S3 对象存储上。

语法：
WITH S3 ("key"="value"[,...])
 
S3 相关属性：
  AWS_ENDPOINT
  AWS_ACCESS_KEY
  AWS_SECRET_KEY
  AWS_REGION
  use_path_style: (选填) 默认为 `false`。S3 SDK 默认使用 Virtual-hosted Style 方式。但某些对象存储系统可能没开启或不支持 Virtual-hosted Style 方式的访问，此时可以添加 `use_path_style` 参数来强制使用 Path Style 访问方式。

Example

Export 数据到本地

Export 数据到本地文件系统，需要在 fe.conf 中添加 enable_outfile_to_local=true 并且重启 FE。

将 Test 表中的所有数据导出到本地存储，默认导出 CSV 格式文件

EXPORT TABLE test TO "file:///home/user/tmp/";

将 Test 表中的 k1,k2 列导出到本地存储，默认导出 CSV 文件格式，并设置 Label

EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "label" = "label1",
  "columns" = "k1,k2"
);

将 Test 表中的 k1 < 50 的行导出到本地存储，默认导出 CSV 格式文件，并以 , 作为列分割符

EXPORT TABLE test WHERE k1 < 50 TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "column_separator"=","
);

将 Test 表中的分区 p1,p2 导出到本地存储，默认导出 csv 格式文件

EXPORT TABLE test PARTITION (p1,p2) TO "file:///home/user/tmp/" 
PROPERTIES ("columns" = "k1,k2");

将 Test 表中的所有数据导出到本地存储，导出其他格式的文件

// parquet格式
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "format" = "parquet"
);
 
// orc格式
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "format" = "orc"
);
 
// csv_with_names格式, 以’AA‘为列分割符，‘zz’为行分割符
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "csv_with_names",
  "column_separator"="AA",
  "line_delimiter" = "zz"
);
 
// csv_with_names_and_types格式
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "csv_with_names_and_types"
);

设置 max_file_sizes 属性

EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB"
);

当导出文件大于 5MB 时，将切割数据为多个文件，每个文件最大为 5MB。

设置 parallelism 属性

EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB",
  "parallelism" = "5"
);

设置 delete_existing_files 属性

EXPORT TABLE test TO "file:///home/user/tmp"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB",
  "delete_existing_files" = "true"
);

Export 导出数据时会先将/home/user/目录下所有文件及目录删除，然后导出数据到该目录下。

export with S3

将 s3_test 表中的所有数据导出到 S3 上，以不可见字符 \x07 作为列或者行分隔符。如果需要将数据导出到 minio，还需要指定 use_path_style=true。

EXPORT TABLE s3_test TO "s3://bucket/a/b/c" 
PROPERTIES (
  "column_separator"="\\x07", 
  "line_delimiter" = "\\x07"
) WITH s3 (
  "s3.endpoint" = "xxxxx",
  "s3.region" = "xxxxx",
  "s3.secret_key"="xxxx",
  "s3.access_key" = "xxxxx"
)

export with HDFS

将 Test 表中的所有数据导出到 HDFS 上，导出文件格式为 Parquet，导出作业单个文件大小限制为 512MB，保留所指定目录下的所有文件。

EXPORT TABLE test TO "hdfs://hdfs_host:port/a/b/c/" 
PROPERTIES(
    "format" = "parquet",
    "max_file_size" = "512MB",
    "delete_existing_files" = "false"
)
with HDFS (
"fs.defaultFS"="hdfs://hdfs_host:port",
"hadoop.username" = "hadoop"
);

export with Broker

需要先启动 Broker 进程，并在 FE 中添加该 Broker。

将 Test 表中的所有数据导出到 hdfs 上

EXPORT TABLE test TO "hdfs://hdfs_host:port/a/b/c" 
WITH BROKER "broker_name" 
(
  "username"="xxx",
  "password"="yyy"
);

将 testTbl 表中的分区 p1,p2 导出到 hdfs 上，以","作为列分隔符，并指定 Label

EXPORT TABLE testTbl PARTITION (p1,p2) TO "hdfs://hdfs_host:port/a/b/c" 
PROPERTIES (
  "label" = "mylabel",
  "column_separator"=","
) 
WITH BROKER "broker_name" 
(
  "username"="xxx",
  "password"="yyy"
);

将 testTbl 表中的所有数据导出到 hdfs 上，以不可见字符 \x07 作为列或者行分隔符。

EXPORT TABLE testTbl TO "hdfs://hdfs_host:port/a/b/c" 
PROPERTIES (
  "column_separator"="\\x07", 
  "line_delimiter" = "\\x07"
) 
WITH BROKER "broker_name" 
(
  "username"="xxx", 
  "password"="yyy"
)

Keywords

EXPORT

Best Practice

并发执行

一个 Export 作业可以设置parallelism参数来并发导出数据。parallelism参数实际就是指定执行 EXPORT 作业的线程数量。当设置"data_consistency" = "none"时，每一个线程会负责导出表的部分 Tablets。

一个 Export 作业的底层执行逻辑实际上是SELECT INTO OUTFILE语句，parallelism参数设置的每一个线程都会去执行独立的SELECT INTO OUTFILE语句。

Export 作业拆分成多个SELECT INTO OUTFILE的具体逻辑是：将该表的所有 tablets 平均的分给所有 parallel 线程，如：

num(tablets) = 40, parallelism = 3，则这 3 个线程各自负责的 tablets 数量分别为 14，13，13 个。
num(tablets) = 2, parallelism = 3，则 Doris 会自动将 parallelism 设置为 2，每一个线程负责一个 tablets。

当一个线程负责的 tablest 超过 maximum_tablets_of_outfile_in_export 数值（默认为 10，可在 fe.conf 中添加maximum_tablets_of_outfile_in_export参数来修改该值）时，该线程就会拆分为多个SELECT INTO OUTFILE语句，如：

一个线程负责的 tablets 数量分别为 14，maximum_tablets_of_outfile_in_export = 10，则该线程负责两个SELECT INTO OUTFILE语句，第一个SELECT INTO OUTFILE语句导出 10 个 tablets，第二个SELECT INTO OUTFILE语句导出 4 个 tablets，两个SELECT INTO OUTFILE语句由该线程串行执行。

当所要导出的数据量很大时，可以考虑适当调大parallelism参数来增加并发导出。若机器核数紧张，无法再增加parallelism 而导出表的 Tablets 又较多时，可以考虑调大maximum_tablets_of_outfile_in_export来增加一个SELECT INTO OUTFILE语句负责的 tablets 数量，也可以加快导出速度。

若希望以 Parition 粒度导出 Table，可以设置 Export 属性 "data_consistency" = "partition" ，此时 Export 任务并发的线程会以 Parition 粒度来划分为多个 Outfile 语句，不同的 Outfile 语句导出的 Parition 不同，而同一个 Outfile 语句导出的数据一定属于同一个 Partition。如：设置 "data_consistency" = "partition" 后

num(partition) = 40, parallelism = 3，则这 3 个线程各自负责的 Partition 数量分别为 14，13，13 个。
num(partition) = 2, parallelism = 3，则 Doris 会自动将 Parallelism 设置为 2，每一个线程负责一个 Partition。

内存限制

通常一个 Export 作业的查询计划只有 扫描-导出 两部分，不涉及需要太多内存的计算逻辑。所以通常 2GB 的默认内存限制可以满足需求。

但在某些场景下，比如一个查询计划，在同一个 BE 上需要扫描的 Tablet 过多，或者 Tablet 的数据版本过多时，可能会导致内存不足。可以调整 Session 变量 exec_mem_limit 来调大内存使用限制。

注意事项

不建议一次性导出大量数据。一个 Export 作业建议的导出数据量最大在几十 GB。过大的导出会导致更多的垃圾文件和更高的重试成本。如果表数据量过大，建议按照分区导出。
如果 Export 作业运行失败，已经生成的文件不会被删除，需要用户手动删除。
Export 作业会扫描数据，占用 IO 资源，可能会影响系统的查询延迟。
目前在 Export 时只是简单检查 Tablets 版本是否一致，建议在执行 Export 过程中不要对该表进行导入数据操作。
一个 Export Job 允许导出的分区数量最大为 2000，可以在 fe.conf 中添加参数 maximum_number_of_export_partitions 并重启 FE 来修改该设置。

DELETE INSERT