Polars 读取 JSONL.gz 时的 Schema 匹配错误笔记（Gemini）

[!NOTE]
2026年2月6日，本文为个人和 AI 大模型 Gemini 对话之后再由 Gemini 进行总结生成，仅供参考。

这份笔记总结了在使用 Polars 处理压缩 JSONL 数据时遇到的 SchemaError 及其深度解决方案。

---

Polars 读取 JSONL.gz 时的 Schema 匹配错误笔记

1. 问题现象

使用 pl.read_ndjson()（或 scan_ndjson）读取 .jsonl.gz 文件时抛出异常：

polars.exceptions.SchemaError: data type mismatch for column formula: incoming: Boolean != target: Null

奇怪的是：先用 gzip 和 json 库手动加载再转 pl.DataFrame 却能成功。

---

2. 核心原因：推断机制的局限性

• 采样采样误判：Polars 在读取时会扫描文件前 \(N\) 行（默认 100 行）来自动推断每列的类型。
• Null 类型锁定：如果前 \(N\) 行中 formula 的值全是 null（Python 中的 None），Polars 会将该列类型定为 pl.Null。
• 类型冲突：当读取到第 \(N+1\) 行及以后，发现出现了 True 或 False（Boolean 类型）时，解析器认为无法将布尔值放入已定义的“永远为空”的槽位中，从而崩溃。
• 嵌套结构的影响：如果该 Key 位于一个 Struct（字典）内部，这种冲突会逐层上传，导致整个 metadata 列解析失败。

---

3. 解决方案

方案 A：显式定义嵌套 Schema（最严谨、性能最优）

通过 schema_overrides 参数强制指定该列及其子字段的结构。这样 Polars 就不再采样，而是直接按定义的类型读取。

代码参考：

Python

import polars as pl

# 1. 定义深层嵌套的结构
l1_sub_fields = [
    pl.Field("trigger", pl.Boolean),
    pl.Field("label_1_prob", pl.Float64)
]

# 2. 构建复杂的 metadata 结构
metadata_schema = pl.Struct([
    pl.Field("_source_file", pl.String),
    pl.Field("_id_in_file", pl.Int64),
    pl.Field("formula", pl.Boolean),  # 关键：强制设为 Boolean，解决冲突
    pl.Field("l1_fasttext", pl.Struct([
        pl.Field("L1_BasicSci", pl.Struct(l1_sub_fields)),
        pl.Field("L1_Eng", pl.Struct(l1_sub_fields)),
        # ... 其他子字段
    ])),
    # ... 其他字段
])

# 3. 读取时覆盖推断
df = pl.read_ndjson(
    "data.jsonl.gz",
    schema_overrides={"metadata": metadata_schema}
)

方案 B：先读为字符串，再异步解码（最灵活）

如果你不希望手动维护复杂的 Field 列表，可以先将整个对象读为 JSON 字符串，再利用 Polars 的 json_decode 动态解析。

代码参考：

Python

df = pl.read_ndjson(
    "data.jsonl.gz",
    schema_overrides={"metadata": pl.String} # 强制作为原始字符串读入
)

# 自动解析 JSON 字符串，这通常比初始扫描更智能
df = df.with_columns(
    pl.col("metadata").str.json_decode()
)

方案 C：增大采样深度（权宜之计）

如果 formula 只是偶尔在前面几行缺失，可以尝试增加推断行数。

Python

df = pl.read_ndjson("data.jsonl.gz", infer_schema_length=10000)

注意：如果数据分布非常不均，此方法依然可能失效。

---

4. 关键知识点总结

1. Polars 类型包含关系：pl.Boolean 是“可空”的，它可以包含 True, False 和 null。但 pl.Null 只能包含 null。
2. Struct 覆盖原则：在使用 schema_overrides 覆盖 Struct 内部字段时，必须写出该 Struct 的完整字段定义，否则未提到的字段会被丢弃。
3. Lazy 模式挑战：当使用 scan_ndjson（Lazy 模式）时，Polars 对 Schema 的准确性要求极高，因为查询优化器必须提前知道每一列的严格类型。

---

5. 操作建议

• 如果 Schema 固定：使用 方案 A，既能解决错误，读取速度也最快。
• 如果 Schema 经常变化 或字段极多：使用 方案 B，开发成本最低。