Reference · 速查

Parquet 速查表

写代码时放在旁边的一页纸。命令可直接抄，参数带默认值与建议值。打印友好。

① 30 秒体检一个文件

-- 一眼看清：每列多大、什么编码、几个 row group、统计信息在不在
SELECT path_in_schema AS col,
       round(sum(total_compressed_size)/1024.0/1024, 2) AS mb,
       any_value(encodings) AS enc,
       any_value(compression) AS codec
FROM parquet_metadata('f.parquet') GROUP BY 1 ORDER BY mb DESC;

SELECT * FROM parquet_file_metadata('f.parquet');   -- 行数/rg 数/footer 大小
SELECT * FROM parquet_schema('f.parquet');          -- 物理类型 + 逻辑类型

或直接用课程脚本：python inspect_parquet.py f.parquet

② 写入参数：默认值 vs 建议值

③ 标准写法（抄这个）

import pyarrow.parquet as pq

LOW_CARD = ["tenant_id", "building_code", "device_id", "metric"]
t = table.sort_by([("device_id", "ascending"), ("ts", "ascending")])

pq.write_table(
    t, "out.parquet",
    compression="zstd",
    row_group_size=200_000,
    use_dictionary=LOW_CARD,                                # 收窄，防抢跑
    column_encoding={"ts": "DELTA_BINARY_PACKED"},          # 时序列
    write_page_index=True,
    sorting_columns=pq.SortingColumn.from_ordering(
        t.schema, [("device_id", "ascending"), ("ts", "ascending")]),
)

COPY (SELECT * FROM src ORDER BY device_id, ts)
  TO 'warehouse/iot'
  (FORMAT parquet, PARTITION_BY (day), COMPRESSION zstd, ROW_GROUP_SIZE 200000);

④ 读取速查

⑤ 编码选择决策树

这一列是什么？
├─ 重复值多（租户/楼栋/设备/枚举/状态）
│    → RLE_DICTIONARY（默认就是，别关）
├─ 递增整数（时间戳/自增 ID/序号）
│    → DELTA_BINARY_PACKED  ← 收益最大，务必显式指定
│      ⚠ 同时用 use_dictionary=[低基数列…] 收窄，否则不生效
├─ 有序且共同前缀的字符串（路径/URL/层级编码）
│    → DELTA_BYTE_ARRAY
├─ 浮点物理量（温度/压力/功率）
│    → 先试 BYTE_STREAM_SPLIT，实测对比后再决定 ← 可能是负收益
└─ 其他（高基数随机字符串、UUID）
     → PLAIN + zstd，并考虑给它加 Bloom filter

⑥ Sizing 决策表

⑦ 常见坑

⑧ 本课程实测数字（4,320,000 行楼宇时序样本）

⑨ 环境

$ pip install pyarrow duckdb          # 全课程只需这两个
$ brew install duckdb                  # 可选：命令行版
$ python gen_sample.py              # 生成样本数据（约 1 分钟）
$ python inspect_parquet.py f.parquet   # 体检任意文件