Go parquet-go 怎么把结构体切片写成 Parquet 文件

如果手里已经有一批 Go 结构体，parquet-go 最直接的写法是把它们放进 []T，交给 parquet.WriteFile[T]。结构体字段会参与 schema 推导，parquet 标签可以固定列名、编码或压缩选项；当输出目标不是本地文件，或者数据要分批到达时，再换成 GenericWriter[T]。

下面的例子只围绕“结构体切片变成 Parquet 文件”展开，不把图片当成运行证据。项目文档目前要求 Go 1.22 或更高版本，依赖可以先这样加入：

# 安装用于读写 Parquet 的 Go 模块
go get github.com/parquet-go/parquet-go

先让结构体字段成为 Parquet 列

把一行数据定义成结构体，是这条路径里最重要的决定。字段类型表达数据类型，parquet 标签表达列名和可选的编码配置；切片中的每个元素就是一个逻辑行。

package main

import (
    "log"

    "github.com/parquet-go/parquet-go"
)

// Order 是一行订单数据，标签把 Go 字段映射为稳定的 Parquet 列名。
type Order struct {
    ID        int64   `parquet:"id"`
    Buyer     string  `parquet:"buyer,dict,zstd"`
    Amount    float64 `parquet:"amount"`
    CreatedAt int64   `parquet:"created_at"`
}

func main() {
    rows := []Order{
        {ID: 1001, Buyer: "林海", Amount: 39.5, CreatedAt: 1761302400},
        {ID: 1002, Buyer: "周宁", Amount: 88.0, CreatedAt: 1761302460},
    }

    // WriteFile 接收同一种结构体的切片，并负责创建 Parquet 文件。
    if err := parquet.WriteFile("orders.parquet", rows); err != nil {
        // 写入失败时不要把这个文件当成可继续使用的结果。
        log.Fatal(err)
    }
}

这里的重点不是把每个字段都写进标签，而是让输入结构稳定。比如 Buyer 的标签同时给出列名、字典编码和 Zstandard 压缩选项；是否使用这些选项要结合数据分布决定，不能把标签误解成排序规则。

小批量文件直接用 WriteFile

当数据已经在内存中、目标就是一个文件路径，而且不需要自定义输出流时，WriteFile 是最短的选择。它的核心输入只有路径和 []T，调用方仍然要检查返回的错误。

// rows 已经由上游整理成 []Order；这里选择便捷文件 API。
if err := parquet.WriteFile("orders.parquet", rows); err != nil {
    // 文件创建、schema 映射或编码失败都应交给上层处理。
    return fmt.Errorf("write orders parquet: %w", err)
}

这种写法适合导出任务、一次性批处理和数据集规模可控的场景。它不负责把多种不同结构体自动拼成一张表，也不会因为你给字段加了标签就替旧文件排序或更新；schema 和输出文件都应该被当成一次写出的整体。

需要流式目标时换 GenericWriter

如果目标是对象存储适配器、网络响应或其他 io.Writer，或者行数据会分批到达，可以创建 GenericWriter[T]。它保留了结构体类型参数，同时把“写到哪里”和“每批写多少”交给调用方。

func writeOrders(out io.Writer, batches [][]Order) error {
    // T 固定为 Order，编译器会约束后续 Write 的切片类型。
    writer := parquet.NewGenericWriter[Order](out)
    for _, batch := range batches {
        // 一批数据对应一组待写行；错误发生后不要继续复用这个输出。
        if _, err := writer.Write(batch); err != nil {
            return fmt.Errorf("write order batch: %w", err)
        }
    }
    // Close 会刷新缓冲区并写入 Parquet 文件尾部，不能省略。
    if err := writer.Close(); err != nil {
        return fmt.Errorf("close parquet writer: %w", err)
    }
    return nil
}

GenericWriter 的优势是类型参数和输出目标都明确；代价是调用方必须负责批次边界、错误后的放弃策略以及最终 Close。如果只是把一小段切片写到本地路径，它通常没有必要替代 WriteFile。

标签、schema 和文件边界

有三类边界最容易被忽略：

• 标签边界：标签可以表达列名、编码、压缩和逻辑类型等 schema 信息，但不会替你完成业务字段清洗。
• 显式 schema：需要让输出遵循预先约定的 schema 时，可以先用 parquet.SchemaOf(new(Order)) 得到 schema，再把它传给泛型 writer；传入的 schema 必须和类型约束相容。
• 文件边界：Parquet 文件写出后不可原地更新；如果数据要改变，应读出、修改后写到新文件。写入失败时也不要把半成品当成可重试的完整文件。

另外，当前仓库是 pre-v1 项目，维护者保留调整 API 的空间。升级依赖时应把编译和下游读取一起纳入回归范围，而不是只看 go get 是否成功。

按场景选择 API

相关问题

结构体字段一定要全部写入吗？不一定，实际列由结构体和 schema 配置共同决定；需要稳定契约时应显式声明并保持兼容。

WriteFile 能自动把多批数据追加到旧文件吗？不要这样设计。Parquet 文件按整体写出，业务上的追加应在应用层合并数据后重新生成目标文件，或采用适合追加模型的独立写入流程。

为什么 GenericWriter 写完还要 Close？写入过程可能仍有缓冲数据，关闭 writer 才能完成刷新并写出文件尾部元数据。

简单导出优先用 WriteFile；当输出目标、批次或 schema 需要由应用控制时，再升级到 GenericWriter。这样既保留结构体带来的类型约束，也不会为小任务引入不必要的生命周期管理。