Apache Arrow PyArrow 数据类型与内存数据模型完全指南：从 DataType 到 Table 的列式数据全解析

数据工程大数据序列化数据分析【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow13/arrow点击查看免费下载Apache Arrow 通过类型元数据 内存缓冲区的组合定义了语言无关的列式数组数据结构。本文基于 Arrow 仓库官方文档 docs/source/python/data.rst系统讲解 PyArrow 中构建内存数据模型的五大核心类——DataType类型元数据、Schema模式、Array数组、RecordBatch记录批、Table表并结合仓库源码如 python/pyarrow/types.pxi、python/pyarrow/array.pxi、python/pyarrow/table.pxi剖析其底层实现。读完本文你将能够熟练创建各类 Arrow 数据类型与嵌套数组理解 null 与 NaN 的处理语义掌握 RecordBatch 与 Table 的分片、拼接和元数据管理并能将列式数据高效转换为机器学习所需的张量。五大核心类PyArrow 内存数据模型总览Apache Arrow 通过将类型元数据与内存缓冲区详见仓库中关于 Memory 与 IO 的文档组合定义了列式数组数据结构。这些结构在 Python 中通过一系列相互关联的类暴露出来类作用pyarrow.DataType类型元数据描述数组的类型决定其值如何被解释pyarrow.Schema模式命名类型的集合可理解为表状对象中的列类型集合pyarrow.Array数组由 Arrow Buffer 对象构成的原子化、连续的列式数据结构pyarrow.RecordBatch记录批具有特定 Schema 的 Array 对象的集合pyarrow.Table表逻辑表数据结构每列由一个或多个同类型的pyarrow.Array组成Schema类似于struct数组类型它定义了 record batch 或 table 数据结构中的列名与列类型。下面我们从最底层的类型元数据开始逐层深入。Type Metadata类型元数据Apache Arrow 定义了语言无关的面向列的数据结构其类型体系包括定长原始类型Fixed-length primitive types数字、布尔、日期与时间、定长二进制、decimal以及其他占据固定比特数的值变长原始类型Variable-length primitive typesbinary二进制、string字符串嵌套类型Nested typeslist列表、map映射、struct结构体、union联合字典类型Dictionary type一种编码后的类别型categorical类型后文详述每种数据类型在 Python 中都有对应的工厂函数来创建类型对象实例import pyarrow as pa t1 pa.int32() t2 pa.string() t3 pa.binary() t4 pa.binary(10) t5 pa.timestamp(ms) t1 print(t1) print(t4) print(t5)注意不同的数据类型可能使用相同的物理存储。例如int64、float64、timestamp[ms]每个值都占用 64 位。从源码看这些工厂函数定义于 python/pyarrow/types.pxi例如int32()第 3755 行、string()第 4337 行、binary(int length-1)第 4387 行length-1表示变长二进制、timestamp(unit, tzNone)第 3909 行可指定时间单位与可选时区。binary(10)会创建定长二进制类型FixedSizeBinary每个值恰好 10 字节。这些类型对象本质上是元数据用于描述数组、模式和记录批中的数据。在 Python 中它们可用于输入数据如 Python 对象可能被强制转换为多种 Arrow 类型的函数中。Field类型 名字 可选元数据pyarrow.Field是一个类型加上一个名字以及可选的用户自定义元数据f0 pa.field(int32_field, t1) f0 f0.name f0.typefield工厂函数types.pxi 第 3483 行签名支持field(name, typeNone, nullableNone, metadataNone)其中nullable控制该字段是否允许 nullmetadata可携带应用自定义的键值元数据详见后文自定义 Schema 与 Field 元数据小节。嵌套类型list 与 structArrow 支持list、map、struct、union等嵌套值类型。创建时必须传入类型或字段以指明子类型的数据类型。例如定义一个int32值的列表t6 pa.list_(t1) t6list_(value_type, int list_size-1)types.pxi 第 4554 行中list_size-1表示变长列表指定正数则创建 FixedSizeList。struct是命名字段的集合fields [ pa.field(s0, t1), pa.field(s1, t2), pa.field(s2, t4), pa.field(s3, t6), ] t7 pa.struct(fields) print(t7)为方便起见可以直接传入(name, type)元组而不必构造Field实例t8 pa.struct([(s0, t1), (s1, t2), (s2, t4), (s3, t6)]) print(t8) t8 t7struct工厂函数types.pxi 第 4887 行接受字段列表或(name, type)元组列表两种方式构造出的类型是相等的。Schemas模式pyarrow.Schema类型与struct数组类型类似它定义了 record batch 或 table 数据结构中的列名与列类型。pyarrow.schema工厂函数在 Python 中创建新的 Schema 对象my_schema pa.schema([(field0, t1), (field1, t2), (field2, t4), (field3, t6)]) my_schemaschema(fields, metadataNone)types.pxi 第 5304 行同样支持字段对象或(name, type)元组并可传入 schema 级别的元数据。在某些应用中你可能不会直接创建 schema而是使用嵌入在IPC 消息参见仓库 python/pyarrow/ipc.pxi 及docs/source/python/目录下关于 IPC 的文档中的 schema。Arrays数组针对每种数据类型都有一个对应的数组数据结构用于持有定义单个连续列式数据块的内存缓冲区。在使用 PyArrow 时这些数据可能来自 IPC 工具也可以由各种 Python 序列list、NumPy 数组、pandas 数据创建。创建数组类型推断与显式指定创建数组的最简单方式是使用pyarrow.array它类似于numpy.array。默认情况下PyArrow 会为你推断数据类型arr pa.array([1, 2, None, 3]) arr也可以传入指定的数据类型来覆盖类型推断pa.array([1, 2], typepa.uint16())从源码看array工厂函数python/pyarrow/array.pxi 第 121 行的完整签名为def array(object obj, typeNone, maskNone, sizeNone, from_pandasNone, bint safeTrue, MemoryPool memory_poolNone):其关键参数包括type显式指定 Arrow 类型否则从数据推断mask布尔数组标记哪些值应为 nullTrue或非 nullFalsesize元素个数若已知精确大小指定它可避免初始分配后的扩容提升性能from_pandas使用 pandas 的语义推断 ndarray 类数据中的 null传入 pandas 对象时默认开启safe默认 True检查溢出或其他不安全转换memory_pool指定内存池不传则使用当前默认内存池数组的固有属性数组的type属性即对应的类型元数据arr.type每个内存数组都有已知的长度length和 null 计数无 null 时为 0len(arr) arr.null_count标量值可通过常规索引选取。pyarrow.array会把None转换为 Arrow null访问 null 位置时返回特殊的pyarrow.NA值arr[0] arr[2]Arrow 数据是不可变的因此只能取值不能赋值。数组可以零拷贝切片arr[1:3]None 与 NaN 的处理如前述Python 对象None在转换为pyarrow.Array时总是被转换为 Arrow null 元素。对于浮点 NaN 值由float(nan)或numpy.nan表示转换时通常将其转换为有效的浮点值。如果向pyarrow.array提供包含np.nan的整数输入则会抛出ValueError。为了与 pandas 更好地兼容PyArrow 支持将 NaN 值解释为 null 元素。这在所有from_pandas函数上是自动启用的其他转换函数则可通过传入from_pandasTrue参数开启对应源码中array()的from_pandas参数。List arrays列表数组pyarrow.array能够推断简单的嵌套数据结构如列表的类型nested_arr pa.array([[], None, [1, 2], [None, 1]]) print(nested_arr.type)ListView arrays列表视图数组pyarrow.array还可以创建另一种列表类型ListViewnested_arr pa.array([[], None, [1, 2], [None, 1]], typepa.list_view(pa.int64())) print(nested_arr.type)ListView 数组与 List 数组的缓冲区集合不同ListView 数组同时拥有offsets偏移和 sizes大小两个缓冲区而 List 数组只有一个 offsets 缓冲区。这允许 ListView 数组指定乱序的偏移values [1, 2, 3, 4, 5, 6] offsets [4, 2, 0] sizes [2, 2, 2] arr pa.ListViewArray.from_arrays(offsets, sizes, values) arr对应的实现为 python/pyarrow/array.pxi 中的cdef class ListViewArray(BaseListArray)第 2760 行其from_arrays(offsets, sizes, values, ...)静态构造器第 2766 行直接从 int32 偏移、大小与值数组构建。关于 ListView 在 Arrow 格式规范中的物理布局细节可参考格式规范中关于 listview-layout 的说明。Struct arrays结构体数组pyarrow.array能够从字典数组推断 struct 类型的 schemapa.array([{x: 1, y: True}, {z: 3.4, x: 4}])Struct 数组可以从 Python 字典或元组序列初始化。对于元组必须显式传入类型ty pa.struct([(x, pa.int8()), (y, pa.bool_())]) pa.array([{x: 1, y: True}, {x: 2, y: False}], typety) pa.array([(3, True), (4, False)], typety)初始化 struct 数组时null 既允许出现在 struct 层级也允许出现在单个字段层级。如果从 Python 字典序列初始化缺失的字典键会被处理为 null 值pa.array([{x: 1}, None, {y: None}], typety)还可以从 struct 各组成部分的既有数组构造 struct 数组。此时数据存储与各数组共享不涉及拷贝xs pa.array([5, 6, 7], typepa.int16()) ys pa.array([False, True, True]) arr pa.StructArray.from_arrays((xs, ys), names(x, y)) arr.type arrStructArray.from_arrays的实现位于 python/pyarrow/array.pxi 第 3979 行cdef class StructArray(Array)定义于第 3888 行。Map arrays映射数组Map 数组可以从元组列表的列表键值对构造但必须显式传入类型data [[(x, 1), (y, 0)], [(a, 2), (b, 45)]] ty pa.map_(pa.string(), pa.int64()) pa.array(data, typety)MapArray 也可以从 offset、key、item 数组构造。Offsets 表示每个 map 的起始位置。注意MapArray.keys和MapArray.items属性给出的是扁平化后的键与值若要保留键值与行的关联需要使用ListArray.from_arrays构造器配合MapArray.offsets属性arr pa.MapArray.from_arrays([0, 2, 3], [x, y, z], [4, 5, 6]) arr.keys arr.items pa.ListArray.from_arrays(arr.offsets, arr.keys) pa.ListArray.from_arrays(arr.offsets, arr.items)Union arrays联合数组联合类型是一种嵌套数组类型其中每个值可以是候选类型集合中的**一种且仅一种**类型。联合数组有两种存储形式稀疏sparse与稠密dense。在稀疏联合数组中每个子数组的长度与结果联合数组相同并通过一个int8的 types 数组指示每个值应从哪个子数组选取xs pa.array([5, 6, 7]) ys pa.array([False, False, True]) types pa.array([0, 1, 1], typepa.int8()) union_arr pa.UnionArray.from_sparse(types, [xs, ys]) union_arr.type union_arr在稠密联合数组中除int8的 types 数组外还需传入一个int32的 offsets 数组指明每个值在所选子数组中的偏移位置xs pa.array([5, 6, 7]) ys pa.array([False, True]) types pa.array([0, 1, 1, 0, 0], typepa.int8()) offsets pa.array([0, 0, 1, 1, 2], typepa.int32()) union_arr pa.UnionArray.from_dense(types, offsets, [xs, ys]) union_arr.type union_arr底层实现见 python/pyarrow/array.pxi 的cdef class UnionArray(Array)第 3479 行from_dense第 3547 行与from_sparse第 3591 行最终分别调用 C 层的CDenseUnionArray.Make与CSparseUnionArray.Make。此外UnionArray暴露了type_codes属性获取 types 数组与offsets属性仅稠密联合可用稠密模式外访问会抛出ArrowTypeError。Dictionary Arrays字典数组PyArrow 中的Dictionary类型是一种特殊数组类型类似于 R 中的 factor 或pandas.Categorical。它允许文件或流中的一个或多个 record batch 传输引用共享字典包含逻辑数组中的去重值的整数索引。这一机制在字符串场景尤其常用可节省内存并提升性能。Apache Arrow 格式中字典的处理方式与在 C/Python 中的呈现略有不同PyArrow 定义了特殊的DictionaryArray类型及对应的字典类型。例如indices pa.array([0, 1, 0, 1, 2, 0, None, 2]) dictionary pa.array([foo, bar, baz]) dict_array pa.DictionaryArray.from_arrays(indices, dictionary) dict_array这里我们得到print(dict_array.type) dict_array.indices dict_array.dictionaryDictionaryArray.from_arrays(indices, dictionary, maskNone, orderedFalse, ...)的实现位于 python/pyarrow/array.pxi 第 3815 行类定义于第 3735 行。当与 pandas 配合时DictionaryArray的对应物是pandas.Categoricaldict_array.to_pandas()Record Batches记录批Apache Arrow 中的Record Batch是一组等长数组实例的集合。考虑一组数组data [ pa.array([1, 2, 3, 4]), pa.array([foo, bar, baz, None]), pa.array([True, None, False, True]) ]使用RecordBatch.from_arrays可以从数组列表创建记录批batch pa.RecordBatch.from_arrays(data, [f0, f1, f2]) batch.num_columns batch.num_rows batch.schema batch[1]RecordBatch类定义于 python/pyarrow/table.pxi 第 2403 行其官方文档特别提示不要直接调用该类的构造函数应使用RecordBatch.from_*系列工厂函数如from_arrays、from_pandas、from_pylist或使用等价的pyarrow.record_batch便捷函数。RecordBatch还提供validate(fullFalse)方法执行校验fullTrue时执行可能为 O(n) 的深度校验失败抛出ArrowInvalid。与数组一样record batch 可以零拷贝切片batch2 batch.slice(1, 3) batch2[1]slice(offset0, lengthNone)的实现位于 python/pyarrow/table.pxi 第 3025 行附近。Tables表PyArrow 的Table类型不是 Apache Arrow 规范的一部分而是用于将多个 record batch 和数组片段作为单一逻辑数据集来处理的工具。一个典型场景是通过 socket 流接收到多个小 record batch随后需要将它们拼接为连续内存以便用于 NumPy 或 pandas。Table对象可以在不产生额外内存拷贝的情况下高效完成这一任务。以上面创建的 record batch 为例可以使用Table.from_batches创建包含一个或多个该 batch 副本的表batches [batch] * 5 table pa.Table.from_batches(batches) table table.num_rowsTable.from_batches(batches, schemaNone)python/pyarrow/table.pxi 第 4798 行接受 RecordBatch 的序列或迭代器所有 batch 的 schema 必须相等schema不传时从第一个 RecordBatch 推断。表的列是ChunkedArray的实例它是一个或多个同类型数组的容器c table[0] c c.num_chunks c.chunk(0)ChunkedArray类定义于 python/pyarrow/table.pxi 第 23 行num_chunks第 1220 行返回块数chunk(i)第 1237 行返回第 i 个块。如 pandas 互操作相关文档所述可以将这些对象转换为连续的 NumPy 数组以供 pandas 使用c.to_pandas()多个表还可以在 schema 相等的前提下通过pyarrow.concat_tables拼接为单个表tables [table] * 2 table_all pa.concat_tables(tables) table_all.num_rows c table_all[0] c.num_chunksconcat_tables(tables, memory_poolNone, promote_optionsnone, **kwargs)python/pyarrow/table.pxi 第 6029 行的promote_options参数控制 schema 类型不匹配时的提升策略。这类似于Table.from_batches但输入是表而非 record batch。Record batch 可以转换为表但反之不行——因此如果你的数据已经是表形式请使用pyarrow.concat_tables。自定义 Schema 与 Field 元数据Arrow 同时支持schema 级与field 级的自定义键值元数据允许系统插入应用自定义的元数据以定制行为。自定义元数据可通过Schema.metadataschema 级与Field.metadatafield 级访问。注意这些元数据在 IPC 过程中会被保留。要定制现有表的 schema 元数据可使用Table.replace_schema_metadatatable.schema.metadata # empty table table.replace_schema_metadata({f0: First dose}) table.schema.metadata要定制表 schema 中字段的元数据可使用Field.with_metadatafield_f1 table.schema.field(f1) field_f1.metadata # empty field_f1 field_f1.with_metadata({f1: Second dose}) field_f1.metadatareplace_schema_metadata的实现python/pyarrow/table.pxi 第 2537 行RecordBatch亦同明确说明它会创建数据的浅拷贝并不会真正修改 Schema——Schema 是不可变的。调用Table.replace_schema_metadata时实际创建了一个新对象。要修改 schema 中字段的元数据则需要定义一个新 schema 并将数据 cast 到这个 schemamy_schema2 pa.schema([ pa.field(f0, pa.int64(), metadata{name: First dose}), pa.field(f1, pa.string(), metadata{name: Second dose}), pa.field(f2, pa.bool_())], metadata{f2: booster}) t2 table.cast(my_schema2) t2.schema.field(f0).metadata t2.schema.field(f1).metadata t2.schema.metadata元数据的键值对在 C 实现中是std::string对象因此在 Python 中表现为字节对象b...。Record Batch Readers记录批读取器PyArrow 中许多函数返回或接受RecordBatchReader参数。它可以像任何 record batch 的可迭代对象一样使用同时无需获取任何 batch 即可提供其公共 schema schema pa.schema([(x, pa.int64())]) def iter_record_batches(): ... for i in range(2): ... yield pa.RecordBatch.from_arrays([pa.array([1, 2, 3])], schemaschema) reader pa.RecordBatchReader.from_batches(schema, iter_record_batches()) print(reader.schema) pyarrow.Schema x: int64 for batch in reader: ... print(batch) pyarrow.RecordBatch x: int64 pyarrow.RecordBatch x: int64它还可以通过C stream 接口在语言之间传输相关实现参见 python/pyarrow/_dlpack.pxi 及仓库中关于 C Data Interface 的文档。将 RecordBatch 转换为 TensorRecordBatch中每个数组都有自己的连续内存但这些内存块之间不一定相邻。机器学习库常用的二维数组又称二维张量或矩阵则只占用一个连续内存块。为此PyArrow 提供了pyarrow.RecordBatch.to_tensor()函数用于高效地将表格型列式数据转换为张量。此转换支持的数类型为无符号整型、有符号整型与浮点型。目前仅支持按列优先column-major的转换 import pyarrow as pa arr1 [1, 2, 3, 4, 5] arr2 [10, 20, 30, 40, 50] batch pa.RecordBatch.from_arrays( ... [ ... pa.array(arr1, typepa.uint16()), ... pa.array(arr2, typepa.int16()), ... ], [a, b] ... ) batch.to_tensor() pyarrow.Tensor type: int32 shape: (9, 2) strides: (4, 36) batch.to_tensor().to_numpy() array([[ 1, 10], [ 2, 20], [ 3, 30], [ 4, 40], [ 5, 50]], dtypeint32)to_tensor的实现位于 python/pyarrow/table.pxi 第 3492 行签名支持null_to_nan、row_major当前仅 column-major 支持与memory_pool参数张量的 NumPy 视图转换由 python/pyarrow/tensor.pxi 中的Tensor.to_numpy提供。当null_to_nan设为True时也可以转换含 null 的数据null 会被转换为NaN import pyarrow as pa batch pa.record_batch( ... [ ... pa.array([1, 2, 3, 4, None], typepa.int32()), ... pa.array([10, 20, 30, 40, None], typepa.float32()), ... ], names [a, b] ... ) batch.to_tensor(null_to_nanTrue).to_numpy() array([[ 1., 10.], [ 2., 20.], [ 3., 30.], [ 4., 40.], [nan, nan]])小结PyArrow 的内存数据模型由类型元数据 → Schema → Array → RecordBatch → Table逐层构成DataType描述值如何被解释Schema组织命名列Array承载连续列式数据RecordBatch将等长数组集合为行式视图Table则把多个 batch 整合为无拷贝的逻辑数据集。在此基础上PyArrow 还提供了丰富的嵌套类型list、ListView、struct、map、union、高效的字典编码数组、可穿透 IPC 的自定义元数据、流式读取器RecordBatchReader以及面向机器学习场景的to_tensor转换能力。理解这套数据模型是后续掌握 PyArrow 的 IPC 序列化、pandas/NumPy 互操作以及 Parquet、数据集等上层工具的基础。赞分享数据工程大数据序列化数据分析【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow13/arrow点击查看免费下载相关推荐Apache Arrow Python 列式内存数据模型完全指南类型元数据、数组、Record Batch 与 TableApache Arrow Python 列式内存数据模型完全指南类型元数据、数组、Record Batch 与 Table Apache Arrow 在 Py数据工程数据分析大数据PyArrow 内存数据模型完全指南数据类型、Schema、Array、RecordBatch 与 Table 的构建、切片与互操作PyArrow 内存数据模型完全指南数据类型、Schema、Array、RecordBatch 与 Table 的构建、切片与互操作 本篇基于 Apache大数据数据分析数据工程序列化Apache Arrow C 数据类型Data Types完全指南DataType 表示、类型工厂、TypeTraits 与访问者模式Apache Arrow C 数据类型Data Types完全指南DataType 表示、类型工厂、TypeTraits 与访问者模式 导读 本文基于数据工程大数据序列化数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考