Apache Arrow C++ Compute 计算函数 API 完整指南:Datum、Function、Registry 与表达式体系

原创2026-10-13 21:11:121,451 阅读
文章标签:数据工程数据分析大数据

Apache Arrow C++ Compute 计算函数 API 完整指南:Datum、Function、Registry 与表达式体系

本文围绕 Apache Arrow C++ 源码仓库中的 Compute Functions API 索引文档 展开,系统讲解 Arrow C++ 计算内核(compute)模块的公开编程接口:从统一数据载体 Datum,到抽象函数类 Function、函数执行器与执行上下文,再到集中注册与查询函数的 FunctionRegistry、一行调用的便捷函数 CallFunction,最后落点于声明式计算表达式 Expression 及其优化 pass。读完本文,你将掌握如何在 C++ 中直接调用 Arrow 内置的标量、向量、聚合与哈希聚合函数,理解内核(kernel)分发(dispatch)与执行的底层机制,并能基于 Expression 构建可绑定、可优化、可序列化的列式计算管线。文中所涉 API 目前标注为 EXPERIMENTAL,可能不经弃用周期直接变更,生产使用时请留意版本演进。

Datum:计算函数的统一数据载体

Arrow 的计算函数需要同时接受标量、数组、分块数组、RecordBatch 与 Table 等多种输入形态。为此,arrow::Datum 被设计为一个变体类型(variant type),其完整定义位于 cpp/src/arrow/datum.h。

Kind 枚举与内部存储

Datum 用 Kind 枚举标识当前存储的数据形态,共六种:

enum Kind { NONE, SCALAR, ARRAY, CHUNKED_ARRAY, RECORD_BATCH, TABLE };

内部通过 std::variant 分别持有 Scalar、ArrayData(注意:数组以 ArrayData 而非 Array 存储,以简化后续处理)、ChunkedArray、RecordBatch 与 Table 的 shared_ptr。kUnknownLength = -1 表示当前变体没有长度概念。

丰富的构造方式

Datum 提供了大量便捷构造:

  • 从 Array、Scalar 及其具体子类型构造:对 Array 与 Scalar 的具体子类(如 Int64Array、StringScalar)提供模板化隐式转换构造;
  • 从 ChunkedArray、RecordBatch、Table 构造:优先使用 shared_ptr 版本,按值构造版本(如 explicit Datum(const ChunkedArray&))在源码注释中被明确提示“可能开销较大”;
  • 从原生 C++ 值构造标量:bool、int8_t…uint64_t、float、double、std::string、const char*,以及基于 std::chrono::duration 的 DurationScalar,覆盖了最常见的标量字面量场景。
Datum d1 = Int64Array::FromSequence(...);  // 从数组构造
Datum d2 = 42;                             // 从 int32 字面量构造标量
Datum d3 = std::string("hello");           // 从字符串构造标量

查询与取值访问器

Datum 提供了 kind()、is_array()、is_chunked_array()、is_arraylike()、is_scalar()、is_value() 等谓词,以及 array()、chunked_array()、record_batch()、table()、scalar()、make_array() 等强类型取值方法;对已知具体类型还可使用 array_as<ExactType>() 与 scalar_as<ExactType>() 完成 checked cast。此外还提供 type()、schema()、length()、null_count()、chunks()、TotalBufferSize() 等通用元信息查询,以及 Equals/ToString 便于调试。注意:以错误类型访问时会抛出 std::bad_variant_access。

抽象函数类:Function 体系

“函数”在 Arrow compute 中是一个特定运算的抽象,同一运算针对不同输入类型组合可有多种实现,每种实现称为一个内核(kernel)。抽象函数类的完整定义位于 cpp/src/arrow/compute/function.h,其术语约定在 cpp/src/arrow/compute/README.md 中有系统说明。

Arity:函数的元数

Arity 描述函数所需的参数个数,提供四个工厂方法与一个可变参数工厂:

Arity::Nullary()      // 0 个参数
Arity::Unary()        // 1 个参数
Arity::Binary()       // 2 个参数
Arity::Ternary()      // 3 个参数
Arity::VarArgs(min)   // 可变参数,min 为最少参数个数

FunctionDoc:函数文档元数据

FunctionDoc 记录函数的一行摘要(summary)、详细描述(description)、参数符号名(arg_names)、关联选项类名(options_class)以及选项是否必填(options_required)。这些元数据不仅服务于 Doxygen 文档生成,也可被其他语言绑定(如 Python/Ruby)用来生成更友好的函数签名。

Function::Kind:函数的五大类别

Function::Kind 枚举定义了函数适用场景的分类,从源码注释可以直接提炼出语义:

Kind 语义 典型代表
SCALAR 对整列数据做元素级(elementwise)标量运算,输出长度与输入相同,Array 与 Scalar 可混合(广播);对应 SQL 表达式中的函数 算术、比较、字符串处理
VECTOR 数组输入、数组输出,但结果依赖整列内容,输出长度可能不同;通常不适用于 SQL 语义 排序、去重、过滤、take
SCALAR_AGGREGATE 从数组输入计算标量汇总统计 sum、mean、min_max
HASH_AGGREGATE 结合分组标识数组计算分组汇总统计 hash_sum、hash_count
META 本身不含内核,分发到其他函数执行 cast 等元函数

Function 的核心接口

Function 基类暴露以下关键方法:

  • name():函数名,注册表强制全局唯一;
  • kind():返回上述函数类别;
  • arity():返回参数个数约束;
  • doc():返回函数文档;
  • num_kernels():当前注册的内核数量;
  • DispatchExact(types):仅凭精确参数类型(不做隐式类型转换)查找内核;
  • DispatchBest(values):允许隐式转换后返回最匹配内核,并可在 values 中标记“仅近似匹配”,由调用方负责按需 cast;
  • GetBestExecutor(inputs):一次性获取绑定好最佳内核的执行器;
  • Execute(args, options, ctx):一站式执行——完成内核分发、批迭代与内存分配;
  • default_options():保证可合法传给 Execute 的默认选项;
  • is_pure():纯函数判定。不纯函数(如随机数生成)对相同输入可能返回不同结果,因此含纯函数调用的表达式可被常量折叠优化。

五种具体函数子类

在 function.h 中,detail::FunctionImpl 模板承载内核集合,派生出的具体类包括:

  • ScalarFunction:元素级函数,AddKernel 默认支持固定宽度类型预分配、默认空值处理(取输入有效性位图交集);
  • VectorFunction:整列依赖型函数,AddKernel 不做数据预分配与有效性位图预分配;
  • ScalarAggregateFunction:标量聚合函数;
  • HashAggregateFunction:哈希分组聚合函数;
  • MetaFunction:元函数,必须实现 ExecuteImpl,对 Array/ChunkedArray/Scalar 输入可依赖具体函数执行,但需自行处理其他 Datum 类型;num_kernels() 恒为 0。

函数执行:FunctionExecutor 与 ExecContext

FunctionExecutor:预配置内核的执行器

当同一函数需要在不同输入类型上重复执行(例如在数据集扫描循环内)时,每次都重新做内核分发显然浪费。FunctionExecutor(function.h)正是为复用而生的抽象:

  • Init(options, exec_ctx):初始化或重新初始化预配置内核,可被调用零次或多次;
  • Execute(args, length):以必须能转换为预配置类型的参数执行;length 为 -1 时按参数推断批长度,标量函数的长度必须与参数批推断长度一致,向量函数忽略该参数。

ExecContext:共享执行配置

ExecContext(cpp/src/arrow/compute/exec.h)聚合了一次计算调用所需的共享配置:

  • memory_pool():内存池,默认 default_memory_pool();
  • func_registry():函数注册表,默认指向 GetFunctionRegistry() 提供的全局注册表;
  • executor():可并行化执行的内部 Executor;
  • set_exec_chunksize(n):内核执行的最大工作单元长度。超过该长度的连续数组输入会被切分为更小的 chunk;默认 INT64_MAX,即不切分;
  • set_preallocate_contiguous(bool):chunked 执行时是否采用连续大块预分配(默认 true);
  • set_use_threads(bool):多线程开关(当前尚未实际使用)。

ExecBatch:内核执行的工作单元

ExecBatch(exec.h)在语义上类似 RecordBatch,但常量“列”用 Scalar 表示而无需展开为重复数组。它持有 values(位置参数 Datum 列表)、可选的 selection_vector(未物化的过滤索引,例如过滤 [true, true, false, true] 表示为 [0, 1, 3])、guarantee(对该批所有行恒为真的谓词表达式,默认 literal(true))与语义长度。可用 ExecBatch::Make 做带长度校验的构造,或 ToRecordBatch 转回物化结果。

内核执行的底层要素

更深一层,内核签名与执行策略定义在 cpp/src/arrow/compute/kernel.h:

  • KernelSignature(L356):由输入类型列表、输出类型与 is_varargs 构成,out_type() 需要 Resolve 才能得到依赖输入的具体输出类型;
  • KernelContext(L59):为内核提供 Allocate/AllocateBitmap 内存分配、SetState 内核态注入与 memory_pool() 访问;
  • SimdLevel(L411):同一类型组合可有不同 SIMD 级别(SSE4_2/AVX/AVX2/AVX512/NEON)的内核变体,按系统 CPU 信息或用户偏好选择——仓库中 scalar_arithmetic_benchmark.cc、aggregate_basic_avx2.cc 等即为 SIMD 化实现的证据;
  • NullHandling(L417):输出有效性位图策略,包括对输入位图取交集的 INTERSECTION、由内核写入的 COMPUTED_PREALLOCATE/COMPUTED_NO_PREALLOCATE、以及输出永不为空的 OUTPUT_NOT_NULL;
  • MemAllocation(L444):固定宽度输出的内存预分配偏好(PREALLOCATE/NO_PREALLOCATE)。

函数注册表:FunctionRegistry 与 GetFunctionRegistry

FunctionRegistry(cpp/src/arrow/compute/registry.h)是内置函数与用户自定义函数的集中注册中心,负责维护“函数名 → Function → 内核集合”的映射。

核心操作

auto registry = arrow::compute::FunctionRegistry::Make();          // 新建注册表
registry->AddFunction(my_function, /*allow_overwrite=*/false);      // 注册函数
registry->AddAlias("my_alias", "my_function");                     // 注册别名
auto func = registry->GetFunction("add");                          // 按名查询
auto names = registry->GetFunctionNames();                         // 列出全部函数名
int n = registry->num_functions();                                  // 函数总数
const Function* cast = registry->cast_function();                   // 获取 cast 函数对象

相关约束与机制:

  • 函数名全局唯一,重复注册返回 Status::KeyError;CanAddFunction 用于注册前预检;
  • 支持为既有函数添加别名(CanAddAlias/AddAlias);
  • 除函数外还可注册 FunctionOptionsType(选项类型描述器,见下文);
  • 通过 Make(FunctionRegistry* parent) 可构建带父注册表的嵌套注册表,且其父引用一旦设定不会变更,即便允许覆盖时也是如此;
  • GetFunctionRegistry() 是获取库级全局注册表的便捷入口,ExecContext 默认即使用它。

注册中心与内核分发的配合

从 exec.cc 的实现可以看到,CallFunction 的典型执行路径是:按名在注册表(来自 ExecContext)中查找 Function → 依据输入 Datum 类型做 DispatchBest 内核选择 → 必要时插入隐式类型转换 → 迭代 ChunkedArray 输入并执行 → 包装输出。这与 registry.h 注释中“先查找函数,再用 Function::Execute 急切执行或使用 dispatch 方法做底层执行”的描述完全一致。

便捷函数:CallFunction 与 GetFunctionExecutor

CallFunction:一站式调用

CallFunction 位于 exec.h 的 compute-call-function 组,是一站式调用器,自动完成内核分发、参数校验、ChunkedArray 迭代与输出包装,提供四个重载:

// 形式一:按 Datum 参数列表调用,可传选项与上下文
Result<Datum> CallFunction(const std::string& func_name,
                           const std::vector<Datum>& args,
                           const FunctionOptions* options,
                           ExecContext* ctx = NULLPTR);

// 形式二:使用函数默认选项
Result<Datum> CallFunction(const std::string& func_name,
                           const std::vector<Datum>& args,
                           ExecContext* ctx = NULLPTR);

// 形式三、四:以 ExecBatch 为输入的对应版本
Result<Datum> CallFunction(const std::string& func_name, const ExecBatch& batch,
                           const FunctionOptions* options, ExecContext* ctx = NULLPTR);
Result<Datum> CallFunction(const std::string& func_name, const ExecBatch& batch,
                           ExecContext* ctx = NULLPTR);

注意:部分函数必须显式提供 FunctionOptions(例如涉及选项类的函数),此时使用默认选项的重载会报错。

using namespace arrow;
auto left = Datum(Int64Array::FromSequence(...));   // 左操作数数组
auto right = Datum(3);                              // 右操作数标量,参与广播
ARROW_ASSIGN_OR_RAISE(Datum result,
                      compute::CallFunction("add", {left, right}));

GetFunctionExecutor:可复用执行器

exec.h 的 compute-function-executor 组提供 GetFunctionExecutor,一次调用同时完成“创建 + 初始化”适合给定函数名、输入类型与选项的 FunctionExecutor,便于在热点路径上反复执行。其两个重载分别接受 std::vector<TypeHolder> 与 std::vector<Datum>(后者从 Datum 推导输入类型),并可指定 FunctionRegistry(默认全局注册表)。

类型安全的命名便捷函数

除通用 CallFunction 外,cpp/src/arrow/compute/api_scalar.h 还以具名函数形式暴露了高频标量运算的 C++ 便捷封装,例如:

Result<Datum> Add(const Datum& left, const Datum& right,
                  ArithmeticOptions options = ArithmeticOptions(),
                  ExecContext* ctx = NULLPTR);
Result<Datum> Subtract(const Datum& left, const Datum& right, /*...*/);
Result<Datum> Multiply(const Datum& left, const Datum& right, /*...*/);
Result<Datum> Divide(const Datum& left, const Datum& right, /*...*/);

其语义在注释中明确:数组参与运算时要求等长;任一侧为 null 则结果为 null(遵循 NullHandling::INTERSECTION 语义);Divide 对整数类型还有除零行为约定。api_scalar.h 同时集中声明了 DayOfWeek、Strftime、Strptime、AssumeTimezone、YearsBetween 等时间日期类函数,api_vector.h 与 api_aggregate.h 则分别对应向量与聚合类函数,统一通过 api.h 聚合导出。

具体选项类:函数行为的细粒度控制

FunctionOptions 基类与扩展点

function_options.h 定义了 FunctionOptions 基类及其类型描述器 FunctionOptionsType。每个选项类都有注册的 type_name(),并支持 Equals、ToString、Copy、Serialize/Deserialize(序列化仅按 type_name 在默认注册表中查找;自定义注册表需自行 GetFunctionOptionsType 后调用其 Deserialize)。

常用选项类速览

以 api_scalar.h 为例:

  • ArithmeticOptions:唯一成员 check_overflow(默认 false)。置为 true 时,Add/Subtract/Multiply/Divide 等算术运算检测溢出并报错,而不是静默回绕;
  • ElementWiseAggregateOptions:成员 skip_nulls(默认 true),控制元素级聚合(如 add 的多参数聚合变体)是否跳过 null;
  • RoundOptions:ndigits(默认 0,舍入精度)与 round_mode(默认 RoundMode::HALF_TO_EVEN),用于 round 函数族;
  • RoundBinaryOptions:仅含 round_mode(默认 HALF_TO_EVEN),用于 round_binary 函数族。

RoundMode 十种舍入模式

RoundMode 枚举完整刻画了舍入与平局(tie)处理规则,语义可直接对照源码注释:

模式 语义
DOWN 向数值更小方向取整(floor)
UP 向数值更大方向取整(ceil)
TOWARDS_ZERO 截断小数部分(trunc)
TOWARDS_INFINITY 负数按 DOWN、正数按 UP,即远离零
HALF_DOWN 平局向负无穷方向(round half towards negative infinity)
HALF_UP 平局向正无穷方向
HALF_TOWARDS_ZERO 平局向零方向
HALF_TOWARDS_INFINITY 平局远离零方向
HALF_TO_EVEN 平局取最近偶数(银行家舍入)
HALF_TO_ODD 平局取最近奇数

对应的时间舍入选项 RoundTemporalOptions(multiple、unit、week_starts_monday 等)与 CalendarUnit 枚举(NANOSECOND…YEAR)也定义于同一文件,供 floor_temporal、ceil_temporal、round_temporal 使用。

计算表达式:Expression 的声明式编程

当需要在多列、多批数据上组合多个函数并复用同一套计算逻辑时,直接逐批 CallFunction 会显得繁琐。Arrow compute 提供了声明式表达式体系,定义于 cpp/src/arrow/compute/expression.h。

Expression 的三种形态

一个未绑定(unbound)的 Expression 将单个 Datum 映射为另一个 Datum,具体是以下三者之一:

  1. 字面量(literal):一个 Datum;
  2. 字段引用(field reference):对输入 Datum 中某个(可能嵌套的)字段的引用;
  3. 函数调用(call):调用某个计算函数,其参数由其他 Expression 提供。

Expression::Call 结构体记录了 function_name、arguments、options,以及绑定(Bind)之后的后置属性:解析出的 function、选中的 kernel、kernel_state 与结果类型 type。

表达式工厂

compute::Expression lit = compute::literal(42);              // 字面量
compute::Expression ref = compute::field_ref("amount");      // 字段引用
compute::Expression e = compute::call("add",                 // 函数调用
    {compute::field_ref("amount"), compute::literal(1)});

expression.h 提供的 literal/field_ref/call 工厂支持从任意可转 Datum 的值构造字面量,call 既可直接接受 shared_ptr<FunctionOptions>,也可接受任意 FunctionOptions 子类值(自动包装为 shared_ptr)。

Bind:把表达式绑定到具体输入

Expression::Bind(const TypeHolder&) / Bind(const Schema&) 将表达式绑定到给定输入类型:查找内核、推导字段类型、插入隐式类型转换、执行部分简化,并初始化执行所需状态。IsBound() 可判断表达式是否已绑定,IsScalarExpression() 判断是否仅由标量字面量、字段引用与 ScalarFunction 调用构成,IsNullLiteral()、IsSatisfiable() 则服务于谓词下推等场景。

便捷构造组(expression-convenience)

expression.h 提供了语义化的便捷构造,让表达式读起来更接近 SQL 谓词:

compute::equal(field_ref("a"), literal(10));
compute::greater_equal(field_ref("b"), literal(0));
compute::and_(equal(field_ref("a"), literal(1)),
              compute::is_valid(field_ref("b")));
compute::or_({less(field_ref("x"), literal(0)),
              greater(field_ref("x"), literal(100))});
compute::not_(is_null(field_ref("y"), /*nan_is_null=*/true));
compute::project({...}, {"new_col1", "new_col2"});

其中 is_null 的 nan_is_null 参数控制 NaN 是否视为 null,project 用于投影出新列。

优化与改写 pass(expression-passes)

expression.h 定义了作用于已绑定表达式的变换管线:

  • Canonicalize:弱规范化,为后续 pass 建立保证(guarantee);
  • FoldConstants:基于字面量参数做常量折叠(如 add(null, x) 恒为 null,直接替换为 null 字面量),并提前求值所有参数全为字面量的调用;
  • ReplaceFieldsWithKnownValues:用已知字段值替换引用;
  • SimplifyWithGuarantee(expr, guaranteed_true_predicate):基于“恒为真”的谓词化简,例如删除过滤表达式中冗余的函数调用、把常量值字段的引用替换为字面量;
  • RemoveNamedRefs:将命名字段引用(如 "x" 或 "x.y")统一替换为字段路径(如 [0]、[1,3]),便于规范化处理。

配合 expression.h 的执行与序列化接口,可完成完整的“构建 → 绑定 → 优化 → 执行”闭环:

// 从 RecordBatch 构造 ExecBatch(缺失/乱序列自动补 null 标量)
ARROW_ASSIGN_OR_RAISE(auto batch,
    compute::MakeExecBatch(schema, Datum(record_batch)));
// 执行已绑定标量表达式
ARROW_ASSIGN_OR_RAISE(Datum result,
    compute::ExecuteScalarExpression(bound_expr, batch, ctx));
// 跨进程/跨语言传递时序列化
ARROW_ASSIGN_OR_RAISE(auto buf, compute::Serialize(expr));

小结与进阶路径

Apache Arrow C++ 的 compute 模块提供了一套完整的“数据 → Datum → Function/Kernel → Registry → 执行 → 表达式”分层 API:Datum 统一承载六种数据形态;Function 以 Arity、FunctionDoc 与五种 Kind 描述运算语义;KernelSignature、NullHandling、MemAllocation 等内核要素在底层决定执行策略;FunctionRegistry 集中管理函数、别名与选项类型;CallFunction/GetFunctionExecutor 提供一次性与可复用的调用入口;Expression 则把这一切提升到声明式层面,配合 Bind、FoldConstants、SimplifyWithGuarantee 等 pass 实现可优化的列式计算。

如需继续深入,可直接阅读仓库中的以下资源:

登录后查看全文
arrow