PyArrow生成Parquet数组嵌套节点解析及原始Schema获取

一、为什么数组会生成list/element（或item）嵌套节点？ #

你猜的没错，这确实和Parquet采用的Dremel编码直接相关：

• Parquet的列式存储天然适配扁平数据，但处理嵌套类型（数组、结构体）时，需要用Dremel的**重复层级（Repetition Level）和定义层级（Definition Level）**标记每个元素的嵌套位置与存在性。
• 逻辑层面的数组类型（比如PyArrow里的list<struct<...>>），在Parquet物理存储中会被拆分为两层：
  1. 外层list节点：作为重复字段的容器，记录数组的重复层级信息，标记哪些元素属于同一个数组实例。
  2. 内层element（旧版本PyArrow用item）节点：对应数组的实际元素类型，存储元素的具体数据和定义层级信息。
• 这种拆分是Parquet实现嵌套类型存储的标准方式，并非PyArrow特有，所有遵循Parquet规范的读写库都会处理成类似结构。

二、如何跳过命名差异，获取原始Schema用于数据库集成？ #

直接解析Parquet的物理Schema会遇到element/item的命名不一致问题，正确做法是读取逻辑Schema——也就是你创建文件时定义的原始Schema，PyArrow提供了直接获取的方法：

解决方案步骤 #

1. 使用pyarrow.parquet.read_schema()读取文件，返回的就是原始逻辑Schema，完全不会包含物理层的list/element节点。
2. 基于这个逻辑Schema，可以直接映射到数据库的表结构（比如数组对应SQL的ARRAY类型，结构体对应ROW类型），无需处理物理层的嵌套节点。

代码示例与Schema对比 #

生成带结构体数组的Parquet文件代码

import pyarrow as pa
import pyarrow.parquet as pq

# 定义原始Schema
struct_type = pa.struct([
    ("id", pa.int32()),
    ("name", pa.string())
])
schema = pa.schema([
    ("id", pa.int32()),
    ("struct_array", pa.list_(struct_type))
])

# 构造数据
data = pa.table([
    [1],
    [[{"id": 101, "name": "foo"}, {"id": 102, "name": "bar"}]]
], schema=schema)

# 写入Parquet文件
pq.write_table(data, "struct_array.parquet")

Schema输出对比

• 原始逻辑Schema（通过data.schema或read_schema获取）：

id: int32
struct_array: list<item: struct<
    id: int32,
    name: string
>>

• Parquet物理Schema（直接读取物理元数据可见）：

message schema {
  required int32 id;
  optional group struct_array (LIST) {
    repeated group list {
      optional group element {
        required int32 id;
        optional binary name (STRING);
      }
    }
  }
}

关键代码 #

读取原始逻辑Schema：

import pyarrow.parquet as pq

# 获取原始逻辑Schema
original_schema = pq.read_schema("struct_array.parquet")
print(original_schema)

这个original_schema就是你创建文件时的Schema，可以直接用于数据库表结构的映射，完全不用关心list/element/item这些物理层节点的命名差异。

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