计算函数

通用计算 API

API 函数和函数注册表 

函数表示对可能具有不同类型的输入进行计算操作。在内部，一个函数由一个或多个“核”实现，具体取决于具体的输入类型（例如，一个将两个输入的值相加的函数，根据输入是否是整数或浮点数，可以有不同的核）。

函数存储在全局的 FunctionRegistry 中，可以通过名称查找。

输入形状 

计算输入表示为通用的 Datum 类，它是几种数据形状（如 Scalar、Array 和 ChunkedArray）的标记联合体。许多计算函数支持数组（分块或非分块）和标量输入，但有些会要求特定的输入类型。例如，array_sort_indices 需要其第一个且唯一的输入是数组，而通用的 sort_indices 函数则接受数组、分块数组、记录批处理或表格作为输入。

调用函数 

可以通过名称调用计算函数，使用 arrow::compute::CallFunction()：

std::shared_ptr<arrow::Array> numbers_array = ...;
std::shared_ptr<arrow::Scalar> increment = ...;
arrow::Datum incremented_datum;

ARROW_ASSIGN_OR_RAISE(incremented_datum,
                      arrow::compute::CallFunction("add", {numbers_array, increment}));
std::shared_ptr<Array> incremented_array = std::move(incremented_datum).make_array();

（请注意，此示例使用从 std::shared_ptr<Array> 到 Datum 的隐式转换）

许多计算函数也可以直接使用具体的 API，例如 arrow::compute::Add()：

std::shared_ptr<arrow::Array> numbers_array = ...;
std::shared_ptr<arrow::Scalar> increment = ...;
arrow::Datum incremented_datum;

ARROW_ASSIGN_OR_RAISE(incremented_datum,
                      arrow::compute::Add(numbers_array, increment));
std::shared_ptr<Array> incremented_array = std::move(incremented_datum).make_array();

一些函数接受或要求确定函数的精确语义的选项结构：

ScalarAggregateOptions scalar_aggregate_options;
scalar_aggregate_options.skip_nulls = false;

std::shared_ptr<arrow::Array> array = ...;
arrow::Datum min_max;

ARROW_ASSIGN_OR_RAISE(min_max,
                      arrow::compute::CallFunction("min_max", {array},
                                                   &scalar_aggregate_options));

// 解包结构标量结果（一个两字段的 {"min", "max"} 结构标量）
std::shared_ptr<arrow::Scalar> min_value, max_value;
min_value = min_max.scalar_as<arrow::StructScalar>().value[0];
max_value = min_max.scalar_as<arrow::StructScalar>().value[1];

然而，分组聚合不能通过 CallFunction 调用。另请参阅 计算 API 参考

隐式转换 

如果核不精确匹配参数类型，函数可能需要在执行之前将其参数转换。例如，核不直接支持字典编码数组的比较，但可以进行隐式转换，允许与解码数组进行比较。

每个函数可以根据需要定义隐式转换行为。例如，比较和算术核要求参数类型完全相同，并通过将其参数提升为可以容纳来自任一输入的任何值的数字类型来支持不同的数值类型。

常见的数字类型 

一组输入数字类型的常见数字类型是可以容纳任何输入的最小数字类型。如果输入中包含浮点类型，那么常见数字类型将是输入中的最宽浮点类型。否则，常见数字类型是整数，如果输入中有任何带符号的输入，则为带符号整数。例如：

特别需要注意，如果将 uint64 列与 int16 列进行比较，如果其中一个 uint64 值不能表示为公共类型 int64（例如，2 ** 63），则可能会引发错误。

可用函数 

类型类别 

为了避免详细列出支持的类型，下面的表格使用了一些通用的类型类别：

• “数值”：整数类型（Int8、等）和浮点类型（Float32、Float64、有时也是 Float16）。一些函数还接受 Decimal128 和 Decimal256 输入。

• “时间”：日期类型（Date32、Date64）、时间类型（Time32、Time64）、时间戳（Timestamp）、持续时间（Duration）、时间区间（Interval）。

• “二进制类似”：Binary、LargeBinary，有时也是 FixedSizeBinary。

• “字符串类似”：String、LargeString。

• “列表类似”：List、LargeList，有时也是 FixedSizeList。

• “嵌套”：列表类似（包括 FixedSizeList）、Struct、Union，以及 Map 等相关类型。

如果不确定函数是否支持具体的输入类型，建议尝试。不支持的输入类型会返回 TypeError 状态。

聚合 

标量聚合操作对（分块的）数组或标量值进行操作，并将输入减少到单个输出值。

• (1) 如果考虑了空值，通过将 ScalarAggregateOptions 参数 skip_nulls = false 设置为 false，那么将应用 Kleene 逻辑逻辑。不考虑 min_count 选项。

• (2) CountMode 控制计算时是否仅计算非空值（默认值），仅计算空值，还是计算所有值。

• (3) 如果未找到值，则返回 -1。无论输入中是否包含空值，空值的索引始终为 -1。

• (4) 对于十进制输入，生成的十进制值将具有相同的精度和标度。结果向零四舍五入。

• (5) 输出是一个 {"min": 输入类型, "max": 输入类型} 结构标量。

• （6）输出是一个数组，包含输入中按降序排列的 N 个最常见元素，其中 N 在 ModeOptions::n 中给定。如果两个值具有相同的计数，较小的值将首先出现。注意，如果输入具有少于 N 个不同的值，输出可能少于 N 个。

• （7）输出是 Int64、UInt64、Float64 或 Decimal128/256，具体取决于输入类型。

• （8）输出是 Float64 或输入类型，具体取决于 QuantileOptions。

• (9) 十进制参数首先转换为 Float64。

• (10) TDigest/t-digest 计算近似分位数，因此只需要固定数量的内存。有关详细信息，请参阅参考实现。

• (11) 结果基于输入数据的排序。

分组聚合（“group by”） 

分组聚合不能直接调用，但作为 SQL 风格的“group by”操作的一部分使用。与标量聚合一样，分组聚合将输入值基于某些“键”列的一组分组，然后分别聚合每个组，并发出每个输入组的一个输出值。

例如，对于以下表：

我们可以计算列 x 的总和，根据列键分组。这给了我们三个组，以下是结果。请注意，null 被视为一个不同的键值。

支持的聚合函数如下。所有函数名称都以 hash_ 为前缀，以区分它们与上面的标量等效函数，反映了它们在内部是如何实现的。

• (1) 如果考虑了空值，通过将 ScalarAggregateOptions 参数 skip_nulls = false 设置为 false，那么将应用 Kleene 逻辑逻辑。不考虑 min_count 选项。

• (2) CountMode 控制计算时是否仅计算非空值（默认值），仅计算空值，还是计算所有值。对于 hash_distinct，它更改的是 null 值是否被生成。这不会影响分组键，只会影响分组值（即可能会获得具有键为空的分组）。

• (3) hash_distinct 和 hash_list 将分组的值收集到一个列表数组中。

• (4) 对于十进制输入，生成的十进制值将具有相同的精度和标度。结果向零四舍五入。

• (5) 输出是一个 {"min": 输入类型, "max": 输入类型} 结构标量数组。

• (6) hash_one 返回每个组的一个任意值。该函数偏向于非空值：如果某个组至少有一个非空值，则返回该值，只有当该组的所有值都为空时，该函数才会返回空值。

• (7) 输出是 Int64、UInt64、Float64 或 Decimal128/256，具体取决于输入类型。

• (8) Decimal 参数首先转换为 Float64。

• (9) T-digest 计算近似分位数，因此只需要固定数量的内存。有关详细信息，请参阅参考实现。

• (10) 结果基于输入数据的排序。

元素级（“标量”）函数 

所有元素级函数都接受数组和标量作为输入。一元函数的语义如下：

• 标量输入产生标量输出

• 数组输入产生数组输出

二进制函数具有以下语义（在其他系统（如 NumPy）中有时称为“广播”）：

• （标量，标量）输入产生标量输出

• （数组，数组）输入产生数组输出（并且两个输入必须具有相同的长度）

• （标量，数组）和（数组，标量）产生数组输出。将标量输入处理为与另一个输入具有相同长度 N 的数组，其中相同的值重复 N 次。

算术函数 

这些函数期望数值类型的输入，并将给定的算术操作应用于从输入（s）中获取的每个元素。如果输入元素中有任何一个为空，相应的输出元素也为空。对于二进制函数，在应用操作之前，输入将被转换为公共数值类型（如果适用，还会解码字典）。

这些函数的默认变体不会检测溢出（结果通常会环绕）。大多数函数也有一个检查溢出的变体，后缀为 _checked，当检测到溢出时返回无效状态。

对于支持十进制输入的函数（目前为 add、subtract、multiply 和 divide 以及它们的检查变体），将适当提升不同精度/标度的十进制。混合十进制和浮点参数将将所有参数都转换为浮点数，而混合十进制和整数参数将将所有参数都转换为十进制。混合时间分辨率时间输入将转换为最细的输入分辨率。

(1) 计算 DECIMAL 结果的精度和标度

与 Redshift 的十进制升级规则兼容。在加法、减法和乘法操作中，保留所有十进制数字。除法的结果精度至少等于两个操作数的精度之和，同时保留足够的标度。如果结果精度超出十进制值范围，则会返回错误。

(2) 非零输入的输出为 -1 或 1，零输入的输出为 0。NaN 值返回 NaN。整数和十进制值返回 Int8 的带符号性，浮点值返回与输入相同类型的带符号性。

位操作函数:

(1) 如果位移量（即第二个输入）超出了数据类型的范围，将会引发错误。但是，当对第一个输入进行位移时发生溢出时，不会引发错误，多余的位将被静默丢弃。

舍入函数 

舍入函数将数值输入转换为基于舍入准则的近似值，采用更简单的表示形式。

• (1) 对于整数输入，输出值为64位浮点数，对于浮点数和小数输入，保留相同的类型。默认情况下，舍入函数将值舍入到最接近的整数，使用HALF_TO_EVEN解决平局情况。可以使用选项来控制舍入准则。round和round_to_multiple都具有round_mode选项，用于设置舍入模式。

• (2) 舍入到指定的数字位数，其中RoundOptions的ndigits选项指定以数字位数为单位的舍入精度。负值对应于非小数部分的位数。例如，-2表示四舍五入到最接近的100的倍数（将十位和个位数设置为零）。ndigits的默认值为0，它将四舍五入到最接近的整数。

• (3) 舍入到倍数，其中RoundToMultipleOptions的multiple选项指定舍入的比例。舍入倍数必须是正值。例如，100对应于舍入到最接近的100的倍数（将十位和个位数设置为零）。multiple的默认值为1，它将四舍五入到最接近的整数。

对于round和round_to_multiple，提供以下舍入模式。带HALF前缀的模式用于解决平局情况，将非平局情况四舍五入到最接近的整数。以下是默认的ndigits和multiple值的示例。

下表给出了ndigits（用于round函数）和multiple（用于round_to_multiple函数）分别如何影响操作的示例。

对数函数 

对数函数也得到支持，并提供了_checked变体，以检查是否需要域错误。

十进制值是被接受的，但首先被转换为Float64。

三角函数 

三角函数也得到支持，还提供了需要时检查域错误的_checked变体。

十进制值会被接受，但首先被转换为Float64。

比较 

这些函数期望两个数值类型的输入（在这种情况下，它们将在比较之前被强制转换为通用的数值类型），或者两个二进制或类字符串的输入，或两个时间类型的输入。如果任何输入被字典编码，它将被扩展以进行比较。如果一对输入元素中有任何一个是null，相应的输出元素也将是null。十进制参数将按照加法和减法的方式进行提升。

这些函数接受任意数量的数值类型的输入（在这种情况下，它们将在比较之前被强制转换为通用的数值类型）或时间类型的输入。如果任何输入被字典编码，它将被扩展以进行比较。

(1) 默认情况下，null 值会被跳过（但可以配置内核来传播 null 值）。对于浮点数值，NaN 会覆盖 null 值，但不会覆盖其他任何值。对于二进制和类字符串的值，仅支持相同类型参数的比较。

• （1）仅将TrimOptions::characters中指定的字符删除。输入字符串和字符参数都解释为ASCII字符。

• （2）仅删除ASCII空白字符（'\t'、'\n'、'\v'、'\f'、'\r'和' '）。

• （3）仅将TrimOptions::characters中指定的字符删除。

• （4）仅删除Unicode空白字符。