dataset.read_table()读空的主因是目录格式不匹配：默认仅识别hive分区路径或含_metadata文件，裸parquet文件需显式设format="parquet"或partitioning=false；filter须用pyarrow.compute表达式，如pc.match_substring(pc.field("name"),"abc")。
为什么 dataset.read_table() 读出来是空的
常见现象：用 dataset.read_table() 加载 Parquet 目录后，len(table) 是 0，但文件明明存在、用 pyarrow.parquet.read_table() 单个文件却能读出数据。
根本原因是：Dataset 默认只识别符合 Hive 分区路径格式（如 year=2023/month=04/）或含 _metadata/_common_metadata 的目录；裸 parquet 文件列表不被自动发现。
- 确认是否用了
format="parquet"显式指定（默认会尝试推断，但容易失败） - 检查路径下是否有
_metadata文件；没有就加partitioning=False或显式传partitioning="hive" - 如果只是几个独立
.parquet文件，别用dataset，直接用pyarrow.parquet.read_table([f1, f2])
filter 参数写不对，完全不生效
dataset.filter 不是 SQL WHERE，它是基于 Arrow 计算表达式的逻辑树，不支持字符串模糊匹配、函数调用或列别名。
典型错误：ds.filter("col LIKE '%abc%'") 或 ds.filter(pc.field("col") == "val")（漏掉 pc 模块导入或写法错）。
立即学习“Python免费学习笔记（深入）”；
- 必须导入
import pyarrow.compute as pc - 写法只能是
pc.field("col") == "val"、pc.greater(pc.field("ts"), pc.scalar("2023-01-01")) - 字符串匹配只能用
pc.match_substring()，不是LIKE：pc.match_substring(pc.field("name"), "abc") - filter 在 scan 阶段下推，但不会改变 schema；若字段不存在，运行时报
KeyError，不是静默跳过
scan() + to_table() 比 read_table() 慢很多
表面看都是读成 Table，但行为完全不同：read_table() 是“一次性全量加载+内存聚合”，scan().to_table() 是“先建执行计划+逐 batch 扫描+最后合并”，中间多一层计算图调度开销。
尤其在小数据集（read_table() 更快也更省内存。
- 用
scan()的真实价值在于：需要复用 scan 对象做多次不同 filter/project、或接to_reader()流式消费、或配合fragments做自定义分片 - 如果只是“读完就处理”，优先用
read_table(filter=..., columns=[...]) -
read_table(use_threads=True)默认已开并行，不用额外配；但scan()的线程数需通过use_threads显式传给to_table()
写入 dataset 时分区字段没进数据，反而变成目录名
分区字段不会自动保留在每张表的 column 里 —— 这是 Dataset 的设计约定：分区信息只存路径，不冗余进数据本身。
如果你需要分区列也在表中（比如后续要做 groupby 或 join），必须手动加回来。
- 写入时用
partitioning=pa.dataset.partitioning(...)只控制目录结构，不影响 table schema - 读取后想恢复分区字段，得用
ds.to_table(columns=["a", "b"], fragments=...)+ 手动从 fragment.path 提取值再 concat - 更稳妥的做法：写入前把分区列作为普通列保留，再用
existing_data_behavior="delete_matching"配合partitioning控制目录，避免丢失语义
分区不是魔法，它省的是扫描 IO，不是数据建模成本。路径解析、类型对齐、空分区处理，都得自己兜底。
