Doris专题17- 数据导入-文件格式

1. 概述

Apache Doris 支持多种文件格式的数据导入，每种格式都有其特定的使用场景和配置参数。本笔记详细记录了 ORC、Parquet、JSON 和 CSV 格式的导入方法和最佳实践。

2. 格式对比总览

格式	支持导入方式	主要特点	适用场景
ORC	Stream Load, Broker Load, S3/HDFS TVF	列式存储，高压缩比	大数据分析，Hive生态
Parquet	Stream Load, Broker Load, S3/HDFS TVF	列式存储，生态兼容性好	数据湖，跨系统数据交换
JSON	Stream Load, Broker Load, Routine Load, S3/HDFS TVF	灵活结构，支持嵌套数据	半结构化数据，API接口数据
CSV	所有导入方式	通用格式，配置灵活	表格数据，Excel导出数据

3. ORC 格式导入

3.1 支持导入方式

Stream Load
Broker Load
INSERT INTO FROM S3 TVF
INSERT INTO FROM HDFS TVF

3.2 使用示例

bash 复制代码

# Stream Load 导入
curl --location-trusted -u <user>:<passwd>
  -H "format: orc"
  -T example.orc
  http://<fe_host>:<fe_http_port>/api/example_db/example_table/_stream_load

sql 复制代码

-- Broker Load 导入
LOAD LABEL example_db.example_label
(
    DATA INFILE("s3://bucket/example.orc")
    INTO TABLE example_table
    FORMAT AS "orc"
)
WITH S3
(
    ...
);

-- TVF 导入
INSERT INTO example_table
SELECT *
FROM S3
(
    "uri" = "s3://bucket/example.orc",
    "format" = "orc",
    ...
);

4. Parquet 格式导入

4.1 支持导入方式

Stream Load
Broker Load
INSERT INTO FROM S3 TVF
INSERT INTO FROM HDFS TVF

4.2 使用示例

bash 复制代码

# Stream Load 导入
curl --location-trusted -u <user>:<passwd>
  -H "format: parquet"
  -T example.parquet
  http://<fe_host>:<fe_http_port>/api/example_db/example_table/_stream_load

sql 复制代码

-- Broker Load 导入
LOAD LABEL example_db.example_label
(
    DATA INFILE("s3://bucket/example.parquet")
    INTO TABLE example_table
    FORMAT AS "parquet"
)
WITH S3
(
    ...
);

-- TVF 导入
INSERT INTO example_table
SELECT *
FROM S3
(
    "uri" = "s3://bucket/example.parquet",
    "format" = "parquet",
    ...
);

5. JSON 格式导入

5.1 支持导入方式

Stream Load
Broker Load
Routine Load
INSERT INTO FROM S3 TVF
INSERT INTO FROM HDFS TVF

5.2 JSON 格式类型

5.2.1 Array 格式（多行数据）

json 复制代码

[
    {"id": 123, "city": "beijing"},
    {"id": 456, "city": "shanghai"}
]

要求：必须设置 strip_outer_array=true

5.2.2 Object 格式（单行数据）

json 复制代码

{"id": 123, "city": "beijing"}

5.2.3 多行 Object 格式

json 复制代码

{"id": 123, "city": "beijing"}
{"id": 456, "city": "shanghai"}

要求：必须设置 read_json_by_line=true

5.3 JSON 参数配置

参数	默认值	说明	使用场景
jsonpaths	无	JSON字段抽取路径	字段映射，嵌套字段提取
json_root	无	JSON解析根节点	处理嵌套数据结构
strip_outer_array	false	去除外层数组	Array格式JSON
read_json_by_line	false	按行读取JSON	多行Object格式
fuzzy_parse	false	快速解析模式	性能优化，要求字段顺序一致
num_as_string	false	数值作为字符串处理	大数或精度要求高的场景

5.4 JSON Path 使用示例

bash 复制代码

# Stream Load 使用 JSON Path
curl --location-trusted -u <user>:<passwd>
  -H "format: json"
  -H "jsonpaths: ["\$.id", "\$.city"]"
  -T example.json
  http://<fe_host>:<fe_http_port>/api/example_db/example_table/_stream_load

# 指定 JSON root
curl --location-trusted -u <user>:<passwd> 
  -H "format: json" 
  -H "json_root: $.events" 
  -T example.json 
  http://<fe_host>:<fe_http_port>/api/example_db/example_table/_stream_load

# 按行读取 JSON
curl --location-trusted -u <user>:<passwd>
  -H "format: json"
  -H "read_json_by_line: true"
  -T example.json
  http://<fe_host>:<fe_http_port>/api/example_db/example_table/_stream_load

sql 复制代码

-- Broker Load 使用 JSON Path
LOAD LABEL example_db.example_label
(
    DATA INFILE("s3://bucket/path/example.json")
    INTO TABLE example_table
    FORMAT AS "json"
    PROPERTIES
    (
        "jsonpaths" = "["\$.id", "\$.city"]"
    )
)
WITH S3
(
    ...
);

-- Routine Load 使用 JSON Path
CREATE ROUTINE LOAD example_db.example_job ON example_table
PROPERTIES
(
    "format" = "json",
    "jsonpaths" = "["\$.id", "\$.city"]"
)
FROM KAFKA
(
    ...
);

6. CSV 格式导入

6.1 支持导入方式

所有导入方式：Stream Load, Broker Load, Routine Load, MySQL Load, S3/HDFS TVF

6.2 CSV 参数配置

参数	默认值	说明	导入方式支持
行分隔符	\n	换行符	Stream, Broker, TVF
列分隔符	\t	列分隔符	所有方式
包围符	无	字段保护符	Stream, Broker, Routine
转义符	\	转义字符	Stream, Broker, Routine
跳过行数	0	跳过文件前几行	Stream, Broker
裁剪双引号	false	去除外层双引号	Stream, Routine
压缩格式	plain	文件压缩格式	Stream, Broker, TVF

6.3 CSV 参数使用场景

6.3.1 行分隔符配置

bash 复制代码

# Linux/Unix 文件
line_delimiter: \\n

# Windows 文件  
line_delimiter: \\r\\n

# 特殊分隔符
line_delimiter: ||

6.3.2 列分隔符配置

bash 复制代码

# 逗号分隔
column_separator: ,

# 制表符（默认）
column_separator: \\t

# Hive 文件（十六进制）
column_separator: \\x01

# 多字符分隔符
column_separator: ||

6.3.3 包围符和转义符

复制代码

数据：a, 'b,c', d
列分隔符：,
包围符：'
解析结果：[a] [b,c] [d]

数据：a, 'b,\\'c', d  
列分隔符：,
包围符：'
转义符：\\
解析结果：[a] [b,'c] [d]

6.4 CSV 导入示例

bash 复制代码

# Stream Load - 指定分隔符
curl --location-trusted -u root: \\
  -H "column_separator: ," \\
  -H "line_delimiter: \\n" \\
  -T example.csv \\
  http://<fe_host>:<fe_http_port>/api/test_db/test_table/_stream_load

# Stream Load - 处理带引号数据
curl --location-trusted -u root: \\
  -H "column_separator: ," \\
  -H "enclose: \\"" \\
  -H "escape: \" \\
  -T example.csv \\
  http://<fe_host>:<fe_http_port>/api/test_db/test_table/_stream_load

# Stream Load - 导入压缩文件
curl --location-trusted -u root: \\
  -H "compress_type: gz" \\
  -T example.csv.gz \\
  http://<fe_host>:<fe_http_port>/api/test_db/test_table/_stream_load

sql 复制代码

-- Broker Load - 指定分隔符
LOAD LABEL test_db.test_label
(
    DATA INFILE("s3://bucket/example.csv")
    INTO TABLE test_table
    COLUMNS TERMINATED BY ";"
    LINES TERMINATED BY "\\n"
)
WITH S3
(
    ...
);

-- MySQL Load - 跳过表头
LOAD DATA LOCAL INFILE 'example.csv'
INTO TABLE test_table
COLUMNS TERMINATED BY ','
LINES TERMINATED BY '\\n'
IGNORE 1 LINES;

-- TVF 导入
INSERT INTO test_table
SELECT *
FROM S3
(
    "uri" = "s3://bucket/example.csv",
    "format" = "csv",
    "column_separator" = ",",
    "line_delimiter" = "\\n"
    ...
);

7. 压缩格式支持

7.1 支持的压缩格式

plain: 不压缩（默认）
gz: GZIP 压缩
bz2: BZIP2 压缩
deflate: DEFLATE 压缩
lz4: LZ4 Frame 格式
lz4_block: LZ4 Block 格式
lzo: LZO 压缩
lzop: LZOP 压缩
snappy_block: SNAPPY Block 格式

7.2 注意事项

不支持 tar 格式：tar 是打包格式，不是压缩格式
压缩文件处理：需要先解包再导入 tar 文件

8. 最佳实践总结

8.1 格式选择建议

结构化数据：优先选择 ORC 或 Parquet，性能最佳
半结构化数据：使用 JSON，支持灵活的数据结构
通用表格数据：使用 CSV，兼容性最好
大数据量：ORC/Parquet + 压缩，节省存储和带宽

8.2 性能优化技巧

JSON 使用 fuzzy_parse=true 提升 3-5 倍性能（要求字段顺序一致）
大文件使用压缩格式减少网络传输
合理设置 max_filter_ratio 控制错误容忍率
使用合适的内存限制 exec_mem_limit

8.3 错误处理

使用 SHOW LOAD WARNINGS 查看详细错误信息
设置合适的 timeout 避免长时间等待
CSV 注意空值（\N）和空字符串的区别