
在 Polars 中定义 Schema 时,pl.Datetime 不能直接作为类型对象使用,必须调用其构造函数(如 pl.Datetime())以提供完整的时间单位和时区参数,否则会触发“dtypes must be fully-specified”错误。
在 polars 中定义 schema 时,`pl.datetime` 不能直接作为类型对象使用,必须调用其构造函数(如 `pl.datetime()`)以提供完整的时间单位和时区参数,否则会触发“dtypes must be fully-specified”错误。
Polars 对数据类型的规范性要求比许多其他库更严格:所有 dtype 在 Schema 中都必须是完全指定的实例,而非未调用的类本身。这一点在基础数值类型(如 pl.Int64、pl.Utf8)上不明显,因为它们是单例或无参类型;但 pl.Datetime 是一个需配置参数的类,其签名如下:
class polars.datatypes.Datetime(
time_unit: TimeUnit = "us",
time_zone: str | timezone | None = None
)因此,pl.Datetime 仅表示类,而 pl.Datetime() 才是符合 Schema 要求的有效 dtype 实例(使用默认微秒级精度和无时区)。若需自定义,可显式传参:
import polars as pl
testing_schema: pl.Schema = pl.Schema({
"date": pl.Datetime(), # 默认: time_unit="us", time_zone=None
"date_utc": pl.Datetime(time_unit="ns", time_zone="UTC"),
"some_int": pl.Int64,
"some_str": pl.Utf8,
"some_cost": pl.Float64,
})⚠️ 注意事项:
- 错误写法
pl.Datetime(无括号)会引发TypeError: dtypes must be fully-specified; -
time_unit可选值为"ns"(纳秒)、"us"(微秒)、"ms"(毫秒)或"s"(秒); -
time_zone支持 IANA 时区名(如"Asia/Shanghai")、datetime.timezone对象,或None(本地/无时区); - 同一 Schema 中不同列可使用不同时间精度或时区,Polars 会严格校验并确保类型安全。
正确初始化 Datetime 是构建可靠、可序列化的 Polars Schema 的关键一步——它不仅避免运行时错误,还为后续数据读取(如 pl.read_csv(..., schema=testing_schema))和类型推断提供明确契约。

















