指定List类型Schema时Polars DataFrame创建失败原因排查

问题重现 #

尝试用Polars创建带指定Schema的两列DataFrame时报错，代码及现象如下：

import polars as pl

data = {"a": [ ["X"], ["Y"], []], "b": [3, 4, 5]}

# 不指定Schema时正常运行
df = pl.DataFrame(data)

df_schema = [("a", pl.List),
             ("b", pl.Int8)]

# 执行报错：invalid series dtype: expected `Utf8`, got `null`
df = pl.DataFrame(data, schema=df_schema)

不指定Schema时，Polars自动推断的DataFrame结构：

shape: (3, 2)
a           b
list[str]   i64
["X"]       3
["Y"]       4
[]          5

问题原因 #

直接写pl.List作为列类型是错误的——Polars的List是泛型类型，必须明确声明内部元素的子类型。自动推断时Polars识别出列a是list[str]（即pl.List(pl.Utf8)），但你指定的pl.List没有子类型信息，Polars无法匹配实际数据的类型，因此抛出错误。

解决方法 #

修改Schema，给List类型指定明确的子类型pl.Utf8，代码如下：

import polars as pl

data = {"a": [ ["X"], ["Y"], []], "b": [3, 4, 5]}

# 正确的Schema声明
df_schema = [("a", pl.List(pl.Utf8)),
             ("b", pl.Int8)]

df = pl.DataFrame(data, schema=df_schema)

# 查看结果
print(df)
print(df.schema)

运行后输出的DataFrame结构：

shape: (3, 2)
a           b
list[str]   i8
["X"]       3
["Y"]       4
[]          5

对应的Schema为：{'a': List(Utf8), 'b': Int8}，完全符合预期。

另外，列b指定pl.Int8是可行的，因为3、4、5都在Int8的取值范围（-128到127）内，不会出现溢出问题。

内容的提问来源于stack exchange，提问作者datahack