跳到主要内容
跳到主要内容

EXPORT

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 相关的文件格式生效)。

    • timeout:导出作业的超时时间,默认为 2 小时,单位是秒。

    注意:要使用 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_stype: (选填) 默认为 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。

  1. 将 test 表中的所有数据导出到本地存储,默认导出 csv 格式文件
EXPORT TABLE test TO "file:///home/user/tmp/";
  1. 将 test 表中的 k1,k2 列导出到本地存储,默认导出 csv 文件格式,并设置 label
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
"label" = "label1",
"columns" = "k1,k2"
);
  1. 将 test 表中的 k1 < 50 的行导出到本地存储,默认导出 csv 格式文件,并以,作为列分割符
EXPORT TABLE test WHERE k1 < 50 TO "file:///home/user/tmp/"
PROPERTIES (
"columns" = "k1,k2",
"column_separator"=","
);
  1. 将 test 表中的分区 p1,p2 导出到本地存储,默认导出 csv 格式文件
EXPORT TABLE test PARTITION (p1,p2) TO "file:///home/user/tmp/" 
PROPERTIES ("columns" = "k1,k2");
  1. 将 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"
);
  1. 设置 max_file_sizes 属性
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
"format" = "parquet",
"max_file_size" = "5MB"
);

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

  1. 设置 parallelism 属性
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
"format" = "parquet",
"max_file_size" = "5MB",
"parallelism" = "5"
);
  1. 设置 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

  1. 将 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

  1. 将 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。

  1. 将 test 表中的所有数据导出到 hdfs 上
EXPORT TABLE test TO "hdfs://hdfs_host:port/a/b/c" 
WITH BROKER "broker_name"
(
"username"="xxx",
"password"="yyy"
);
  1. 将 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"
);
  1. 将 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 作业的线程数量。每一个线程会负责导出表的部分 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 数量,也可以加快导出速度。

内存限制

通常一个 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 来修改该设置。