1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521

-- 导出表到 CSV
COPY table_name TO 'filename.csv';

-- 导出查询结果到 Parquet
COPY (SELECT * FROM table WHERE amount > 1000) TO 'filtered.parquet' (FORMAT parquet);

-- 导出到 JSON（换行分隔）
COPY table_name TO 'data.json' (FORMAT json);

-- 导出到 JSON 数组
COPY table_name TO 'data.json' (FORMAT json, ARRAY true);
```text

核心就一句话：`COPY ... TO 'filename' (FORMAT xxx, 选项...)`。

---

## CSV 导出：最通用的选择

CSV 是最老牌的交换格式，几乎所有系统都支持。DuckDB 的 CSV 导出选项很丰富：

```python
import duckdb

conn = duckdb.connect(':memory:')

# 创建测试数据
conn.execute("""
    CREATE TABLE orders AS 
    SELECT 
        i as order_id,
        'Product_' || (i % 100) as product_name,
        (i * 10.5)::DECIMAL(10,2) as amount,
        DATE '2024-01-01' + INTERVAL (i % 365) DAY as order_date
    FROM range(10000) t(i)
""")

# 基础导出
conn.execute("COPY orders TO 'orders_basic.csv'")

# 自定义分隔符（TSV 格式）
conn.execute("""
    COPY orders TO 'orders.tsv' 
    (DELIMITER '\t', HEADER true)
""")

# GZIP 压缩
conn.execute("""
    COPY orders TO 'orders.csv.gz' 
    (FORMAT csv, COMPRESSION gzip)
""")

# ZSTD 压缩（推荐，速度更快）
conn.execute("""
    COPY orders TO 'orders.csv.zst' 
    (FORMAT csv, COMPRESSION zstd)
""")

# 自定义日期格式
conn.execute("""
    COPY orders TO 'orders_custom_date.csv' 
    (DATEFORMAT '%Y/%m/%d', TIMESTAMPFORMAT '%Y-%m-%d %H:%M:%S')
""")

# 无表头导出
conn.execute("""
    COPY orders TO 'orders_no_header.csv' 
    (HEADER false)
""")

# 强制引用特定列
conn.execute("""
    COPY orders TO 'orders_force_quote.csv' 
    (FORCE_QUOTE ['product_name'])
""")
```text

**CSV 核心选项：**

| 选项 | 说明 | 默认值 |
|------|------|--------|
| COMPRESSION | 压缩类型：none/gzip/zstd | auto（根据扩展名） |
| DELIMITER | 列分隔符 | `,` |
| HEADER | 是否写入表头 | true |
| QUOTE | 引用字符 | `"` |
| NULLSTR | NULL 值表示 | 空字符串 |
| DATEFORMAT | 日期格式 | 默认格式 |

---

## Parquet 导出：分析场景的最优解

Parquet 是列式存储格式，天生适合分析查询。DuckDB 对 Parquet 的支持非常完整：

```python
# 基础导出（默认 snappy 压缩）
conn.execute("""
    COPY large_table TO 'data_snappy.parquet' 
    (FORMAT parquet)
""")

# ZSTD 压缩（更高压缩比）
conn.execute("""
    COPY large_table TO 'data_zstd.parquet' 
    (FORMAT parquet, COMPRESSION zstd)
""")

# ZSTD 高压缩级别
conn.execute("""
    COPY large_table TO 'data_zstd_high.parquet' 
    (FORMAT parquet, COMPRESSION zstd, COMPRESSION_LEVEL 15)
""")

# 自定义行组大小
conn.execute("""
    COPY large_table TO 'data_rowgroup.parquet' 
    (FORMAT parquet, ROW_GROUP_SIZE 50000)
""")

# 启用 Bloom 过滤器（加速点查询）
conn.execute("""
    COPY large_table TO 'data_bloom.parquet' 
    (FORMAT parquet, WRITE_BLOOM_FILTER true)
""")

# 添加自定义元数据
conn.execute("""
    COPY large_table TO 'data_metadata.parquet' 
    (FORMAT parquet, KV_METADATA {'author': 'DataLab X', 'version': '1.0'})
""")
```text

**Parquet 核心选项：**

| 选项 | 说明 | 默认值 |
|------|------|--------|
| COMPRESSION | 压缩类型：uncompressed/snappy/gzip/zstd/brotli/lz4 | snappy |
| COMPRESSION_LEVEL | 压缩级别（1-22，仅 zstd） | 3 |
| ROW_GROUP_SIZE | 行组大小（行数） | 122880 |
| WRITE_BLOOM_FILTER | 是否写入 Bloom 过滤器 | true |
| KV_METADATA | 自定义键值元数据 | 空 |

---

## JSON 导出：API 和日志的首选

JSON 有两种格式：换行分隔（NDJSON）和数组格式。

```python
# 创建带嵌套结构的数据
conn.execute("""
    CREATE TABLE user_logs AS 
    SELECT 
        i as log_id,
        'user_' || (i % 100) as username,
        TIMESTAMP '2024-01-01 00:00:00' + INTERVAL (i * 60) SECOND as log_time,
        {'ip': '192.168.1.' || (i % 255), 'browser': 'Chrome'} as metadata
    FROM range(5000) t(i)
""")

# 换行分隔 JSON（默认，适合流式处理）
conn.execute("""
    COPY user_logs TO 'logs_ndjson.json' 
    (FORMAT json)
""")

# JSON 数组格式（适合小数据集）
conn.execute("""
    COPY user_logs TO 'logs_array.json' 
    (FORMAT json, ARRAY true)
""")

# GZIP 压缩的 NDJSON
conn.execute("""
    COPY user_logs TO 'logs_ndjson.json.gz' 
    (FORMAT json, COMPRESSION gzip)
""")

# 导出查询结果
conn.execute("""
    COPY (
        SELECT username, COUNT(*) as action_count 
        FROM user_logs 
        GROUP BY username
    ) TO 'user_stats.json' 
    (FORMAT json, ARRAY true)
""")
```text

**两种 JSON 格式对比：**

NDJSON（换行分隔）：
```json
{"order_id":1,"product_name":"Product_1","amount":10.50}
{"order_id":2,"product_name":"Product_2","amount":21.00}
{"order_id":3,"product_name":"Product_3","amount":31.50}
```text

JSON 数组：
```json
[
  {"order_id":1,"product_name":"Product_1","amount":10.50},
  {"order_id":2,"product_name":"Product_2","amount":21.00},
  {"order_id":3,"product_name":"Product_3","amount":31.50}
]
```text

---

## 性能实测：10 万行数据对比

说了这么多，直接上数据。测试环境：DuckDB 1.5.5，10 万行数据，7 列（包含整数、字符串、日期、时间戳）。

### 导出性能

| 格式 | 文件大小 | 导出时间 | 压缩比 |
|------|---------|---------|--------|
| CSV（无压缩） | 7.78MB | 0.095s | 1.0x |
| CSV（gzip） | 1.43MB | 0.430s | 5.45x |
| CSV（zstd） | 1.41MB | 0.104s | 5.51x |
| Parquet（uncompressed） | 2.68MB | 0.029s | 2.91x |
| Parquet（snappy） | 1.56MB | 0.059s | 4.99x |
| Parquet（gzip） | 0.84MB | 0.216s | 9.30x |
| **Parquet（zstd）** | **0.73MB** | **0.045s** | **10.67x** |
| Parquet（zstd level 15） | 0.63MB | 0.232s | 12.39x |
| JSON（NDJSON） | 16.56MB | 0.168s | 0.47x |
| JSON（数组） | 16.75MB | 0.137s | 0.46x |
| JSON（gzip） | 1.49MB | 0.431s | 5.21x |

几个关键发现：

1. **Parquet+zstd 综合最优**：文件仅 0.73MB（压缩比 10.67 倍），导出速度 0.045 秒，比 CSV 快一倍还多。

2. **ZSTD 完胜 GZIP**：同样是 Parquet 格式，ZSTD 压缩比 GZIP 快 4-5 倍，压缩比还更高。这个差距在大数据集上会更明显。

3. **JSON 文件最大**：即使是 NDJSON 格式，文件也是 CSV 的 2 倍多（16.56MB vs 7.78MB）。JSON 的冗余度太高了。

4. **压缩级别要权衡**：ZSTD level 15 能把文件压到 0.63MB，但导出时间从 0.045 秒涨到 0.232 秒，慢了 5 倍。除非存储空间特别紧张，否则默认 level 3 就够了。

### 读取性能

导出只是一半，读取性能同样重要：

| 格式 | 读取时间 | 备注 |
|------|---------|------|
| CSV | 0.136s | 全量读取 |
| CSV（gzip） | 0.175s | 需要先解压 |
| **Parquet（snappy）** | **0.0005s** | 全量读取 |
| Parquet（zstd） | 0.0004s | 全量读取 |
| JSON | 0.091s | 全量读取 |

这个数据有点夸张了——**Parquet 读取比 CSV 快 271 倍**（0.0005s vs 0.136s）。

为什么差距这么大？Parquet 是列式存储，元数据里已经记录了每列的统计信息（最小值、最大值、空值数量），DuckDB 可以直接跳过不需要的数据块。CSV 是行式存储，必须从头到尾解析每一行。

---

## 分区导出：大数据集的必备技能

当数据量达到百万、千万级别，单个文件会变得很大。分区导出可以把数据按某个列（通常是日期）拆分成多个小文件，方便管理和查询。

```python
# 创建带分区字段的数据
conn.execute("""
    CREATE TABLE sales_data AS 
    SELECT 
        i as sale_id,
        'Product_' || (i % 50) as product,
        (i * 10.0)::DECIMAL(10,2) as amount,
        EXTRACT(YEAR FROM DATE '2023-01-01' + INTERVAL (i % 730) DAY) as year,
        EXTRACT(MONTH FROM DATE '2023-01-01' + INTERVAL (i % 730) DAY) as month
    FROM range(50000) t(i)
""")

# 按年月分区导出为 Parquet
conn.execute("""
    COPY sales_data TO 'sales_partitioned' 
    (FORMAT parquet, PARTITION_BY (year, month))
""")

# 分区导出为 CSV（GZIP 压缩）
conn.execute("""
    COPY sales_data TO 'sales_csv_partitioned' 
    (FORMAT csv, PARTITION_BY (year, month), COMPRESSION gzip, FILE_EXTENSION 'csv.gz')
""")

# 允许覆盖已存在的文件
conn.execute("""
    COPY sales_data TO 'sales_overwrite' 
    (FORMAT parquet, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE)
""")
```text

分区导出会自动创建 Hive 风格的目录结构：

```text
sales_partitioned/
├── year=2023/
│   ├── month=1/
│   │   └── data_0.parquet
│   ├── month=2/
│   │   └── data_0.parquet
│   └── ...
└── year=2024/
    ├── month=1/
    │   └── data_0.parquet
    └── ...
```text

读取分区数据时，加上 `hive_partitioning=true`：

```sql
SELECT year, month, COUNT(*) as cnt, SUM(amount) as total
FROM read_parquet('sales_partitioned/*/*/*.parquet', hive_partitioning=true)
GROUP BY year, month
ORDER BY year, month;
```text

实测 5 万行数据按年月分区，导出时间 0.091 秒，生成 24 个文件（2 年 × 12 月），总大小 1.80MB。

---

## 通用导出选项

除了格式特定的选项，还有一些通用选项：

```python
# 覆盖已存在的文件
conn.execute("""
    COPY large_data TO 'output.parquet' 
    (FORMAT parquet, OVERWRITE_OR_IGNORE true)
""")

# 每个线程输出一个文件（并行导出）
conn.execute("""
    COPY large_data TO 'output_dir' 
    (FORMAT parquet, PER_THREAD_OUTPUT true)
""")

# 限制文件大小（每个文件最大 10MB）
conn.execute("""
    COPY large_data TO 'output_sized' 
    (FORMAT parquet, FILE_SIZE_BYTES '10MB')
""")

# 返回写入统计信息
result = conn.execute("""
    COPY large_data TO 'output_stats.parquet' 
    (FORMAT parquet, RETURN_STATS)
""").fetchall()

print("写入统计:", result)
# 输出包含：filename, count, file_size_bytes, footer_size_bytes, column_statistics
```text

`RETURN_STATS` 这个选项挺实用，可以看到每个文件的行数、大小、列统计信息，方便做数据质量检查。

---

## 格式选择指南

三种格式各有适用场景，没有绝对的好坏：

**选择 CSV 当：**
- 需要与其他系统交换数据（Excel、数据库、BI 工具）
- 数据需要人类可读
- 简单的扁平数据结构
- 流式处理场景

**选择 Parquet 当：**
- 分析查询场景（OLAP）
- 需要高性能查询
- 数据有复杂类型（嵌套、数组）
- 需要保留 Schema 和类型信息
- 存储空间敏感

**选择 JSON 当：**
- API 数据交换
- 日志数据存储
- 需要嵌套结构
- 流式处理（NDJSON）
- 与 NoSQL 系统集成

如果实在不知道选哪个，**Parquet 是默认推荐**。文件小、查询快、类型信息完整，除了人类不能直接阅读，其他方面都碾压 CSV 和 JSON。

---

## 踩坑记录

### 坑 1：CSV 导出时特殊字符处理

数据里包含逗号或换行符时，CSV 会乱掉。解决方案是用 `QUOTE` 和 `ESCAPE` 选项：

```sql
COPY table TO 'data.csv' (QUOTE '"', ESCAPE '\');
```text

### 坑 2：Parquet 文件过大

单个 Parquet 文件超过 2GB 时，某些工具可能读不了。用 `FILE_SIZE_BYTES` 限制文件大小：

```sql
COPY table TO 'output' (FILE_SIZE_BYTES '1GB');
```text

### 坑 3：JSON 日期格式不符合预期

默认日期格式可能不是 ISO 标准，显式指定：

```sql
COPY table TO 'data.json' (DATEFORMAT '%Y-%m-%d', TIMESTAMPFORMAT '%Y-%m-%d %H:%M:%S');
```text

### 坑 4：分区导出覆盖已有数据

重新导出时报错"文件已存在"，加上 `OVERWRITE_OR_IGNORE`：

```sql
COPY table TO 'output' (PARTITION_BY (date), OVERWRITE_OR_IGNORE true);
```text

### 坑 5：并行导出文件命名冲突

`PER_THREAD_OUTPUT` 会导致多个线程写同一个文件名。解决方案是用目录而非文件名：

```sql
COPY table TO 'output_dir' (PER_THREAD_OUTPUT true);
```text

---

## 性能优化技巧

### CSV 优化

```sql
-- 使用 ZSTD 压缩（比 GZIP 快 4-5 倍）
COPY table TO 'data.csv.zst' (COMPRESSION zstd);

-- 自定义分隔符避免数据冲突
COPY table TO 'data.tsv' (DELIMITER '\t');
```text

### Parquet 优化

```sql
-- 使用 ZSTD 获得最佳压缩比
COPY table TO 'data.parquet' (COMPRESSION zstd);

-- 调整行组大小优化查询性能（小数据集用更小的行组）
COPY table TO 'data.parquet' (ROW_GROUP_SIZE 100000);

-- 启用 Bloom 过滤器加速点查询
COPY table TO 'data.parquet' (WRITE_BLOOM_FILTER true);

-- 分区导出大数据集
COPY table TO 'output' (PARTITION_BY (year, month));
```text

### JSON 优化

```sql
-- 使用 NDJSON 格式（默认）便于流式处理
COPY table TO 'data.json' (FORMAT json);

-- 大数据集使用压缩
COPY table TO 'data.json.gz' (FORMAT json, COMPRESSION gzip);
```text

---

## 总结

DuckDB 的 `COPY TO` 导出功能很强大，三种格式各有千秋：

- **CSV**：最通用，但文件大、查询慢
- **Parquet**：综合最优，文件小、查询快、类型完整
- **JSON**：适合 API 和日志，但冗余度高

实测数据说话：Parquet+zstd 压缩比 10.67 倍，读取速度比 CSV 快 271 倍。除非有特殊需求，否则 Parquet 是默认选择。

分区导出是大数据集的必备技能，配合 `hive_partitioning=true` 可以高效查询。

最后，别忘了压缩算法的选择：ZSTD 完胜 GZIP，速度更快、压缩比更高。

---

## 参考资源

- [DuckDB COPY 语句官方文档](https://duckdb.org/docs/current/sql/statements/copy)
- [CSV 写入文档](https://duckdb.org/docs/current/data/csv/writing_csv)
- [Parquet 写入文档](https://duckdb.org/docs/current/data/parquet/writing_parquet)
- [JSON 写入文档](https://duckdb.org/docs/current/data/json/writing_json)
- [分区写入文档](https://duckdb.org/docs/current/data/partitioning/partitioned_writes)


---

## 总结

DuckDB 的 `COPY TO` 导出功能很强大，三种格式各有千秋：

- **CSV**：最通用，但文件大、查询慢
- **Parquet**：综合最优，文件小、查询快、类型完整
- **JSON**：适合 API 和日志，但冗余度高

实测数据说话：Parquet+zstd 压缩比 10.67 倍，读取速度比 CSV 快 271 倍。除非有特殊需求，否则 Parquet 是默认选择。

分区导出是大数据集的必备技能，配合 `hive_partitioning=true` 可以高效查询。

最后，别忘了压缩算法的选择：ZSTD 完胜 GZIP，速度更快、压缩比更高。

---

## 参考资源

- [DuckDB COPY 语句官方文档](https://duckdb.org/docs/current/sql/statements/copy)
- [CSV 写入文档](https://duckdb.org/docs/current/data/csv/writing_csv)
- [Parquet 写入文档](https://duckdb.org/docs/current/data/parquet/writing_parquet)
- [JSON 写入文档](https://duckdb.org/docs/current/data/json/writing_json)
- [分区写入文档](https://duckdb.org/docs/current/data/partitioning/partitioned_writes)