如何在Python中通过Apache Arrow IPC维护Polars DataFrame元数据？

Polars底层基于Apache Arrow，天然支持利用Arrow的元数据机制在序列化/反序列化过程中保留自定义信息。以下是具体实现步骤：

1. 给DataFrame添加自定义元数据 #

你可以给整个DataFrame添加全局元数据，也可以给单个列添加专属元数据，两者都通过Polars的with_metadata方法实现。

示例代码： #

import polars as pl

# 创建带列级元数据的DataFrame
df = pl.DataFrame(
    {
        "timestamp": pl.date_range(start="2024-01-01", end="2024-01-03", interval="1d"),
        "value": [10, 20, 30],
        "coords": pl.Series([(1.0, 2.0), (3.0, 4.0), (5.0, 6.0)], dtype=pl.List(pl.Float64))
    },
    schema={
        "timestamp": pl.Datetime(time_unit="ms").with_metadata({"timezone": "UTC", "source": "postgres_db.sensor_data"}),
        "value": pl.Int64.with_metadata({"unit": "kg", "precision": "0.1"}),
        "coords": pl.List(pl.Float64).with_metadata({"crs": "EPSG:4326", "coord_type": "WGS84"})
    }
)

# 给DataFrame添加全局元数据（比如生成方式、创建时间）
df = df.with_metadata({"generation_method": "daily_hourly_aggregation", "created_at": "2024-05-20T14:30:00"})

2. 序列化为Apache Arrow IPC格式 #

使用Polars的write_ipc方法将DataFrame写入Arrow IPC文件，元数据会自动嵌入到文件中，无需额外处理。

示例代码： #

# 序列化到Arrow IPC文件（Feather格式本质也是Arrow IPC，也可使用write_feather）
df.write_ipc("data_with_metadata.arrow")

3. 反序列化并读取元数据 #

读取IPC文件后，直接通过metadata属性获取全局元数据，通过schema访问列级元数据。

示例代码： #

# 从IPC文件加载DataFrame
df_loaded = pl.read_ipc("data_with_metadata.arrow")

# 获取全局元数据
print("全局元数据:", df_loaded.metadata)

# 遍历获取每一列的元数据
for col in df_loaded.columns:
    col_meta = df_loaded.schema[col].metadata
    print(f"列 {col} 的元数据:", col_meta)

注意事项 #

• 元数据的键和值必须都是字符串类型，如果需要存储复杂结构（比如字典、列表），可以先序列化为JSON字符串再存入。
• 确保使用的Polars版本与Apache Arrow版本兼容，避免元数据读取异常。
• Arrow IPC的元数据嵌入在文件内部，不会显著增加文件体积，适合长期存储和数据追溯。

常见应用场景 #

• 数据 lineage 追踪：存储DataFrame的生成逻辑（如聚合规则、过滤条件）或数据源信息（数据库表、API地址）。
• 列属性标注：记录列的时区、单位、精度等业务相关信息。
• 地理空间数据管理：保留坐标参考系（CRS）信息，避免后续处理时出现坐标系统混淆。

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