数据工程大数据序列化数据分析【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow13/arrow点击查看免费下载本指南以 docs/source/cpp/api/datatype.rst 为骨架系统梳理 Apache Arrow C 中的数据建模核心arrow::Type::type类型枚举、arrow::DataType抽象基类、官方推荐的类型工厂函数type-factories、六大类具体类型子类Primitive / Temporal / Binary-like / Nested / Dictionary / Extension以及承载列级元信息的Field、Schema、KeyValueMetadata与字段查找工具FieldPath、FieldRef。读完本文你将掌握如何用一行工厂函数精确描述任意 Arrow 数据布局理解逻辑类型与物理存储的映射关系并具备在 schema 中进行按名/按下标字段寻址的实战能力。一、总览从类型 ID 到 DataType 抽象基类Arrow 的 C 数据建模分为两层类型 IDType::type提供轻量、快速的类型分类标签DataType 对象承载完整可能是参数化的类型描述。文档中首先列出这两个核心入口。1.1 Type::type主数据类型枚举在 cpp/src/arrow/type_fwd.h#L305-L453 中Type::type枚举完整定义了 Arrow 支持的所有逻辑类型其 ID 值同时也是序列化与跨语言互操作的稳定标识。以下为核心枚举及语义ID枚举语义0NA无物理存储的 NULL 类型1BOOL布尔型单 bit、LSB 位打包2–9UINT8/INT8/UINT16/INT16/UINT32/INT32/UINT64/INT64有符号/无符号整数little-endian10–12HALF_FLOAT/FLOAT/DOUBLE2/4/8 字节浮点13–15STRING/BINARY/FIXED_SIZE_BINARYUTF8 变长串、变长字节、定长字节16–17DATE32/DATE64int32 天 / int64 毫秒自 UNIX 纪元18–20TIMESTAMP/TIME32/TIME64时间戳int64、时间int32/int6421–22INTERVAL_MONTHS/INTERVAL_DAY_TIME日历区间月天毫秒23–24DECIMAL128/DECIMAL256128/256 位定标十进制DECIMAL为DECIMAL128的向后兼容别名25–28LIST/STRUCT/SPARSE_UNION/DENSE_UNION嵌套类型29DICTIONARY字典编码categorical/factor30–32MAP/EXTENSION/FIXED_SIZE_LISTMap、用户自定义扩展、定长列表33DURATION经过时间秒/毫秒/微秒/纳秒34–37LARGE_STRING/LARGE_BINARY/LARGE_LIST/INTERVAL_MONTH_DAY_NANO64 位偏移的大类型及复合日历区间38RUN_END_ENCODEDRun-End 编码39–41STRING_VIEW/BINARY_VIEW/LIST_VIEWView 族类型内联前缀优化枚举末尾以MAX_ID收尾配套提供arrow::AllTypeIds()返回全部类型 ID 的向量。1.2 DataType所有数据类型的抽象基类arrow::DataType定义于 cpp/src/arrow/type.h#L127-L218。Arrow 中的数据类型都是逻辑类型它既可以是一个基本物理类型固定大小的字节或位也可以是由其他数据类型组成的嵌套类型还可以是以其他类型为物理载体的类型例如以 int64 编码的时间戳。文档中注明简单类型可由Type::typeID 完全描述而复杂类型通常是参数化的parametric。DataType 的核心接口成员id()返回类型类别Type::typestorage_id()返回存储类型的类别默认等于id()被扩展类型等覆盖Equals()判断两类型是否相等——注意逻辑上可互相转换的类型如ListUInt8与Binary不视为相等ToString()/name()前者含子字段的完整字符串表示后者仅类型名bit_width()/byte_width()仅对定宽类型有意义否则返回 -1layout()返回DataTypeLayout描述该类型预期的缓冲区布局实验性 APIfield(i)/fields()/num_fields()访问子字段Accept(TypeVisitor*)将类型分发给访问器Hash()计算哈希不含子字段元数据。DataTypeLayouttype.h#L93-L125通过BufferKindFIXED_WIDTH、VARIABLE_WIDTH、BITMAP、ALWAYS_NULL描述每个缓冲区的物理形态。例如布尔类型BooleanType的布局是两个位图有效位图 数据位图见 type.h#L603-L617普通定宽类型经CTypeImpl模板则是位图 固定宽度数据两段布局。没有顶层有效位图的类型包括NA、DENSE_UNION、SPARSE_UNION与RUN_END_ENCODED见 type.h#L2491-L2501 的may_have_validity_bitmap。二、类型工厂函数官方推荐的创建方式文档明确指出These functions are recommended for creating data types. They may return new objects or existing singletons, depending on the type requested.工厂函数是创建类型的推荐方式它们可能返回新对象也可能返回已存在的单例。这一组函数由\defgroup type-factories标记定义在 cpp/src/arrow/type_fwd.h#L459-L647。2.1 无参单例工厂以下工厂返回单例引用const std::shared_ptrDataType覆盖全部非参数化类型类别工厂函数空/布尔null()、boolean()有符号整数int8()、int16()、int32()、int64()无符号整数uint8()、uint16()、uint32()、uint64()浮点float16()半精度、float32()、float64()字符串utf8()、utf8_view()、large_utf8()二进制binary()、binary_view()、large_binary()日期date32()天数、date64()毫秒区间month_interval()、day_time_interval()、month_day_nano_interval()2.2 参数化类型工厂工厂函数参数说明fixed_size_binary(byte_width)定长二进制每值占用固定字节数decimal(precision, scale)按精度自动选择precision 38 返回Decimal256Type否则返回Decimal128Typedecimal128(precision, scale)/decimal256(precision, scale)显式指定具体十进制类型list(value_type)/list(value_field)变长列表int32 偏移等价于Listvalue_typelarge_list(...)64 位偏移的列表list_view(...)/large_list_view(...)列表视图offsetsize 表示map(key_type, item_type, keys_sorted)Map物理表示等同liststructkey, itemfixed_size_list(value_type, list_size)定长列表struct_(fields)结构体可接受FieldVector或(name, type)初始化列表timestamp(unit)/timestamp(unit, timezone)时间戳见下文时区语义time32(unit)/time64(unit)单位分别限SECOND/MILLI与MICRO/NANOduration(unit)经过时间run_end_encoded(run_end_type, value_type)Run-End 编码sparse_union(fields, type_codes)/dense_union(fields, type_codes)联合类型type_codes缺省为空dictionary(index_type, dict_type, ordered)字典编码index_type必须是整数典型用法示例#include arrow/api.h using namespace arrow; // 单例工厂无需释放类型全局共享 auto t_int32 int32(); auto t_str utf8(); // 参数化类型 auto t_ts timestamp(TimeUnit::NANO, Asia/Shanghai); // 带时区时间戳 auto t_dec decimal(20, 4); // precision38 → Decimal128 auto t_struct struct_({field(name, utf8()), field(age, int32())}); auto t_dict dictionary(int8(), utf8(), /*ordered*/true); // 字典编码2.3 Field 与 Schema 的工厂schema-factories文档中Fields and Schemas一节由\defgroup schema-factories承载type_fwd.h#L649-L720提供与类型工厂配套的元信息工厂field(name, type, nullabletrue, metadatanullptr)创建字段另有仅携带元数据的重载schema(fields, metadatanullptr)由FieldVector或(name, type)列表创建 schemaschema(fields, endianness, metadatanullptr)显式指定字节序Endianness::Little/Big/Native。三、具体类型子类详解文档按Primitive → Temporal → Binary-like → Nested → Dictionary-encoded → Extension六组展开全部具体类型子类。3.1 Primitive空值、布尔与数值类型NullTypetype.h#L582-L600Type::NAname()为null布局为单一的AlwaysNull缓冲即无物理存储。BooleanTypeType::BOOLname()为bool。注意它与 C 语言 bool 不同每值仅占 1 bitbit_width()重写为 1布局为两个位图。数值类型numeric-datatypes 组全部由模板detail::IntegerTypeImpl/detail::CTypeImpl生成type.h#L550-L577包括整数Int8Type…Int64Type与UInt8Type…UInt64TypeIntegerType提供is_signed()虚接口浮点HalfFloatType、FloatType、DoubleTypeFloatingPointType::Precision枚举HALF/SINGLE/DOUBLE数值类型继承链为PrimitiveCType → FixedWidthType → DataType均属于NumberType。十进制类型type.h#L1001-L1092Arrow 十进制是以定标整数编码的定点数。Decimal128Type(7, 3)可精确表示 1234.567 与 -1234.567内部编码为 128 位整数 1234567 与 -1234567但无法表示 12345.67。关键参数Decimal128Typeprecision 1–38kMaxPrecision16 字节kByteWidth16Decimal256Typeprecision 1–7632 字节仅在需要超过 38 位有效数字时使用更宽即更占空间、更慢。二者都提供校验式静态工厂Make(precision, scale)返回Result。3.2 Temporal日期、时间、时间戳与区间时间类别的核心是TimeUnit::type枚举type_fwd.h#L252-L258SECOND 0、MILLI 1、MICRO 2、NANO 3DateUnit枚举则为DAY 0、MILLI 1。具体类型Date32Typeint32 天Type::DATE32Date64Typeint64 毫秒Type::DATE64物理类型分别对应Int32Type/Int64Type。Time32Typeint32仅SECOND或MILLI单位Time64Typeint64仅MICRO或NANO单位。TimestampTypetype.h#L1632-L1694int64 自 UNIX 纪元的秒/毫秒/微秒/纳秒。时区语义是文档强调的重点时区字符串两种合法形式(i) IANA 数据库名称如Europe/Zurich(ii) 绝对偏移如-08:00UTC、Etc/UTC、00:00均表示原生 UTC。带非空时区 →timezone-aware列底层整型数组必须存UTC 归一化的值任意两列可直接比较无需再作偏移换算空时区 →timezone-naive列生产者可用任意时区填充消费者不得假设其与他列可比较naive 字段展示时不得做本地化而 aware 字段可本地化显示。DurationTypeint64 经过时间秒/毫秒/微秒/纳秒与日历无关。区间类型IntervalTypeMonthIntervalTypeint32 月数、DayTimeIntervalTypeDayMilliseconds{days, milliseconds}8 字节、MonthDayNanoIntervalTypeMonthDayNanos{months, days, nanoseconds}16 字节三字段相互独立。3.3 Binary-like字符串与二进制BinaryTypeType::BINARY变长字节int32 偏移offset_type int32_tStringType是其子类仅逻辑类型变为Type::STRINGUTF8。布局为位图 偏移数组 变长数据。LargeBinaryType/LargeStringType同上但偏移为int64容量更大。FixedSizeBinaryType定长构造时指定byte_width并提供校验式Make()。View 族BinaryViewType/StringViewTypetype.h#L783-L877每个值是一个 16 字节的 viewkSize16其中12 字节内联存储kInlineSize——≤12 字节的小值完全内联、零解引用访问且前 4 字节前缀kPrefixSize总是复制便于快速失败比较。该设计借鉴自慕尼黑工业大学 UmbraDB、Velox 与 DuckDB能显著减小短字符串的 CPU 缓存工作集。3.4 Nested列表、Map、结构体与联合全部嵌套类型继承NestedType同时是ParametricType通过children_持有子FieldListTypeint32 偏移/LargeListTypeint64 偏移可递归嵌套如list(list(int32))ListViewType/LargeListViewType以 offsetsize 双数组表示FixedSizeListType每行定长子元素数list_sizeMapTypetype.h#L1248-L1285物理表示等同liststructkey,item支持keys_sorted标记与key_type()/item_type()访问器可递归如map(utf8, map(utf8, int32))StructTypeFieldVector字段集合提供GetFieldByName/GetFieldIndex/AddField/RemoveField/SetField等操作SparseUnionType/DenseUnionType8 位type_codes表示逻辑子类型 ID最大 127。稀疏联合的每个子数组长度与联合数组一致稠密联合额外用 32 位偏移缓冲只编码被引用的值省空间但引入间接访问开销。两者都没有顶层有效位图RunEndEncodedType由 run-end 类型与值类型构成。3.5 DictionaryType字典编码DictionaryTypetype.h#L1852-L1888即其他语言中的categorical/factor类型索引由任意整数类型承担字典值类型 ordered布尔标记表达排序语义。构造函数DictionaryType(index_type, value_type, ordered)另有校验式Make(...)。注意字典本身不属于类型而是随ArrayData附带的数据部分。3.6 ExtensionType用户自定义扩展类型扩展类型机制cpp/src/arrow/extension_type.h#L39允许用户基于已有物理存储类型定义新的逻辑类型必须实现extension_name()唯一标识注册到ExtensionTypeRegistry时要求唯一通过storage_type()暴露物理存储类型storage_id()返回存储类型 IDMakeArray()负责把存储数据包装为扩展数组返回ExtensionArray子类实例存储类型的byte_width()/bit_width()会被透传。四、Fields、Schemas 与元数据4.1 Field字段名 类型 可空性 元数据Fieldtype.h#L356-L544描述嵌套类型或 Schema 中的单个构成元素。构造参数name、type、nullable默认 true、metadata默认空。成员能力访问器name()、type()、nullable()、metadata()、HasMetadata()不可变派生WithName()、WithType()、WithNullable()、WithMetadata()、WithMergedMetadata()、RemoveMetadata()合并MergeWith(other, options)要求同名且类型兼容MergeOptions控制是否允许类型提升如promote_nullability、promote_decimal、promote_integer_to_float、promote_numeric_width、promote_temporal_unit等十余项开关Defaults()仅合并 NullTypePermissive()除promote_dictionary_ordered外全开Equals(other, check_metadata)、IsCompatibleWith()、Flatten()、ToString(show_metadata)。4.2 Schema记录批/表的数据结构描述Schematype.h#L2255-L2357是Field对象序列描述 RecordBatch 或 Table 的各列。能力包括Equals()、num_fields()、field(i)、field_names()、GetFieldByName()/GetFieldIndex()返回 -1 表示未找到、GetAllFieldsByName()、字节序处理endianness()/is_native_endian()/WithEndianness()、元数据处理metadata()/WithMetadata()/RemoveMetadata()/HasMetadata()、字段增删改AddField/RemoveField/SetField/WithNames()、ToString(show_metadata)与HasDistinctFieldNames()。文档另列出SchemaBuildertype.h#L2371-L2467——用于增量构造/合并 schema通过ConflictPolicyCONFLICT_APPEND/IGNORE/REPLACE/MERGE/ERROR控制同名字段冲突策略并提供静态Merge与AreCompatible自由函数UnifySchemas()则按名字合并多个 schema。4.3 KeyValueMetadata任意键值元数据KeyValueMetadatacpp/src/arrow/util/key_value_metadata.h#L36-L84持有任意键值对非线程安全。提供Append、Get、Contains、Set、Delete、DeleteMany、FindKey、Merge、Copy、Equals、ToString与size()等操作并可通过key_value_metadata(pairs)工厂创建。Field::MergeWith保留本字段元数据而丢弃对方元数据的行为与之配合使用。4.4 字段查找助手FieldPath 与 FieldRef文档中Helpers for looking up fields一节含:undoc-members:专门介绍两种嵌套字段寻址手段FieldPathtype.h#L1908-L1972纯整数下标路径如{5, 9, 3}等价于schema-field(5)-type()-field(9)-type()-field(3)。非法路径越界或空路径会报错。Get()系列支持对Schema、Field、DataType、Array、RecordBatch、Table等多态取值GetFlattened()变体非零拷贝且会把子数组空位图与祖先做 AND 合并。FieldReftype.h#L2007-L2232可按名字或混合方式引用字段可从int下标、std::string名字、FieldPath及嵌套FieldRef隐式构造。典型示例摘自源码注释// schema({field(a, struct_({field(n, null())})), field(b, int32())}) FieldRef ref1(0, 0); // 下标路径 FieldRef ref2(a, 0); // 名字 下标 FieldRef ref3(a, n); // 纯名字路径 FieldRef ref4(0, n); ARROW_ASSIGN_OR_RAISE(FieldRef ref5, FieldRef::FromDotPath(.a[0])); // 点路径FromDotPath()支持.alpha、[2]、.beta[3]等语法特殊字符需\转义。FindAll()返回所有匹配的FieldPath名字可重复因此可能多匹配FindOne/GetOne/GetOneOrNone等便捷接口在无匹配或多匹配时给出明确错误配套GetAll/GetAllFlattened供批量取值。五、类型遍历工具TypeVisitor文档 Utilities 一节列出了arrow::TypeVisitorcpp/src/arrow/visitor.h#L83。这是对 DataType 实施双分派的标准手段为每个具体类型重载一个Visit(const XxxType)虚方法覆盖NullType、BooleanType、全部数值/字符串/时间/嵌套/字典/扩展类型。典型用法是定义子类按需重写部分Visit其余交给默认实现随后调用type-Accept(visitor)触发分派。同一文件中还定义了针对数组的ArrayVisitor二者常配套用于类型→数组的泛化处理。六、实践建议与常见误区优先使用工厂函数而非直接 new无参类型如int32()返回共享单例零分配开销参数化类型如timestamp(...)则由工厂负责校验与构造是文档明确推荐的入口。区分逻辑类型与物理类型timestamp(TimeUnit::NANO)的物理载体是 int64GetPhysicalType()可将逻辑类型映射到物理类型StringType物理上等价于BinaryType仅is_utf8语义不同。时区语义容易踩坑timezone-aware 列的值必须 UTC 归一化naive 列不可跨列直接比较时区字符串建议统一使用 IANA 名称或00:00。大小选择能用Decimal128就别用Decimal25616 vs 32 字节能用BinaryType32 位偏移上限约 2 GiB就别用LargeBinaryType后者每值多 4 字节偏移。字段寻址优先用FieldRef取代裸的field_index与field_name参数组合它天然支持嵌套、按名与点路径三种方式注意同名多字段场景需用FindAll/GetOne显式消歧。以上所有类型类、工厂与工具的完整声明分别位于 cpp/src/arrow/type.h、cpp/src/arrow/type_fwd.h、cpp/src/arrow/extension_type.h 与 cpp/src/arrow/visitor.h可结合 docs/source/cpp/api/datatype.rst 的 Doxygen 索引查阅每个成员的详细文档。赞分享数据工程大数据序列化数据分析【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow13/arrow点击查看免费下载相关推荐Apache Arrow C Data Types 完全指南DataType 类型系统、工厂函数与 Schema 元数据Apache Arrow C Data Types 完全指南DataType 类型系统、工厂函数与 Schema 元数据 本篇技术指南以 Data Typ数据工程数据分析大数据Apache Arrow pyarrow 数据类型与 Schema 体系全指南工厂函数、类型类与检查谓词详解Apache Arrow pyarrow 数据类型与 Schema 体系全指南工厂函数、类型类与检查谓词详解 本文以 docs/source/python/a数据工程大数据序列化数据分析Apache Arrow (PyArrow) 数据类型与 Schema API 全解工厂函数、类型类与类型检查谓词Apache Arrow PyArrow 数据类型与 Schema API 全解工厂函数、类型类与类型检查谓词 PyArrow 的 pyarrow 命名空间提大数据数据分析数据工程序列化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考