Apache Arrow 术语表全解:Columnar Format 核心概念与源码级剖析

原创2026-09-22 14:38:051,837 阅读
文章标签:数据工程大数据序列化数据分析

Apache Arrow 术语表全解:Columnar Format 核心概念与源码级剖析

本指南以 Apache Arrow 官方格式规范中的 Glossary 为骨架,系统讲解数组(Array)、缓冲区(Buffer)、记录批(Record Batch)、表(Table)、嵌套类型(Nested Type)、字典编码(Dictionary Encoding)与扩展类型(Extension Type)等核心术语的准确定义、内存布局特征及其在各语言实现中的差异。读完本文,你将能精确区分"列式格式内"与"特定语言实现内"两个层面的概念边界,并能在阅读 Columnar 规范 与源码时快速对号入座。

术语表的定位与阅读方法

Arrow 生态横跨 C++、Java、Python、Go、Rust、C# 等多种语言,各项目历史上对同一概念使用了不同词汇(例如 "array" 与 "vector" 常常混用)。为消除歧义,Apache Arrow 官方文档在 Glossary.rst 中维护了一份按字母排序、带交叉引用的术语表。所有条目都指向 Columnar Format 规范,该规范定义了语言无关的内存数据结构、元数据序列化方式以及通用的序列化传输协议。

阅读术语表时需要始终区分两个层面:

  • 列式格式(columnar format)层面:属于跨语言协议标准,任何实现都必须遵循;
  • 语言实现层面:部分概念(如 chunked array、table)并非格式规范的一部分,而只是某些语言(主要是 C++ 及其绑定,以及 Go)在 API 层面的便利抽象。

Array(数组)与 Vector(向量):列式存储的基本单元

A contiguous, one-dimensional sequence of values with known length where all values have the same type.

数组是长度已知、所有值类型相同的一维连续值序列,由零个或多个缓冲区(buffers)、一个非负长度和一个**数据类型(data type)**构成。缓冲区的排列方式由数据类型依据列式格式(:doc:./Columnar``)决定。

该条目还澄清了两个容易误解的性质:

  • 连续(contiguous):指遍历数组时始终遍历同一组缓冲区。这不代表数组只能占用一块连续内存——数组可以包含多块不连续的缓冲区,或由横跨多个缓冲区的子数组构成,但对遍历者而言逻辑上是连续的;
  • 一维(one-dimensional):指数组是槽位(slot)或单值(singular value)的序列。即使某些数据类型(如 struct、union)的一个槽位在语义上代表多个值,数组本身仍是一维的。

术语表中注明 "array" 与 "vector" 在不同实现中可互换使用,规范文档统一采用 "array"。

在源码层面,C++ 实现将这一概念落实为 arrow::Array 基类(见 cpp/src/arrow/array/array_base.h#L53),所有具体数组类型(Int32Array、StringArray、StructArray 等)都继承自它;而 Java 实现则习惯称其为 Vector(见 java/vector 模块)。

Buffer(缓冲区):数组数据的物理容器

A contiguous region of memory with a given length.

缓冲区是一块给定长度的连续内存区域,用于存储数组数据。术语表特别指出,缓冲区可以位于 CPU 内存、由文件内存映射而来,也可以位于设备内存(如 GPU)中——不过并非所有 Arrow 实现都支持所有这些可能性。

在列式布局中,一个数组通常由多个缓冲区组成,例如:

  • 有效性位图(validity bitmap):记录每个槽位是否为 null;
  • 数据缓冲区:存放实际值;
  • 偏移量缓冲区:用于变长类型(如字符串、List)。

从 C++ 源码可见,ArrayData 通过 buffers 向量持有这些缓冲区,而 Buffer 类提供了 size()、data() 等访问接口。IPC 序列化时,每个缓冲区作为消息体的一部分独立写出(详见下文 IPC 条目及 format/Message.fbs 中的 BodyCompression 表)。

数据类型:Data Type、Primitive Type、Nested Type 与 Parent/Child 关系

Data Type(数据类型 / Type)

A type that a value can take, such as Int8 or List[Utf8].

数据类型决定数组的值如何在内存中按 Columnar 规范 布局。内置类型的权威定义在 format/Schema.fbs(Flatbuffers 协议定义文件)中,包括 Null、Boolean、Int、FloatingPoint、Decimal、Date、Time、Timestamp、Interval、List、LargeList、ListView、FixedSizeList、Map、Struct、Union、Dictionary 等。

Primitive Type(原始类型)

A data type that does not have any child types.

没有子类型的类型称为原始类型,例如定宽数值类型、变长二进制、Null 类型。一个典型的例子:32 位有符号整数数组与 32 位浮点数组具有相同的物理布局(Fixed-size Primitive),只是语义类型不同。

Nested Type(嵌套类型)与 Complex Type

A data type whose structure depends on one or more other child data types.

嵌套类型是结构依赖于一个或多个子数据类型的数据类型。例如 List 是有一个子类型的嵌套类型。术语表给出关键性质:

两个嵌套类型相等,当且仅当它们的子类型也相等。

例如 List<a href="https://link.gitcode.com/i/13bdeb651c6bd34b6ecd818e45752f2b" target="_blank">Int32] 与 List[Utf8] 是不同类型的列表,List[Int32] 与 List[Int64] 也不同。这一性质在 [Columnar.rst 的 Terminology 一节有等价表述,并补充了"参数化类型(parametric type)"的概念:所有嵌套类型天然是参数化的,Timestamp 也是参数化的(需要单位如微秒以及时区)。

Parent/Child Type 与 Parent/Child Array

术语表用 List[Int32] 这个例子把类型关系与数组关系对应起来:

  • parent type / child type:在嵌套类型中,嵌套类型本身是父类型,其参数是子类型。List[Int32] 中 List 是父类型,Int32 是子类型;
  • parent array / child array:在嵌套类型的数组中,父数组对应父类型,子数组对应子类型。一个 List[Int32] 类型的父数组拥有一个 Int32 类型的子数组。

Slot(槽位):数组中的"行"

A single logical value within an array, i.e. a "row".

槽位是数组中的单个逻辑值,即"一行"。在嵌套类型中一个槽位可能对应多个物理值(例如一个 List 槽位包含若干元素),但逻辑上它始终是一个值。IPC 元数据中的 FieldNode 就通过 length(槽位数)与 null_count(观测到的空值数)来刻画数组中每个层级的信息,见 format/Message.fbs#L34-L43:

struct FieldNode {
  length: long;       // 该层级 Arrow 数组的值槽位数量
  null_count: long;   // 观测到的 null 数量;null_count == 0 时可以不物化有效性位图
}

Field(字段)与 Schema(模式)

A column in a schema. Consists of a field name, a data type, a flag indicating whether the field is nullable or not, and optional key-value metadata.

字段是模式中的一列,由四部分组成:字段名、数据类型、是否可空(nullable)标志、可选的键值元数据。

A collection of fields with optional metadata that determines all the data types of an object like a record batch or table.

模式是字段的集合(附带可选元数据),它决定了记录批(Record Batch)或表(Table)这类对象中所有列的数据类型。在 format/Schema.fbs 中,Field 和 Schema 表分别对应这两个概念;C++ 侧的对应实现为 arrow::Field 与 arrow::Schema,例如 Table::schema() 返回表的模式、Table::field(i) 返回第 i 列的字段(见 cpp/src/arrow/table.h#L104-L117)。

Record Batch(记录批)与 IPC 消息家族

Record Batch(记录批)

术语表给出了两个层面的定义:

  • IPC 格式层面:记录批是数据的基本单元(primitive unit),由与某个模式(schema)对应的一组**有序缓冲区(buffers)**构成;
  • 某些实现层面(主要是 C++ 及其绑定):记录批是一块连续、二维的数据块,由一组**长度相同的有序数组(arrays)**构成。

与数组类似,记录批的"连续"也指遍历其行时始终遍历同一组缓冲区。RecordBatchReader、RecordBatchFileReader 与 RecordBatchWriter 等类(见 cpp/src/arrow/ipc/reader.h 与 cpp/src/arrow/ipc/writer.h)负责在内存结构与 IPC 字节流之间转换。

IPC Message(IPC 消息)

The IPC representation of a particular in-memory structure, like a record batch or schema.

IPC 消息是特定内存结构(如记录批或模式)的 IPC 表示,必然是 Flatbuffers 协议文件中 MessageHeader 联合体(union)的成员之一。该联合体定义在 format/Message.fbs 中,覆盖 Schema、DictionaryBatch、RecordBatch、Tensor、SparseTensor 等消息类型。

IPC Streaming Format(IPC 流式格式)与 IPC File Format(IPC 文件格式)

  • 流式格式:一种用于流式传输 Arrow 数据或将数据序列化到文件的协议,由一连串 IPC 消息构成。它允许边生产边消费,适合管道式处理;
  • 文件格式 / 随机访问格式:流式格式的扩展,可将 Arrow 数据序列化到磁盘,然后以随机访问方式读取任意记录批。这正是 .arrow / .feather 类文件的基础,也是 RecordBatchFileReader 支持按批号随机读取的原因。

三者关系可概括为:IPC 消息是原子单元,流式格式是消息的有序流,文件格式在流式格式之上附加了随机访问能力。

Chunked Array(分块数组)与 Table(表):实现层面的聚合视图

Chunked Array(分块数组)

A discontiguous, one-dimensional sequence of values with known length where all values have the same type. Consists of zero or more arrays, the "chunks".

分块数组是不连续、一维、长度已知、类型统一的值序列,由零个或多个数组(即"块",chunks)组成。它与数组的关键区别在于"不连续":遍历分块数组的不同索引可能穿越不同的缓冲区。

术语表特别强调:

分块数组不是列式格式的一部分,该术语特指某些 Arrow 语言实现(主要是 C++ 及其绑定)。

C++ 实现中 arrow::ChunkedArray(见 cpp/src/arrow/chunked_array.h#L73)持有 ArrayVector chunks_,并提供 length()、null_count()、num_chunks()、chunk(i)、Slice() 等接口。需要注意的是,分块布局不是 API 契约——函数可能自行决定改变结果的分块方式,接收多个 ChunkedArray 的 API 也不应假定各输入的分块布局一致。

Table(表)

A discontiguous, two-dimensional chunk of data consisting of an ordered collection of chunked arrays. All chunked arrays have the same length, but may have different types. Different columns may be chunked differently.

表是不连续、二维的数据块,由一组有序的分块数组构成。所有分块数组长度相同,但类型可以不同,且不同列的分块方式可以不同。例如第 1 列可能分成 2 块,第 2 列分成 5 块,只要总行数一致即可。

与分块数组类似,表也不是列式格式的组成部分,而是特定语言实现的产物(例如 C++ 及其绑定,以及 Go)。C++ 的 arrow::Table(见 cpp/src/arrow/table.h)通过 column(i) 返回 ChunkedArray 列,并可通过 Table::FromRecordBatches、Table::Make、Table::Slice 等在批、数组与表之间转换。

一张图看懂 Table 与 Record Batch 的区别

术语表为 "table" 条目配了一张示意图,直观展示表(多列各自分块)与记录批(单块、同长数组集合)的结构差异:

Arrow Table 与 Record Batch 的结构对比:Table 由可分块不一致的 ChunkedArray 列构成,Record Batch 由同长的数组集合构成

核心差异可以总结为:

维度 Record Batch Table
维度特征 连续、二维 不连续、二维
构成单元 长度相同的有序数组 有序的分块数组
列分块方式 每列恰好一块,各列长度一致 各列可独立分块,仅总长一致
是否属于列式格式 IPC 中属于格式定义 不属于格式,属实现层概念

Dictionary(字典)与 Dictionary-Encoding(字典编码)

Dictionary-encoding: An array that stores its values as indices into a dictionary array instead of storing the values directly.

字典编码是一种压缩存储方式:数组不直接存储值,而是存储指向字典数组(dictionary)的索引。字典本身是一个承载实际值的数组,二者总是成对出现。这在基数较低(distinct 值少)的列上(如城市名、枚举状态)能显著减少内存占用。

在 format/Schema.fbs 中,字典类型通过 DictionaryEncoding 表描述(包括 id、indexType、isOrdered 等参数),对应的 C++ 实现为 arrow::DictionaryArray(见 cpp/src/arrow/array/array_dict.h#L53)。物理布局细节可参考 Columnar 规范中的字典编码布局章节。

Extension Type(扩展类型)与 Storage Type(存储类型)

An extension type is an user-defined data type that adds additional semantics to an existing data type. This allows implementations that do not support a particular extension type to still handle the underlying data type (the "storage type").

扩展类型是用户自定义的数据类型,它在既有数据类型之上附加额外的语义。其价值在于:不支持该扩展类型的实现仍然可以按底层存储类型(storage type)处理数据,从而保证互操作性。术语表给出的经典例子是:

UUID 可以表示为 16 字节的定长二进制类型(fixed-size binary)。

也就是说,uuid 扩展类型以 FixedSizeBinary(16) 为存储类型——语义层是"UUID",物理层只是一段 16 字节定长二进制,任何实现都能读写它。

Canonical Extension Type(规范化扩展类型)

规范化扩展类型是经过 Arrow 社区标准化、旨在提高实现间互操作性的扩展类型。它与一般扩展类型的区别在于:规范化类型由社区统一制定并纳入格式规范(参见 CanonicalExtensions.rst),而普通扩展类型由各项目自行定义。

源码实现印证

C++ 中 arrow::ExtensionType 基类(见 cpp/src/arrow/extension_type.h#L39-L104)完整实现了术语表的语义:

  • storage_type() 返回底层存储类型,storage_id() 返回存储类型的类型类别;
  • extension_name() 返回扩展类型的唯一名称,用于序列化时识别类型;
  • Serialize() / Deserialize() 负责扩展类型元数据的序列化与反序列化(存储类型由 IPC 代码路径自动处理);
  • WrapArray() 静态方法将存储数组包装为扩展数组;
  • ExtensionTypeRegistry(见 cpp/src/arrow/extension_type.h#L131)提供全局注册表,用于 RegisterType / GetType 等注册与查询操作。

此外,术语表 "extension type" 条目指向格式规范中的 Metadata 扩展类型章节,解释了扩展类型元数据如何与存储类型一并序列化。

Physical Layout(物理布局)

A specification for how to arrange values in memory.

物理布局是值在内存中的排列规范,与值语义无关。例如 32 位有符号整数数组与 32 位浮点数组共享同一种布局(Fixed-size Primitive),Decimal128 值以 16 字节存储在定长二进制布局中,时间戳以 64 位定长布局存储。

布局的完整规范曾独立成文(Layout.rst),现已在 Columnar 规范 中集中阐述,包括 Null、Primitive、Variable-size Binary、Fixed-size List、List、Struct、Sparse/Dense Union、Run-End Encoded 等各类布局的位图与缓冲排布规则。

概念关系速查与交叉引用

以下是术语表全部条目的关系图景,便于记忆与检索:

  • 值组织:array(连续一维)→ record batch(连续二维,IPC 基本单元)→ 流式/文件格式;chunked array(不连续一维)→ table(不连续二维),后两者是 C++/Go 实现层抽象;
  • 类型体系:data type 分为 primitive type 与 nested type(含 parent/child type 关系),slot 是数组中的逻辑值,buffer 是物理容器;
  • 元数据:field 组成 schema;dictionary-encoding 依赖 dictionary;extension type 建立在 storage type 之上,canonical extension type 是其中的规范化子集;
  • 序列化:IPC message(MessageHeader 成员)构成 IPC streaming format,其扩展为 IPC file format(随机访问);
  • 互操作:physical layout 决定值与内存的对应关系,保证多语言实现读写同一份数据。

如需深入,可继续阅读 Columnar 规范(列式内存布局与元数据)、IPC 规范(序列化协议)与 Metadata 规范(字段级元数据与扩展类型序列化),并结合 C++ 源码目录 cpp/src/arrow 中的 array/、table.h、chunked_array.h、extension_type.h、ipc/ 等模块对照研读。

登录后查看全文
arrow