Polars Schema 中 Datetime 类型必须显式初始化-Python教程-PHP中文网

Polars Schema 中 Datetime 类型必须显式初始化

在 Polars 中定义 Schema 时，pl.Datetime 不能直接作为类型引用使用，必须调用其构造函数（如 pl.Datetime()）以提供完整的时间单位和时区参数，否则会触发 TypeError: dtypes must be fully-specified 错误。

在 polars 中定义 schema 时，`pl.datetime` 不能直接作为类型引用使用，必须调用其构造函数（如 `pl.datetime()`）以提供完整的时间单位和时区参数，否则会触发 `typeerror: dtypes must be fully-specified` 错误。

Polars 的类型系统要求所有数据类型在 Schema 中必须是“完全指定的”（fully-specified）实例，而非抽象类型类本身。这与 pl.Int64、pl.Utf8、pl.Float64 等标量类型不同——它们本身就是单例对象（即类型常量），而 pl.Datetime 是一个需实例化的类，其签名如下：

class polars.datatypes.Datetime(
    time_unit: TimeUnit = "us", 
    time_zone: str | timezone | None = None
)

其中 time_unit 可选 "ns"（纳秒）、"us"（微秒）、"ms"（毫秒）；time_zone 可为时区字符串（如 "UTC"、"Asia/Shanghai"）或 None（无时区，即本地时间）。因此，以下写法是错误的：

# ❌ 错误：pl.Datetime 是类，未实例化
pl.Schema({"date": pl.Datetime})  # TypeError!

正确做法是显式调用构造函数，即使使用默认参数也需加 ()：

import polars as pl

# ✅ 正确：使用默认 time_unit="us", time_zone=None
schema = pl.Schema({
    "date": pl.Datetime(),
    "some_int": pl.Int64,
    "some_str": pl.Utf8,
    "some_cost": pl.Float64,
})

# ✅ 也可自定义参数
advanced_schema = pl.Schema({
    "date_utc": pl.Datetime(time_unit="ns", time_zone="UTC"),
    "date_local": pl.Datetime(time_unit="ms"),
    "id": pl.UInt32,
})

⚠️ 注意事项：

即使不关心时区或精度，也不可省略括号——pl.Datetime() 和 pl.Datetime 在 Python 中语义完全不同；
若后续需从 CSV/Parquet 等格式读取数据并应用该 Schema，Polars 会严格按指定 time_unit 和 time_zone 解析时间列，建议保持与数据源一致；
其他类似类型（如 pl.Duration、pl.Categorical、pl.List、pl.Struct）同样需要实例化，例如 pl.Duration("ms")、pl.List(pl.Float32)。