morningman commented on code in PR #739: URL: https://github.com/apache/doris-website/pull/739#discussion_r1641879862
########## i18n/zh-CN/docusaurus-plugin-content-docs/current/data-operate/export/export-view.md: ########## @@ -0,0 +1,133 @@ +--- +{ + "title": "数据导出概述", Review Comment: 文件名称:export-overview.md ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/data-operate/export/export-view.md: ########## @@ -0,0 +1,133 @@ +--- +{ + "title": "数据导出概述", + "language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# 数据导出概述 +数据导出功能,用于将查询结果集或者Doris的表数据,使用指定的文件格式,写入指定的存储系统中的。 + +导出功能和数据备份功能有以下区别: + +| |数据导出|数据备份| +| ----- | ----- | ----- | +|数据最终存储位置|HDFS、对象存储、本地文件系统|HDFS、对象存储| +|数据格式|Parquet、ORC、CSV 等开放格式|Doris 内部存储格式| +|执行速度|中等(需要读取数据并转换成目标数据格式)|快速(无需解析和转换,直接上传Doris数据文件)| +|灵活度|可以通过 SQL 语句灵活定义要导出的数据|仅支持表级别全量备份| +|使用场景|结果集下载、不同系统之间的数据交换|数据备份、Doris集群间的数据迁移| + +# 选择导出方式 +Doris 提供以下三种不同的数据导出方式: + +* SELECT INTO OUTFILE:支持任意 SQL 结果集的导出。 +* EXPORT:支持表级别的部分或全部数据导出。 +* MySQL DUMP:兼容 mysql dump 指令的数据导出。 + + + +三种导出方式的异同点如下: + +| |SELECT INTO OUTFILE|EXPORT|MySQL DUMP| +| ----- | ----- | ----- | ----- | +|同步/异步|同步|异步(提交EXPORT任务后通过 SHOW EXPORT 命令查看任务进度)|同步| +|支持任意 SQL|支持|不支持|不支持| +|导出指定分区|支持|支持|不支持| +|导出指定tablets|支持|不支持|不支持| +|并发导出|支持且并发高(但取决于 SQL 语句是否有 ORDER BY 等需要单机处理的算子)|支持且并发高(支持 Tablet 粒度的并发导出)|不支持,只能单线程导出| +|支持导出的数据格式|Parquet、ORC、CSV|Parquet、ORC、CSV|MySQL Dump 专有格式| +|是否支持导出外表|支持|部分支持|不支持| +|是否支持导出view|支持|支持|支持| +|支持的导出位置|S3、HDFS、LOCAL|S3、HDFS、LOCAL|LOCAL| + +## SELECT INTO OUTFILE +适用于以下场景: + +* 导出数据需要经过复杂计算逻辑的,如过滤、聚合、关联等。 +* 适合执行同步任务的场景。 + +## EXPORT +适用于以下场景: + +* 大数据量的单表导出、仅需简单的过滤条件。 +* 需要异步提交任务的场景。 + +## MySQl Dump +适用于以下场景: + +* 兼容MySQL 生态,需要同时导出表结构和数据。 +* 仅用于开发测试或者数据量很小的情况。 + + + +# 导出文件列类型映射 +Parquet、ORC 文件格式拥有自己的数据类型。Doris 的导出功能能够自动将 Doris 的数据类型导出为 Parquet、ORC 文件格式的对应数据类型。CSV 格式没有类型,所有数据都以文本形式输出。 + + + +以下是Doris数据类型和 Parquet、ORC 文件格式的数据类型映射关系表: + +1. Doris导出到Orc文件格式的数据类型映射表: + +|Doris Type|Orc Type| Review Comment: 缩进一级,后面的相同处理 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/data-operate/export/export-manual.md: ########## @@ -173,68 +130,330 @@ FinishTime: 2019-06-25 17:08:34 * ErrorMsg:如果作业出现错误,这里会显示错误原因。 * OutfileInfo:如果作业导出成功,这里会显示具体的`SELECT INTO OUTFILE`结果信息。 -### 取消导出任务 -:::info 备注 -`CANCEL EXPORT` 命令自 Doris 1.2.2 版本起支持。 +提交Export作业后,在Export任务成功或失败之前可以通过 [CANCEL EXPORT](../../sql-manual/sql-statements/Data-Manipulation-Statements/Manipulation/CANCEL-EXPORT.md) 命令取消导出作业。取消命令举例如下: -::: +```sql +CANCEL EXPORT FROM tpch1 WHERE LABEL like "%export_%"; +``` +# 导出文件列类型映射 +`Export`支持导出数据为Parquet、ORC 文件格式。Parquet、ORC 文件格式拥有自己的数据类型,Doris 的导出功能能够自动将 Doris 的数据类型导出为 Parquet、ORC 文件格式的对应数据类型,具体映射关系请参阅[导出综述](./export-view.md)文档的 "导出文件列类型映射" 部分。 -提交作业后,可以通过 [CANCEL EXPORT](../../sql-manual/sql-statements/Data-Manipulation-Statements/Manipulation/CANCEL-EXPORT) 命令取消导出作业。取消命令举例如下: +# 示例 +## 导出到 HDFS +将 db1.tbl1 表的p1和p2分区中的`col1` 列和`col2` 列数据导出到 HDFS 上,设置导出作业的 label 为 `mylabel`。导出文件格式为csv(默认格式),列分割符为`,`,导出作业单个文件大小限制为512MB。 ```sql -CANCEL EXPORT -FROM example_db -WHERE LABEL like "%example%"; +EXPORT TABLE db1.tbl1 +PARTITION (p1,p2) +TO "hdfs://host/path/to/export/" +PROPERTIES +( + "label" = "mylabel", + "column_separator"=",", + "max_file_size" = "512MB", + "columns" = "col1,col2" +) +with HDFS ( + "fs.defaultFS"="hdfs://hdfs_host:port", + "hadoop.username" = "hadoop" +); +``` +如果HDFS开启了高可用,则需要提供HA信息,如: + +```sql +EXPORT TABLE db1.tbl1 +PARTITION (p1,p2) +TO "hdfs://HDFS8000871/path/to/export/" +PROPERTIES +( + "label" = "mylabel", + "column_separator"=",", + "max_file_size" = "512MB", + "columns" = "col1,col2" +) +with HDFS ( + "fs.defaultFS" = "hdfs://HDFS8000871", + "hadoop.username" = "hadoop", + "dfs.nameservices" = "your-nameservices", + "dfs.ha.namenodes.your-nameservices" = "nn1,nn2", + "dfs.namenode.rpc-address.HDFS8000871.nn1" = "ip:port", + "dfs.namenode.rpc-address.HDFS8000871.nn2" = "ip:port", + "dfs.client.failover.proxy.provider.HDFS8000871" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider" +); +``` +如果Hadoop 集群开启了高可用并且启用了 Kerberos 认证,可以参考如下SQL语句: + +```sql +EXPORT TABLE db1.tbl1 +PARTITION (p1,p2) +TO "hdfs://HDFS8000871/path/to/export/" +PROPERTIES +( + "label" = "mylabel", + "column_separator"=",", + "max_file_size" = "512MB", + "columns" = "col1,col2" +) +with HDFS ( + "fs.defaultFS"="hdfs://hacluster/", + "hadoop.username" = "hadoop", + "dfs.nameservices"="hacluster", + "dfs.ha.namenodes.hacluster"="n1,n2", + "dfs.namenode.rpc-address.hacluster.n1"="192.168.0.1:8020", + "dfs.namenode.rpc-address.hacluster.n2"="192.168.0.2:8020", + "dfs.client.failover.proxy.provider.hacluster"="org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider", + "dfs.namenode.kerberos.principal"="hadoop/_h...@realm.com" + "hadoop.security.authentication"="kerberos", + "hadoop.kerberos.principal"="doris_t...@realm.com", + "hadoop.kerberos.keytab"="/path/to/doris_test.keytab" +); ``` +## 导出到 S3 +将 s3\_test 表中的所有数据导出到 s3 上,导出格式为csv,以不可见字符 "\\x07" 作为行分隔符。 + +```sql +EXPORT TABLE s3_test TO "s3://bucket/a/b/c" +PROPERTIES ( + "line_delimiter" = "\\x07" +) WITH s3 ( + "s3.endpoint" = "xxxxx", + "s3.region" = "xxxxx", + "s3.secret_key"="xxxx", + "s3.access_key" = "xxxxx" +) +``` +## 导出到本地文件系统 +> export数据导出到本地文件系统,需要在fe.conf中添加`enable_outfile_to_local=true`并且重启FE。 + +将test表中的所有数据导出到本地存储: + +```sql +-- 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" +); +``` +> 注意: + +> 导出到本地文件系统的功能不适用于公有云用户,仅适用于私有化部署的用户。并且默认用户对集群节点有完全的控制权限。Doris 对于用户填写的导出路径不会做合法性检查。如果 Doris 的进程用户对该路径无写权限,或路径不存在,则会报错。同时处于安全性考虑,如果该路径已存在同名的文件,则也会导出失败。 + +> Doris 不会管理导出到本地的文件,也不会检查磁盘空间等。这些文件需要用户自行管理,如清理等。 + +## 指定分区导出 +导出作业支持仅导出 Doris 内表的部分分区,如仅导出 test 表的 p1 和 p2 分区 + +```sql +EXPORT TABLE test +PARTITION (p1,p2) +TO "file:///home/user/tmp/" +PROPERTIES ( + "columns" = "k1,k2" +); +``` +## 导出时过滤数据 +导出作业支持导出时根据谓词条件过滤数据,仅导出符合条件的数据,如仅导出满足 `k1 < 50` 条件的数据 + +```sql +EXPORT TABLE test +WHERE k1 < 50 +TO "file:///home/user/tmp/" +PROPERTIES ( + "columns" = "k1,k2", + "column_separator"="," +); +``` +## 导出外表数据 +导出作业支持Doris Catalog外表数据: + +```sql +-- 创建一个catalog +CREATE CATALOG `tpch` PROPERTIES ( + "type" = "trino-connector", + "trino.connector.name" = "tpch", + "trino.tpch.column-naming" = "STANDARD", + "trino.tpch.splits-per-node" = "32" +); + +-- 导出 Catalog 外表数据 +EXPORT TABLE tpch.sf1.lineitem TO "file:///path/to/exp_" +PROPERTIES( + "parallelism" = "5", + "format" = "csv", + "max_file_size" = "1024MB" +); +``` + +> 注意:当前Export导出 Catalog 外表数据不支持并发导出,即使指定 parallelism 大于 1,仍然是单线程导出。 + +# 最佳实践 +## 导出一致性 +`Export`导出支持 partition / tablets 两种粒度。`data_consistency`参数用来指定以何种粒度切分希望导出的表,`none` 代表 Tablets 级别,`partition`代表 Partition 级别。 + +```sql +EXPORT TABLE test TO "file:///home/user/tmp" +PROPERTIES ( + "format" = "parquet", + "data_consistency" = "partition", + "max_file_size" = "512MB" +); +``` +若设置`"data_consistency" = "partition"` ,Export任务底层构造的多个`SELECT INTO OUTFILE` 语句都会导出不同的partition。 + +若设置`"data_consistency" = "none"` ,Export任务底层构造的多个`SELECT INTO OUTFILE` 语句都会导出不同的tablets,但是这些不同的tablets有可能属于相同的partition。 + +关于Export底层构造 `SELECT INTO OUTFILE` 的逻辑,可参阅附录部分。 + +## 导出作业并发度 +Export可以设置不同的并发度来并发导出数据。指定并发度为5: + +```sql +EXPORT TABLE test TO "file:///home/user/tmp/" +PROPERTIES ( + "format" = "parquet", + "max_file_size" = "512MB", + "parallelism" = "5" +); +``` +关于Export并发导出的原理,可参阅附录部分。 + +## 导出前清空导出目录 +```sql +EXPORT TABLE test TO "file:///home/user/tmp" +PROPERTIES ( + "format" = "parquet", + "max_file_size" = "512MB", + "delete_existing_files" = "true" +); +``` +如果设置了 `"delete_existing_files" = "true"`,导出作业会先将`/home/user/`目录下所有文件及目录删除,然后导出数据到该目录下。 + +> 注意: + +> 若要使用delete\_existing\_files参数,还需要在fe.conf中添加配置`enable_delete_existing_files = true`并重启fe,此时delete\_existing\_files才会生效。delete\_existing\_files = true 是一个危险的操作,建议只在测试环境中使用。 + +## 设置导出文件的大小 +导出作业支持设置导出文件的大小,如果单个文件大小超过设定值,则会按照指定大小分成多个文件导出。 + +```sql +EXPORT TABLE test TO "file:///home/user/tmp/" +PROPERTIES ( + "format" = "parquet", + "max_file_size" = "512MB" +); +``` +通过设置 `"max_file_size" = "``512MB``"`,则单个导出文件的最大大小为 512MB。 + +# 注意事项 +1. 内存限制 + + 通常一个 Export 作业的查询计划只有 `扫描-导出` 两部分,不涉及需要太多内存的计算逻辑。所以通常 2GB 的默认内存限制可以满足需求。 + + 但在某些场景下,比如一个查询计划,在同一个 BE 上需要扫描的 Tablet 过多,或者 Tablet 的数据版本过多时,可能会导致内存不足。可以调整session变量`exec_mem_limit`来调大内存使用限制。 + +2. 导出数据量 + + 不建议一次性导出大量数据。一个 Export 作业建议的导出数据量最大在几十 GB。过大的导出会导致更多的垃圾文件和更高的重试成本。如果表数据量过大,建议按照分区导出。 + + 另外,Export 作业会扫描数据,占用 IO 资源,可能会影响系统的查询延迟。 + +3. 导出文件的管理 + + 如果 Export 作业运行失败,已经生成的文件不会被删除,需要用户手动删除。 + +4. 数据一致性 + + 目前在export时只是简单检查tablets版本是否一致,建议在执行export过程中不要对该表进行导入数据操作。 + +5. 导出超时 + + 若导出的数据量很大,超过导出的超时时间,则Export任务会失败。此时可以在Export命令中指定`timeout` 参数来增加超时时间并重试Export命令。 + +6. 导出失败 + + 在 Export 作业运行过程中,如果 FE 发生重启或切主,则 Export 作业会失败,需要用户重新提交。可以通过`show export` 命令查看Export任务状态。 + +7. 导出分区数量 + + 一个Export Job允许导出的分区数量最大为2000,可以在fe.conf中添加参数`maximum_number_of_export_partitions`并重启FE来修改该设置。 + +8. 并发导出 + + 在并发导出时,请注意合理地配置线程数量和并行度,以充分利用系统资源并避免性能瓶颈。在导出过程中,可以实时监控进度和性能指标,以便及时发现问题并进行优化调整。 + +9. 数据完整性 + + 导出操作完成后,建议验证导出的数据是否完整和正确,以确保数据的质量和完整性。 + + + +# 附录 +### 并发导出原理 Review Comment: 先移除这段,加个TODO,这个逻辑还要修改下 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: dev-unsubscr...@doris.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@doris.apache.org For additional commands, e-mail: dev-h...@doris.apache.org