DuckDB 读取 Hive Parquet 怎么把日期分区列带出来

我第一次把按日期分区的 Parquet 目录交给 DuckDB 时，最容易误判的一点是：year 和 month 不一定写在 Parquet 文件的物理列里，它们可能只存在于目录名。只要目录采用 year=2025/month=03/part-000.parquet 这种 Hive 约定，读取时打开 hive_partitioning，DuckDB 就能把目录键值带成查询列。

官方地址：https://duckdb.org/

最小写法是 read_parquet('data/**/*.parquet', hive_partitioning = true)。如果分区列没有出现，先检查目录是否是 key=value 格式，再确认没有显式关闭该选项；日期列的类型处理则另看 hive_types。

• 目录键：year=2025/month=03 才能被按 Hive 分区解析。
• 读取开关：显式写 hive_partitioning=true 最容易排除自动识别差异。
• 类型边界：分区列能出现，不代表一定已经是你想要的 DATE 类型。

目录结构为什么决定分区列能否被识别

先看问题现场：文件本身只有 order_id 和 amount，但业务希望查询结果还能看到日期。DuckDB 的 Hive 分区读取依赖目录层级表达键值，而不是猜测普通文件夹名的含义。比如 data/year=2025/month=03/part-000.parquet 中，year 与 month 就是目录分区键。

这里要区分两类字段：Parquet 文件里的字段来自文件 schema，year、month 则来自路径解析。目录如果写成 2025/03/ 而不是 year=2025/month=03/，就没有足够的键名让 Hive 解析器生成同名列。

用 read_parquet 把日期分区列带出来

为了避免依赖自动识别，我通常会在排查阶段显式打开开关。下面的 SQL 只负责读取和投影分区列，不把业务聚合混进来：

-- 显式打开 Hive 分区解析，让目录键值成为可查询列
SELECT order_id, amount, year, month
FROM read_parquet(
    'data/**/*.parquet',
    hive_partitioning = true
)
LIMIT 20;

-- 用目录分区列筛选指定月份，避免先把所有月份混在一起
SELECT count(*) AS row_count
FROM read_parquet(
    'data/**/*.parquet',
    hive_partitioning = true
)
WHERE year = 2025 AND month = 3;

第一次查询用来确认列是否存在，第二次才引入筛选。这样分层排查的好处是：如果第一条就提示找不到 year，问题在路径命名或分区解析；如果第一条正常、第二条结果不符合预期，再去看值的类型和筛选条件。

日期类型和分区过滤要分开看

目录中的值最初来自字符串片段，但 DuckDB 会尝试对部分 Hive 分区类型做自动推断，日期、时间戳和大整数是官方文档明确提到的类型。若你需要稳定的 schema，可以显式给分区字段指定逻辑类型：

-- 明确声明分区字段类型，避免不同批次目录值被当成不同类型
SELECT year, month, order_id
FROM read_parquet(
    'data/**/*.parquet',
    hive_partitioning = true,
    hive_types = {'year': 'BIGINT', 'month': 'BIGINT'}
)
WHERE year = 2025 AND month BETWEEN 1 AND 3;

hive_types 解决的是“分区字段按什么逻辑类型解释”；WHERE year = 2025 解决的是“查询需要哪些分区”。两者不要混为一谈。对分区键的过滤还能帮助 DuckDB 跳过不相关文件，但这并不意味着 SQL 里的任意表达式都能获得同样的裁剪效果。

自动识别、关闭开关和常见误区

DuckDB 默认会尝试从路径中寻找 key=value 模式并自动识别 Hive 分区。生产查询仍建议在关键入口显式写出 hive_partitioning=true，因为它让代码意图更清楚；如果写成 false，目录值就不会作为 year、month 返回。

常见问题

普通的 year/2025 目录能自动变成分区列吗？

不能把它当作稳定约定。Hive 解析依赖 key=value 形式，建议整理为 year=2025 这样的目录。

一定要写 hive_partitioning=true 吗？

不是必须，DuckDB 会尝试自动识别；但在文章示例、共享查询或排查阶段显式写出更容易确认意图。

分区列能直接当 DATE 使用吗？

要看目录键的命名和类型推断结果。需要稳定 schema 时，用 hive_types 指定逻辑类型，并让筛选条件与该类型一致。

回到最初的问题，关键不是给 Parquet 文件“补写”日期字段，而是让 DuckDB 正确理解文件所在的 Hive 路径：目录用 key=value 表达分区，读取时打开 hive_partitioning，类型和筛选再分别处理。这样 year、month 才会从目录自然进入查询结果。