计算函数

通用计算 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));

// Unpack struct scalar result (a two-field {"min", "max"} scalar)
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 参考

隐式转换

如果内核与参数类型不完全匹配，则函数可能需要在执行之前转换其参数。 例如，任何内核都不直接支持字典编码数组的比较，但是可以进行隐式转换，从而可以与解码后的数组进行比较。

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

公共数值类型

一组输入数值类型的公共数值类型是可以容纳任何输入类型的任何值的最小数值类型。 如果任何输入是浮点类型，则公共数值类型是输入中最宽的浮点类型。 否则，公共数值类型是整数，如果任何输入都是有符号的，则为有符号的。 例如

输入类型	公共数值类型	注释
int32, int32	int32
int16, int32	int32	最大宽度为 32，将 LHS 提升为 int32
uint16, int32	int32	一个输入有符号，覆盖无符号
uint32, int32	int64	加宽以适应 uint32 的范围
uint16, uint32	uint32	所有输入均为无符号，保持无符号
int16, uint32	int64
uint64, int16	int64	int64 无法容纳所有 uint64 值
float32, int32	float32	将 RHS 提升为 float32
float32, float64	float64
float32, int64	float32	int64 更宽，仍然提升为 float32

特别要注意的是，如果 uint64 列中的某个值不能表示为公共类型 int64 (例如，2 ** 63)，则将 uint64 列与 int16 列进行比较可能会发出错误。

可用函数

类型类别

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

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

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

• “类似二进制”：二进制、大二进制，有时也是固定大小二进制。

• “类似字符串”：字符串、大字符串。

• “类似列表”：列表、大列表、列表视图、大列表视图，有时也是固定大小列表。

• “嵌套”：类似列表（包括固定大小列表）、结构体、联合，以及相关类型（如映射）。

如果您不确定函数是否支持具体的输入类型，我们建议您尝试一下。 不支持的输入类型会返回 TypeError Status。

聚合

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

• (1) 如果通过设置 ScalarAggregateOptions 参数 skip_nulls = false 来考虑空值，则应用 Kleene 逻辑。 不遵守 min_count 选项。

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

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

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

• (5) 对于十进制输入，生成的十进制将具有相同的精度和刻度。 结果四舍五入远离零。

• (6) 输出是 {"min": input type, "max": input type} 结构体。

  在间隔类型中，仅支持月份间隔，因为日期时间和月份日期时间纳米类型不可排序。

• (7) 输出是一个 {"mode": input type, "count": Int64} 结构的数组。它包含输入中最常见的 N 个元素，按降序排列，其中 N 由 ModeOptions::n 给出。如果两个值的计数相同，则较小的值排在前面。请注意，如果输入的离散值少于 N 个，则输出的元素可能少于 N 个。

• (8) 第一个输入包含透视键，而第二个输入包含要透视的值。 输出是一个结构体，其中包含 PivotOptions::key_names 中每个键的字段。

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

• (10) 输出是 Float64 或输入类型，具体取决于 QuantileOptions。

• (11) Decimal 参数首先被强制转换为 Float64。

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

  Decimal 参数首先被强制转换为 Float64。

分组聚合（“group by”）

分组聚合不能直接调用，而是用作 SQL 风格的“group by”操作的一部分。 与标量聚合一样，分组聚合将多个输入值减少为单个输出值。 但是，分组聚合不是聚合输入的所有值，而是将输入值在某些“键”列集合上进行分区，然后分别聚合每个组，为每个输入组发出一个输出值。

例如，对于下表

列 key	列 x
“a”	2
“a”	5
“b”	null
“b”	null
null	null
null	9

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

列 key	列 sum(x)
“a”	7
“b”	null
null	9

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

函数名称	元数	输入类型	输出类型	选项类	注释
hash_all	一元	布尔值	布尔值	ScalarAggregateOptions	(1)
hash_any	一元	布尔值	布尔值	ScalarAggregateOptions	(1)
hash_approximate_median	一元	数值	Float64	ScalarAggregateOptions
hash_count	一元	任何	Int64	CountOptions	(2)
hash_count_all	零元		Int64
hash_count_distinct	一元	任何	Int64	CountOptions	(2)
hash_distinct	一元	任何	输入类型的列表	CountOptions	(2) (3)
hash_first	一元	数值，二进制	输入类型	ScalarAggregateOptions	(11)
hash_first_last	一元	数值，二进制	结构体	ScalarAggregateOptions	(11)
hash_kurtosis	一元	数值	Float64	SkewOptions	(9)
hash_last	一元	数值，二进制	输入类型	ScalarAggregateOptions	(11)
hash_list	一元	任何	输入类型的列表		(3)
hash_max	一元	非嵌套、非二进制/类字符串	输入类型	ScalarAggregateOptions
hash_mean	一元	数值	Decimal/Float64	ScalarAggregateOptions	(4)
hash_min	一元	非嵌套、非二进制/类字符串	输入类型	ScalarAggregateOptions
hash_min_max	一元	非嵌套类型	结构体	ScalarAggregateOptions	(5)
hash_one	一元	任何	输入类型		(6)
hash_pivot_wider	二进制	二进制，字符串，整数（参数 0）；任何（参数 1）	结构体	PivotWiderOptions	(7)
hash_product	一元	数值	数值	ScalarAggregateOptions	(8)
hash_skew	一元	数值	Float64	SkewOptions	(9)
hash_stddev	一元	数值	Float64	VarianceOptions	(9)
hash_sum	一元	数值	数值	ScalarAggregateOptions	(8)
hash_tdigest	一元	数值	FixedSizeList[Float64]	TDigestOptions	(10)
hash_variance	一元	数值	Float64	VarianceOptions	(9)

• (1) 如果考虑空值，通过将 ScalarAggregateOptions::skip_nulls 设置为 false，则应用Kleene 逻辑。 min_count 选项不生效。

• (2) CountMode 控制是仅计算非空值（默认），仅计算空值，还是计算所有值。 对于 hash_distinct，它改为控制是否发出空值。 这永远不会影响分组键，只会影响组值（即，您可能会得到一个键为空的组）。

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

• (4) 对于 decimal 输入，生成的 decimal 将具有相同的精度和比例。 结果四舍五入远离零。

• (5) 输出是一个 {"min": input type, "max": input type} 结构体数组。

  在间隔类型中，仅支持月份间隔，因为日期时间和月份日期时间纳米类型不可排序。

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

• (7) 第一个输入包含透视键，而第二个输入包含要透视的值。 输出是一个结构体，其中包含 PivotOptions::key_names 中每个键的字段。

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

• (9) Decimal 参数首先被强制转换为 Float64。

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

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

逐元素（“标量”）函数

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

• 标量输入产生标量输出

• 数组输入产生数组输出

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

• (标量, 标量) 输入产生标量输出

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

• (标量, 数组) 和 (数组, 标量) 产生数组输出。 标量输入被视为长度为 N 的数组，与另一个输入相同，并且相同的值重复 N 次。

算术函数

这些函数期望数值类型的输入，并将给定的算术运算应用于从输入中收集的每个元素。 如果任何输入元素为空，则相应的输出元素为空。 对于二元函数，输入将在应用运算之前强制转换为通用数值类型（并在适用时进行字典解码）。

这些函数的默认变体不检测溢出（然后结果通常会回绕）。 大多数函数还有一种溢出检查变体，后缀为 _checked，当检测到溢出时，该变体会返回一个 Invalid Status。

对于支持 decimal 输入的函数（目前为 add, subtract, multiply 和 divide 及其 checked 变体），不同精度/比例的 decimals 将被适当地提升。 混合的 decimal 和浮点参数会将所有参数强制转换为浮点数，而混合的 decimal 和整数参数会将所有参数强制转换为 decimals。 混合的时间分辨率时间输入将被强制转换为最精细的输入分辨率。

函数名称	元数	输入类型	输出类型	注释
abs	一元	数值/持续时间	数值/持续时间
abs_checked	一元	数值/持续时间	数值/持续时间
add	二进制	数值/时间	数值/时间	(1)
add_checked	二进制	数值/时间	数值/时间	(1)
divide	二进制	数值/时间	数值/时间	(1)
divide_checked	二进制	数值/时间	数值/时间	(1)
exp	一元	数值	Float32/Float64
expm1	一元	数值	Float32/Float64
multiply	二进制	数值/时间	数值/时间	(1)
multiply_checked	二进制	数值/时间	数值/时间	(1)
negate	一元	数值/持续时间	数值/持续时间
negate_checked	一元	有符号数值/持续时间	有符号数值/持续时间
power	二进制	数值	数值
power_checked	二进制	数值	数值
sign	一元	数值/持续时间	Int8/Float32/Float64	(2)
sqrt	一元	数值	数值
sqrt_checked	一元	数值	数值
subtract	二进制	数值/时间	数值/时间	(1)
subtract_checked	二进制	数值/时间	数值/时间	(1)

• (1) 计算的 DECIMAL 结果的精度和比例

  操作	结果精度和比例
  add subtract	scale = max(s1, s2) precision = max(p1-s1, p2-s2) + 1 + scale
  multiply	scale = s1 + s2 precision = p1 + p2 + 1
  divide	scale = max(4, s1 + p2 - s2 + 1) precision = p1 - s1 + s2 + scale

  它与 Redshift 的 decimal 提升规则兼容。 所有 decimal 数字都保留用于 add, subtract 和 multiply 操作。 divide 的结果精度至少是两个操作数的精度之和，并保留足够的比例。 如果结果精度超出 decimal 值范围，则返回错误。

• (2) 对于非零输入，输出为 (-1,1) 中的任何一个，对于零输入，输出为 0。 NaN 值返回 NaN。 积分和 decimal 值将有符号性作为 Int8 返回，浮点值以与输入值相同的类型返回它。

位运算函数

函数名称	元数	输入类型	输出类型
bit_wise_and	二进制	数值	数值
bit_wise_not	一元	数值	数值
bit_wise_or	二进制	数值	数值
bit_wise_xor	二进制	数值	数值
shift_left	二进制	数值	数值
shift_left_checked	二进制	数值	数值 (1)
shift_right	二进制	数值	数值
shift_right_checked	二进制	数值	数值 (1)

• (1) 如果移位量（即第二个输入）超出数据类型的范围，则会发出错误。 但是，移位第一个输入时的溢出不是错误（截断的位将被静默丢弃）。

舍入函数

舍入函数根据舍入标准将数值输入替换为具有更简单表示的近似值。

函数名称	元数	输入类型	输出类型	选项类	注释
ceil	一元	数值	Float32/Float64/Decimal
floor	一元	数值	Float32/Float64/Decimal
round	一元	数值	输入类型	RoundOptions	(1)(2)
round_to_multiple	一元	数值	输入类型	RoundToMultipleOptions	(1)(3)
round_binary	二进制	数值	输入类型	RoundBinaryOptions	(1)(4)
trunc	一元	数值	Float32/Float64/Decimal

• (1) 默认情况下，舍入函数使用 HALF_TO_EVEN 将值更改为最接近的整数以解决联系。 可以使用选项来控制舍入标准。 所有 round 函数都有 round_mode 选项来设置舍入模式。

• (2) 舍入到指定位数的数字，其中 ndigits RoundOptions 的选项指定了舍入精度，以位数来表示。负值对应于非小数部分的位数。例如，-2 对应于舍入到最接近 100 的倍数（将个位和十位数字置零）。ndigits 的默认值为 0，表示舍入到最接近的整数。对于整数输入，非负的 ndigits 值将被忽略，输入将保持不变。对于整数输入，如果 -ndigits 大于输入类型可以容纳的最大位数，则会返回错误。

• (3) 舍入到倍数，其中 multiple RoundToMultipleOptions 的选项指定舍入比例。舍入倍数必须是正值，并且可以强制转换为输入类型。例如，100 对应于舍入到最接近 100 的倍数（将个位和十位数字置零）。multiple 的默认值为 1，表示舍入到最接近的整数。

• (4) 将第一个输入舍入到第二个输入的倍数。舍入倍数必须是正值，并且可以强制转换为第一个输入类型。例如，100 对应于舍入到最接近 100 的倍数（将个位和十位数字置零）。

对于 round 函数，可以使用以下舍入模式。Tie-breaking 模式以 HALF 为前缀，并将非 ties 舍入到最接近的整数。给出的示例值适用于 ndigits 和 multiple 的默认值。

round_mode	执行的操作	示例值
DOWN	舍入到最接近的，小于或等于其绝对值的整数；也称为 floor(x)	3.2 -> 3, 3.7 -> 3, -3.2 -> -4, -3.7 -> -4
UP	舍入到最接近的，大于或等于其绝对值的整数；也称为 ceil(x)	3.2 -> 4, 3.7 -> 4, -3.2 -> -3, -3.7 -> -3
TOWARDS_ZERO	获取不带小数位的整数部分；也称为 trunc(x)	3.2 -> 3, 3.7 -> 3, -3.2 -> -3, -3.7 -> -3
TOWARDS_INFINITY	对负值使用 DOWN 规则进行舍入，对正值使用 UP 规则进行舍入	3.2 -> 4, 3.7 -> 4, -3.2 -> -4, -3.7 -> -4
HALF_DOWN	使用 DOWN 规则对 ties 进行舍入	3.5 -> 3, 4.5 -> 4, -3.5 -> -4, -4.5 -> -5
HALF_UP	使用 UP 规则对 ties 进行舍入	3.5 -> 4, 4.5 -> 5, -3.5 -> -3, -4.5 -> -4
HALF_TOWARDS_ZERO	使用 TOWARDS_ZERO 规则对 ties 进行舍入	3.5 -> 3, 4.5 -> 4, -3.5 -> -3, -4.5 -> -4
HALF_TOWARDS_INFINITY	使用 TOWARDS_INFINITY 规则对 ties 进行舍入	3.5 -> 4, 4.5 -> 5, -3.5 -> -4, -4.5 -> -5
HALF_TO_EVEN	将 ties 舍入到最接近的偶数整数	3.5 -> 4, 4.5 -> 4, -3.5 -> -4, -4.5 -> -4
HALF_TO_ODD	将 ties 舍入到最接近的奇数整数	3.5 -> 3, 4.5 -> 5, -3.5 -> -3, -4.5 -> -5

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

舍入 multiple	舍入 ndigits	执行的操作
1	0	舍入到整数
0.001	3	舍入到小数点后 3 位
10	-1	舍入到 10 的倍数
2	NA	舍入到 2 的倍数

对数函数

还支持对数函数，并且还提供 _checked 变体，如果需要，可以检查域错误。

接受十进制值，但首先将其转换为 Float64。

函数名称	元数	输入类型	输出类型
ln	一元	Float32/Float64/Decimal	Float32/Float64
ln_checked	一元	Float32/Float64/Decimal	Float32/Float64
log10	一元	Float32/Float64/Decimal	Float32/Float64
log10_checked	一元	Float32/Float64/Decimal	Float32/Float64
log1p	一元	Float32/Float64/Decimal	Float32/Float64
log1p_checked	一元	Float32/Float64/Decimal	Float32/Float64
log2	一元	Float32/Float64/Decimal	Float32/Float64
log2_checked	一元	Float32/Float64/Decimal	Float32/Float64
logb	二进制	Float32/Float64/Decimal	Float32/Float64
logb_checked	二进制	Float32/Float64/Decimal	Float32/Float64

三角函数

还支持三角函数，并且还提供 _checked 变体，如果需要，可以检查域错误。

接受十进制值，但首先将其转换为 Float64。

函数名称	元数	输入类型	输出类型
acos	一元	Float32/Float64/Decimal	Float32/Float64
acos_checked	一元	Float32/Float64/Decimal	Float32/Float64
asin	一元	Float32/Float64/Decimal	Float32/Float64
asin_checked	一元	Float32/Float64/Decimal	Float32/Float64
atan	一元	Float32/Float64/Decimal	Float32/Float64
atan2	二进制	Float32/Float64/Decimal	Float32/Float64
cos	一元	Float32/Float64/Decimal	Float32/Float64
cos_checked	一元	Float32/Float64/Decimal	Float32/Float64
sin	一元	Float32/Float64/Decimal	Float32/Float64
sin_checked	一元	Float32/Float64/Decimal	Float32/Float64
tan	一元	Float32/Float64/Decimal	Float32/Float64
tan_checked	一元	Float32/Float64/Decimal	Float32/Float64

双曲三角函数

还支持双曲三角函数，并且在适用的情况下，还提供 _checked 变体，用于检查域错误。

接受十进制值，但首先将其转换为 Float64。

函数名称	元数	输入类型	输出类型
acosh	一元	Float32/Float64/Decimal	Float32/Float64
acosh_checked	一元	Float32/Float64/Decimal	Float32/Float64
asinh	一元	Float32/Float64/Decimal	Float32/Float64
atanh	一元	Float32/Float64/Decimal	Float32/Float64
atanh_checked	一元	Float32/Float64/Decimal	Float32/Float64
cosh	一元	Float32/Float64/Decimal	Float32/Float64
sinh	一元	Float32/Float64/Decimal	Float32/Float64
tanh	一元	Float32/Float64/Decimal	Float32/Float64

比较

这些函数期望两个数字类型的输入（在这种情况下，它们将在比较之前转换为 common numeric type），或者两个 Binary- 或 String-like 类型的输入，或者两个 Temporal 类型的输入。如果任何输入是字典编码的，它将被展开以进行比较。如果一对输入元素中的任何一个为空，则相应的输出元素为空。Decimal 参数将以与 add 和 subtract 相同的方式进行提升。

函数名	元数	输入类型	输出类型
equal	二进制	数字、Temporal、Binary- 和 String-like	布尔值
greater	二进制	数字、Temporal、Binary- 和 String-like	布尔值
greater_equal	二进制	数字、Temporal、Binary- 和 String-like	布尔值
less	二进制	数字、Temporal、Binary- 和 String-like	布尔值
less_equal	二进制	数字、Temporal、Binary- 和 String-like	布尔值
not_equal	二进制	数字、Temporal、Binary- 和 String-like	布尔值

这些函数接受任意数量的数字类型输入（在这种情况下，它们将在比较之前转换为 common numeric type）或 Temporal 类型的输入。如果任何输入是字典编码的，它将被展开以进行比较。

函数名	元数	输入类型	输出类型	选项类	注释
max_element_wise	Varargs	数字、Temporal、Binary- 和 String-like	数字或 Temporal	ElementWiseAggregateOptions	(1)
min_element_wise	Varargs	数字、Temporal、Binary- 和 String-like	数字或 Temporal	ElementWiseAggregateOptions	(1)

• (1) 默认情况下，nulls 被跳过（但可以将内核配置为传播 nulls）。对于浮点值，NaN 将优先于 null，但不优先于任何其他值。对于 binary- 和 string-like 值，仅支持相同的类型参数。

逻辑函数

这些函数的正常行为是，如果任何输入为空，则发出 null（类似于浮点计算中 NaN 的语义）。

其中一些函数还提供 Kleene 逻辑变体（后缀为 _kleene），其中 null 被认为是“未定义”。这是在 SQL 系统以及 R 和 Julia 中使用的 null 解释示例。

因此，对于 Kleene 逻辑变体

• “true AND null”、“null AND true”给出“null”（结果未定义）

• “true OR null”、“null OR true”给出“true”

• “false AND null”、“null AND false”给出“false”

• “false OR null”、“null OR false”给出“null”（结果未定义）

函数名称	元数	输入类型	输出类型
和	二进制	布尔值	布尔值
and_kleene	二进制	布尔值	布尔值
and_not	二进制	布尔值	布尔值
and_not_kleene	二进制	布尔值	布尔值
invert	一元	布尔值	布尔值
or	二进制	布尔值	布尔值
or_kleene	二进制	布尔值	布尔值
xor	二进制	布尔值	布尔值

字符串谓词

这些函数根据输入字符串元素的字符内容对其进行分类。空字符串元素在输出中发出 false。对于函数的 ASCII 变体（前缀为 ascii_），包含非 ASCII 字符的字符串元素在输出中发出 false。

第一组函数以逐个字符为基础运行，如果输入仅包含给定类的字符，则在输出中发出 true

函数名称	元数	输入类型	输出类型	匹配的字符类	注释
ascii_is_alnum	一元	String-like	布尔值	字母数字 ASCII
ascii_is_alpha	一元	String-like	布尔值	字母 ASCII
ascii_is_decimal	一元	String-like	布尔值	十进制 ASCII	(1)
ascii_is_lower	一元	String-like	布尔值	小写 ASCII	(2)
ascii_is_printable	一元	String-like	布尔值	可打印 ASCII
ascii_is_space	一元	String-like	布尔值	空格 ASCII
ascii_is_upper	一元	String-like	布尔值	大写 ASCII	(2)
utf8_is_alnum	一元	String-like	布尔值	字母数字 Unicode
utf8_is_alpha	一元	String-like	布尔值	字母 Unicode
utf8_is_decimal	一元	String-like	布尔值	十进制 Unicode
utf8_is_digit	一元	String-like	布尔值	Unicode 数字	(3)
utf8_is_lower	一元	String-like	布尔值	小写 Unicode	(2)
utf8_is_numeric	一元	String-like	布尔值	数字 Unicode	(4)
utf8_is_printable	一元	String-like	布尔值	可打印 Unicode
utf8_is_space	一元	String-like	布尔值	空格 Unicode
utf8_is_upper	一元	String-like	布尔值	大写 Unicode	(2)

• (1) 还匹配所有数字 ASCII 字符和所有 ASCII 数字。

• (2) 非大小写字符（例如标点符号）不匹配。

• (3) 当前与 utf8_is_decimal 相同。

• (4) 与 utf8_is_decimal 不同，非十进制数字字符也匹配。

第二组函数还考虑字符串元素中的字符顺序

函数名称	元数	输入类型	输出类型	注释
ascii_is_title	一元	String-like	布尔值	(1)
utf8_is_title	一元	String-like	布尔值	(1)

• (1) 仅当输入字符串元素为首字母大写时，输出才为 true，即任何单词都以大写字符开头，后跟小写字符。单词边界由非大小写字符定义。

第三组函数以逐字节为基础检查字符串元素

函数名称	元数	输入类型	输出类型	注释
string_is_ascii	一元	String-like	布尔值	(1)

• (1) 仅当输入字符串元素仅包含 ASCII 字符时，输出才为 true，即仅包含 [0, 127] 中的字节。

字符串转换

函数名称	元数	输入类型	输出类型	选项类	注释
ascii_capitalize	一元	String-like	String-like		(1)
ascii_lower	一元	String-like	String-like		(1)
ascii_reverse	一元	String-like	String-like		(2)
ascii_swapcase	一元	String-like	String-like		(1)
ascii_title	一元	String-like	String-like		(1)
ascii_upper	一元	String-like	String-like		(1)
binary_length	一元	Binary- 或 String-like	Int32 或 Int64		(3)
binary_repeat	二进制	Binary/String (Arg 0); Integral (Arg 1)	Binary- 或 String-like		(4)
binary_replace_slice	一元	String-like	Binary- 或 String-like	ReplaceSliceOptions	(5)
binary_reverse	一元	二进制	二进制		(6)
replace_substring	一元	String-like	String-like	ReplaceSubstringOptions	(7)
replace_substring_regex	一元	String-like	String-like	ReplaceSubstringOptions	(8)
utf8_capitalize	一元	String-like	String-like		(9)
utf8_length	一元	String-like	Int32 或 Int64		(10)
utf8_lower	一元	String-like	String-like		(9)
utf8_replace_slice	一元	String-like	String-like	ReplaceSliceOptions	(7)
utf8_reverse	一元	String-like	String-like		(11)
utf8_swapcase	一元	String-like	String-like		(9)
utf8_title	一元	String-like	String-like		(9)
utf8_upper	一元	String-like	String-like		(9)

• (1) 输入中的每个 ASCII 字符都会转换为小写或大写。非 ASCII 字符保持不变。

• (2) ASCII 输入被反转到输出。如果存在非 ASCII 字符，则将返回 Invalid Status。

• (3) 输出是每个输入元素的物理长度（以字节为单位）。对于 Binary/String，输出类型为 Int32，对于 LargeBinary/LargeString，输出类型为 Int64。

• (4) 将输入的二进制字符串重复给定的次数。

• (5) 将子字符串中从 ReplaceSliceOptions::start (包含) 到 ReplaceSliceOptions::stop (不包含) 的切片，替换为 ReplaceSubstringOptions::replacement。 binary kernel 以字节为单位测量切片，而 UTF8 kernel 以代码单元为单位测量切片。

• (6) 执行字节级别的反转。

• (7) 将与 ReplaceSubstringOptions::pattern 匹配的非重叠子字符串替换为 ReplaceSubstringOptions::replacement。 如果 ReplaceSubstringOptions::max_replacements != -1，则它确定进行的最大替换次数，从左侧开始计数。

• (8) 将与正则表达式 ReplaceSubstringOptions::pattern 匹配的非重叠子字符串替换为 ReplaceSubstringOptions::replacement，使用 Google RE2 库。 如果 ReplaceSubstringOptions::max_replacements != -1，则它确定进行的最大替换次数，从左侧开始计数。 请注意，如果模式包含组，则可以使用反向引用。

• (9) 输入中的每个 UTF8 编码字符都转换为小写或大写。

• (10) 输出是每个输入元素的字符数（不是字节数）。 String 的输出类型为 Int32，LargeString 的输出类型为 Int64。

• (11) 每个 UTF8 编码的代码单元以相反的顺序写入输出。 如果输入不是有效的 UTF8，则输出未定义（但会保留输出缓冲区的大小）。

字符串填充

这些函数附加/前置给定的填充字节 (ASCII) 或代码点 (UTF8)，以便使字符串居中 (center)、右对齐 (lpad) 或左对齐 (rpad)。

函数名称	元数	输入类型	输出类型	选项类
ascii_center	一元	String-like	String-like	PadOptions
ascii_lpad	一元	String-like	String-like	PadOptions
ascii_rpad	一元	String-like	String-like	PadOptions
utf8_center	一元	String-like	String-like	PadOptions
utf8_lpad	一元	String-like	String-like	PadOptions
utf8_rpad	一元	String-like	String-like	PadOptions

字符串修剪

这些函数修剪掉两侧 (trim) 或左侧 (ltrim) 或右侧 (rtrim) 的字符。

函数名称	元数	输入类型	输出类型	选项类	注释
ascii_ltrim	一元	String-like	String-like	TrimOptions	(1)
ascii_ltrim_whitespace	一元	String-like	String-like		(2)
ascii_rtrim	一元	String-like	String-like	TrimOptions	(1)
ascii_rtrim_whitespace	一元	String-like	String-like		(2)
ascii_trim	一元	String-like	String-like	TrimOptions	(1)
ascii_trim_whitespace	一元	String-like	String-like		(2)
utf8_ltrim	一元	String-like	String-like	TrimOptions	(3)
utf8_ltrim_whitespace	一元	String-like	String-like		(4)
utf8_rtrim	一元	String-like	String-like	TrimOptions	(3)
utf8_rtrim_whitespace	一元	String-like	String-like		(4)
utf8_trim	一元	String-like	String-like	TrimOptions	(3)
utf8_trim_whitespace	一元	String-like	String-like		(4)

• (1) 仅修剪掉 TrimOptions::characters 中指定的字符。 输入字符串和 characters 参数都解释为 ASCII 字符。

• (2) 仅修剪掉 ASCII 空格字符 ('\t'、'\n'、'\v'、'\f'、'\r' 和 ' ')。

• (3) 仅修剪掉 TrimOptions::characters 中指定的字符。

• (4) 仅修剪掉 Unicode 空格字符。

字符串分割

这些函数将字符串分割成字符串列表。 所有 kernel 都可以选择使用 max_splits 和 reverse 参数进行配置，其中 max_splits == -1 表示没有限制（默认值）。 当 reverse 为 true 时，分割从字符串的末尾开始进行；这仅在给定正 max_splits 时相关。

函数名称	元数	输入类型	输出类型	选项类	注释
ascii_split_whitespace	一元	String-like	List-like	SplitOptions	(1)
split_pattern	一元	Binary- 或 String-like	List-like	SplitPatternOptions	(2)
split_pattern_regex	一元	Binary- 或 String-like	List-like	SplitPatternOptions	(3)
utf8_split_whitespace	一元	String-like	List-like	SplitOptions	(4)

• (1) 非零长度的 ASCII 定义的空格字节序列 ('\t'、'\n'、'\v'、'\f'、'\r' 和 ' ') 被视为分隔符。

• (2) 当找到完全匹配的模式时，字符串将被分割（模式本身不包含在输出中）。

• (3) 当找到正则表达式匹配项时，字符串将被分割（匹配的子字符串本身不包含在输出中）。

• (4) 非零长度的 Unicode 定义的空格代码点序列被视为分隔符。

字符串组件提取

函数名称	元数	输入类型	输出类型	选项类	注释
extract_regex	一元	Binary- 或 String-like	结构体	ExtractRegexOptions	(1)
extract_regex_span	一元	Binary- 或 String-like	结构体	ExtractRegexSpanOptions	(2)

• (1) 使用 Google RE2 库提取由正则表达式定义的子字符串。 输出结构字段名称引用命名的捕获组，例如正则表达式 (?P<letter>[ab])(?P<digit>\\d) 的 ‘letter’ 和 ‘digit’。

• (2) 使用 Google RE2 库提取由正则表达式定义的子字符串的偏移量和长度。 输出结构字段名称引用命名的捕获组，例如正则表达式 (?P<letter>[ab])(?P<digit>\\d) 的 ‘letter’ 和 ‘digit’。 每个输出结构字段都是一个固定大小的两个整数列表：捕获组的起始索引和捕获组的长度。

字符串连接

这些函数执行字符串分割的逆操作。

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	注释
binary_join	二进制	Binary- or String-like 的列表	String-like	String-like		(1)
binary_join_element_wise	Varargs	Binary- or String-like (varargs)	Binary- 或 String-like	Binary- 或 String-like	JoinOptions	(2)

• (1) 第一个输入必须是一个数组，而第二个输入可以是标量或数组。 第一个输入中的每个值列表都使用每个第二个输入作为分隔符进行连接。 如果任何输入列表为 null 或包含 null 值，则相应的输出将为 null。

• (2) 所有参数都按元素方式连接，最后一个参数被视为分隔符（无论哪种情况，标量都会被回收）。 Null 分隔符发出 null。 如果任何其他参数为 null，则默认情况下相应的输出将为 null，但它可以选择跳过或替换为给定的字符串。

字符串切片

此函数根据起始和停止索引以及非零步长（默认为 1）将数组的每个序列转换为子序列。 切片语义遵循 Python 切片语义：起始索引是包含的，停止索引是不包含的；如果步长为负数，则序列以相反的顺序执行。

函数名称	元数	输入类型	输出类型	选项类	注释
binary_slice	一元	Binary-like	Binary-like	SliceOptions	(1)
utf8_slice_codeunits	一元	String-like	String-like	SliceOptions	(2)

• (1) 将字符串切片为由 SliceOptions 给出的 (start, stop, step) 定义的子字符串，其中 start 和 stop 以字节为单位测量。 Null 输入发出 null。

• (2) 将字符串切片为由 SliceOptions 给出的 (start, stop, step) 定义的子字符串，其中 start 和 stop 以代码单元为单位测量。 Null 输入发出 null。

包含测试

函数名称	元数	输入类型	输出类型	选项类	注释
count_substring	一元	Binary- 或 String-like	Int32 或 Int64	MatchSubstringOptions	(1)
count_substring_regex	一元	Binary- 或 String-like	Int32 或 Int64	MatchSubstringOptions	(1)
ends_with	一元	Binary- 或 String-like	布尔值	MatchSubstringOptions	(2)
find_substring	一元	Binary- and String-like	Int32 或 Int64	MatchSubstringOptions	(3)
find_substring_regex	一元	Binary- and String-like	Int32 或 Int64	MatchSubstringOptions	(3)
index_in	一元	Boolean, Null, Numeric, Temporal, Binary- and String-like	Int32	SetLookupOptions	(4)
is_in	一元	Boolean, Null, Numeric, Temporal, Binary- and String-like	布尔值	SetLookupOptions	(5)
match_like	一元	Binary- 或 String-like	布尔值	MatchSubstringOptions	(6)
match_substring	一元	Binary- 或 String-like	布尔值	MatchSubstringOptions	(7)
match_substring_regex	一元	Binary- 或 String-like	布尔值	MatchSubstringOptions	(8)
starts_with	一元	Binary- 或 String-like	布尔值	MatchSubstringOptions	(2)

• (1) 输出是 MatchSubstringOptions::pattern 在相应输入字符串中出现的次数。 Binary/String 的输出类型为 Int32，LargeBinary/LargeString 的输出类型为 Int64。

• (2) 当且仅当 MatchSubstringOptions::pattern 是相应输入的后缀/前缀时，输出为 true。

• (3) 输出是 MatchSubstringOptions::pattern 在相应输入字符串中第一次出现的索引，否则为 -1。 Binary/String 的输出类型为 Int32，LargeBinary/LargeString 的输出类型为 Int64。

• (4) 如果在 SetLookupOptions::value_set 中找到对应的输入元素，则输出是该元素的索引。否则，输出为空值。

• (5) 当且仅当对应的输入元素等于 SetLookupOptions::value_set 中的一个元素时，输出为真。

• (6) 当且仅当 SQL 风格的 LIKE 模式 MatchSubstringOptions::pattern 与对应的输入元素完全匹配时，输出为真。也就是说，% 将匹配任意数量的字符，_ 将精确匹配一个字符，任何其他字符匹配它本身。要匹配字面百分号或下划线，请在该字符前加反斜杠。

• (7) 当且仅当 MatchSubstringOptions::pattern 是对应输入元素的子字符串时，输出为真。

• (8) 当且仅当 MatchSubstringOptions::pattern 在任何位置与对应的输入元素匹配时，输出为真。

分类

函数名称	元数	输入类型	输出类型	选项类	注释
is_finite	一元	Null, Numeric	布尔值		(1)
is_inf	一元	Null, Numeric	布尔值		(2)
is_nan	一元	Null, Numeric	布尔值		(3)
is_null	一元	任何	布尔值	NullOptions	(4)
is_valid	一元	任何	布尔值		(5)
true_unless_null	一元	任何	布尔值		(6)

• (1) 当且仅当对应的输入元素是有限的（既不是 Infinity，也不是 -Infinity，也不是 NaN）时，输出为真。因此，对于 Decimal 和整数输入，此函数始终返回 true。

• (2) 当且仅当对应的输入元素是 Infinity/-Infinity 时，输出为真。因此，对于 Decimal 和整数输入，此函数始终返回 false。

• (3) 当且仅当对应的输入元素是 NaN 时，输出为真。因此，对于 Decimal 和整数输入，此函数始终返回 false。

• (4) 当且仅当对应的输入元素为空值时，输出为真。通过设置 NullOptions::nan_is_null，NaN 值也可以被视为空值。

• (5) 当且仅当对应的输入元素非空时，输出为真，否则为假。

• (6) 当且仅当对应的输入元素非空时，输出为真，否则为空值。

  主要用于表达式简化/保证。

选择 / 多路复用

对于每行输入值，这些函数根据条件发出其中一个输入值。

函数名称	元数	输入类型	输出类型	注释
case_when	Varargs	Boolean 的结构 (Arg 0), 任何 (其余)	输入类型	(1)
choose	Varargs	Integral (Arg 0), 定宽/类似二进制 (其余)	输入类型	(2)
coalesce	Varargs	任何	输入类型	(3)
if_else	三元运算符	Boolean (Arg 0), 任何 (其余)	输入类型	(4)

• (1) 此函数的作用类似于 SQL “case when” 语句或 switch-case。输入是一个 “condition” 值，它是一个 Boolean 的结构体，后跟每个 “branch” 的值。条件结构体的每个子项必须恰好有一个值参数，或者比子项多一个值参数（在这种情况下，我们有一个 “else” 或 “default” 值）。输出与值输入的类型相同；每行将是第一个布尔值为 true 的值数据对应的value值，或者是 “default” 输入对应的value值，否则为空值。

  请注意，目前，虽然支持所有类型，但字典将被解包。

• (2) 第一个输入必须是 integral 类型。其余参数可以是任何类型，但必须都是相同类型或可提升为通用类型。第一个输入（“index”）的每个值都用作其余参数的基于零的索引（即，索引 0 是第二个参数，索引 1 是第三个参数，依此类推），并且该行的输出值将是所选输入的相应值在该行。如果索引为空值，则输出也将为空值。

• (3) 输出的每一行将是该行第一个非空的输入值，否则为空值。

• (4) 第一个输入必须是 Boolean 标量或数组。第二和第三个输入可以是标量或数组，并且必须是相同类型。输出是一个数组（如果所有输入都是标量，则为标量），其类型与第二个/第三个输入相同。如果第一个输入中存在空值，则它们将被提升到输出，否则将根据第一个输入值选择空值。

  另请参见：replace_with_mask。

结构转换

函数名称	元数	输入类型	输出类型	选项类	注释
list_value_length	一元	List-like	Int32 或 Int64		(1)
make_struct	Varargs	任何	结构体	MakeStructOptions	(2)

• (1) 每个输出元素都是对应输入元素的长度（如果输入为空值，则为空值）。对于 List、ListView 和 FixedSizeList，输出类型为 Int32，对于 LargeList 和 LargeListView，输出类型为 Int64。

• (2) 输出结构体的字段类型是其参数的类型。字段名称使用 MakeStructOptions 的实例指定。如果所有输入都是标量，则输出形状将是标量，否则任何标量都将广播到数组。

转换

提供了一个名为 cast 的通用转换函数，该函数接受大量的输入和输出类型。要转换为的类型可以在 CastOptions 实例中传递。或者，具体的函数 Cast() 提供了相同的服务。

函数名称	元数	输入类型	输出类型	选项类	注释
ceil_temporal	一元	Temporal	Temporal	RoundTemporalOptions
floor_temporal	一元	Temporal	Temporal	RoundTemporalOptions
round_temporal	一元	Temporal	Temporal	RoundTemporalOptions
cast	一元	Many	Variable	CastOptions
strftime	一元	Temporal	String	StrftimeOptions	(1)
strptime	一元	String-like	Timestamp	StrptimeOptions

下面列出了 cast 可用的转换。在所有情况下，空输入值都会转换为空输出值。

• (1) %S（秒）标志的输出精度取决于输入时间戳精度。具有秒精度的时间戳表示为整数，而毫秒、微秒和纳秒表示为固定浮点数，分别具有 3、6 和 9 位小数。要获得整数秒，请强制转换为具有秒分辨率的时间戳。小数点字符根据区域设置进行本地化。有关其他标志的说明，请参见详细格式化文档。

真值提取

输入类型	输出类型	注释
Binary- and String-like	布尔值	(1)
数值	布尔值	(2)

• (1) 当且仅当对应的输入值具有非零长度时，输出为真。

• (2) 当且仅当对应的输入值为非零时，输出为真。

同类转换

输入类型	输出类型	注释
Int32	32 位时间	(1)
Int64	64 位时间	(1)
(Large)Binary	(Large)String	(2)
(Large)String	(Large)Binary	(3)
数值	数值	(4) (5)
32 位时间	Int32	(1)
64 位时间	Int64	(1)
Temporal	Temporal	(4) (5)

• (1) 无操作转换：原始值保持不变，仅更改类型。

• (2) 如果 CastOptions::allow_invalid_utf8 为 false，则验证内容。

• (3) 无操作转换：仅更改类型。

• (4) 启用溢出和截断检查，具体取决于给定的 CastOptions。

• (5) 并非所有此类转换都已实现。

字符串表示

输入类型	输出类型	注释
布尔值	String-like
数值	String-like

通用转换

输入类型	输出类型	注释
Dictionary	Dictionary 值类型	(1)
Extension	Extension 存储类型
结构体	结构体	(2)
List-like	List-like 或 (Large)ListView	(3)
(Large)ListView	List-like 或 (Large)ListView	(4)
Map	Map 或 List of two-field struct	(5)
Null	任何
任何	Extension	(6)

• (1) 字典索引不变，字典值从输入值类型转换为输出值类型（如果可以使用转换）。

• (2) 输出类型的字段名称必须与输入类型的字段名称相同或为输入类型的字段名称的子集；它们也必须具有相同的顺序。转换为字段名称的子集 “选择” 这些字段，使得每个输出字段与具有相同名称的输入字段的数据匹配。

• (3) 列表偏移量不变，列表值从输入值类型转换为输出值类型（如果可以使用转换）。如果输出类型为 (Large)ListView，则大小从偏移量派生。

• (4) 如果输出类型类似于列表，则可能必须重建偏移量（因此，重建值数组）才能进行排序和充分间隔。如果输出类型是列表视图类型，则偏移量和大小不变。在任何情况下，列表值都从输入值类型转换为输出值类型（如果可以使用转换）。

• (5) 偏移量不变，键和值从各自的输入类型转换为输出类型（如果可以使用转换）。如果输出类型是结构体列表，则键字段输出为第一个字段，值字段输出为第二个字段，无论选择的字段名称如何。

• (6) 任何可以转换为结果扩展的存储类型的输入类型。这排除了扩展类型，除非转换为相同的扩展类型。

时间分量提取

这些函数从时间类型中提取日期时间分量（年、月、日等）。对于具有非空时区的时间戳输入，将返回本地化时间戳分量。

函数名称	元数	输入类型	输出类型	选项类	注释
day	一元	Temporal	Int64
day_of_week	一元	Temporal	Int64	DayOfWeekOptions	(1)
day_of_year	一元	Temporal	Int64
hour	一元	Timestamp, Time	Int64
is_dst	一元	Timestamp	布尔值
iso_week	一元	Temporal	Int64		(2)
iso_year	一元	Temporal	Int64		(2)
iso_calendar	一元	Temporal	结构体		(3)
is_leap_year（是否为闰年）	一元	Timestamp, Date（时间戳，日期）	布尔值
microsecond（微秒）	一元	Timestamp, Time	Int64
millisecond（毫秒）	一元	Timestamp, Time	Int64
minute（分钟）	一元	Timestamp, Time	Int64
month（月份）	一元	Temporal	Int64
nanosecond（纳秒）	一元	Timestamp, Time	Int64
quarter（季度）	一元	Temporal	Int64
second（秒）	一元	Timestamp, Time	Int64
subsecond（亚秒）	一元	Timestamp, Time	Float64
us_week（美式周）	一元	Temporal	Int64		(4)
us_year（美式年份）	一元	Temporal	Int64		(4)
week（周）	一元	Timestamp	Int64	WeekOptions（周选项）	(5)
year（年份）	一元	Temporal	Int64
year_month_day（年_月_日）	一元	Temporal	结构体		(6)

• (1) 输出星期几的数字。默认情况下，周从星期一开始，用 0 表示，到星期日结束，用 6 表示。根据 DayOfWeekOptions::count_from_zero 参数，日编号可以从 0 或 1 开始。DayOfWeekOptions::week_start 可用于使用 ISO 约定设置一周的起始日（星期一=1，星期日=7）。DayOfWeekOptions::week_start 参数不受 DayOfWeekOptions::count_from_zero 的影响。

• (2) 第一个 ISO 周在一月份拥有大部分（4 天或更多）天数。 ISO 年从第一个 ISO 周开始。 ISO 周从星期一开始。 更多详情请参阅 ISO 8601 周日期定义。

• (3) 输出是一个 {"iso_year": 输出类型, "iso_week": 输出类型, "iso_day_of_week":  输出类型} 结构体。

• (4) 第一个美式周在一月份拥有大部分（4 天或更多）天数。美式年从第一个美式周开始。美式周从星期日开始。

• (5) 返回周数，允许设置多个参数。 如果 WeekOptions::week_starts_monday 为 true，则周从星期一开始，否则如果为 false，则从星期日开始。 如果 WeekOptions::count_from_zero 为 true，则当年份中属于上一年最后一个 ISO 周的日期将编号为第 0 周，否则如果为 false，则为第 52 或 53 周。 如果 WeekOptions::first_week_is_fully_in_year 为 true，则第一周（第 1 周）必须完全在一月份；否则如果为 false，则从 12 月 29 日、30 日或 31 日开始的一周将被视为新年的第一周。

• (6) 输出是一个 {"year": int64(), "month": int64(), "day": int64()} 结构体。

时间差

这些函数计算两个时间戳之间在指定单元中的差值。 该差值由跨越的边界数量决定，而不是时间跨度。 例如，一天中 23:59:59 和第二天 00:00:01 之间的天数差为一天（因为跨越了午夜），而不是零天（即使经过的时间少于 24 小时）。 此外，如果时间戳具有定义的时区，则以本地时区计算差值。 例如，“2019-12-31 18:00:00-0500”和“2019-12-31 23:00:00-0500”之间的年差为零年，因为本地年份相同，即使 UTC 年份不同。

函数名称	元数	输入类型	输出类型	选项类
day_time_interval_between（日_时间_间隔_之间）	二进制	Temporal	DayTime interval（日时间隔）
days_between（天_之间）	二进制	Timestamp, Date（时间戳，日期）	Int64
hours_between（小时_之间）	二进制	Temporal	Int64
microseconds_between（微秒_之间）	二进制	Temporal	Int64
milliseconds_between（毫秒_之间）	二进制	Temporal	Int64
minutes_between（分钟_之间）	二进制	Temporal	Int64
month_day_nano_interval_between（月_日_纳秒_间隔_之间）	二进制	Temporal	MonthDayNano interval（月日纳秒间隔）
month_interval_between（月_间隔_之间）	二进制	Timestamp, Date（时间戳，日期）	Month interval（月间隔）
nanoseconds_between（纳秒_之间）	二进制	Temporal	Int64
quarters_between（季度_之间）	二进制	Timestamp, Date（时间戳，日期）	Int64
seconds_between（秒_之间）	二进制	Temporal	Int64
weeks_between（周_之间）	二进制	Timestamp, Date（时间戳，日期）	Int64	DayOfWeekOptions
years_between（年_之间）	二进制	Timestamp, Date（时间戳，日期）	Int64

时区处理

assume_timezone 函数旨在用于当外部系统产生“时区感知缺失”的时间戳时，需要将这些时间戳转换为“时区感知”的时间戳（例如，请参阅 Python 文档中的 定义）。

输入时间戳被假定为相对于 AssumeTimezoneOptions::timezone 中给出的时区。 它们被转换为 UTC 相对的时间戳，并将时区元数据设置为上述值。 如果时间戳已经设置了时区元数据，则返回错误。

local_timestamp 函数将 UTC 相对的时间戳转换为本地的“时区感知缺失”的时间戳。 时区取自输入时间戳的时区元数据。 此函数是 assume_timezone 的逆函数。 请注意：所有时间函数已经像在元数据提供的时区的本地时间一样对时间戳进行操作。 使用 local_timestamp 仅用于当外部系统期望本地时间戳时。

函数名称	元数	输入类型	输出类型	选项类	注释
assume_timezone（假定时区）	一元	Timestamp	Timestamp	AssumeTimezoneOptions（假定时区选项）	(1)
local_timestamp（本地时间戳）	一元	Timestamp	Timestamp		(2)

• (1) 除了时区值之外，AssumeTimezoneOptions 还允许选择在给定时区中时间戳不明确或不存在时的行为（由于 DST 转换）。

随机数生成

此函数生成一个数组，其中包含范围 [0, 1) 内的均匀分布的双精度数字。 这些选项提供输出的长度和生成随机数的算法，使用种子或系统提供的、特定于平台的随机生成器。

函数名称	元数	输出类型	选项类
random（随机）	零元	Float64	RandomOptions（随机选项）

数组式（“向量”）函数

累积函数

累积函数是向量函数，它们使用给定的二元结合运算以及标识元素（幺半群）对其输入执行运行累积，并输出一个包含相应中间运行值的数组。 输入应为数字类型。 默认情况下，这些函数不检测溢出。 它们也有溢出检查变体，后缀为 _checked，当检测到溢出时，它会返回一个 Invalid Status。

函数名称	元数	输入类型	输出类型	选项类	注释
cumulative_sum（累积_和）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_sum_checked（累积_和_已检查）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_prod（累积_积）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_prod_checked（累积_积_已检查）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_max（累积_最大值）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_min（累积_最小值）	一元	数值	数值	CumulativeOptions（累积选项）	(1)
cumulative_mean（累积_平均值）	一元	数值	Float64	CumulativeOptions（累积选项）	(1) (2)

• (1) CumulativeOptions 有两个可选参数。 第一个参数 CumulativeOptions::start 是运行累积的起始值。 对于 sum，其默认值为 0，对于 prod，其默认值为 1，对于 max，其默认值为输入类型的最小值，对于 min，其默认值为输入类型的最大值。 指定的 start 值必须可以强制转换为输入类型。 第二个参数 CumulativeOptions::skip_nulls 是一个布尔值。 当设置为 false（默认值）时，传播第一个遇到的 null。 当设置为 true 时，输入中的每个 null 都会在输出中产生相应的 null，并且不会影响向前累积。

• (2) CumulativeOptions::start 被忽略。

统计函数

函数名称	元数	输入类型	输出类型	选项类	注释
winsorize（缩尾）	一元	数值	数值	WinsorizeOptions（缩尾选项）	(1)

• (1) 钳制较低和较高分位数中的值，以减少异常值的统计影响。 可以在 WinsorizeOptions 中配置分位数。

关联变换

函数名称	元数	输入类型	输出类型	注释
dictionary_encode（字典编码）	一元	Boolean, Null, Numeric, Temporal, Binary- and String-like	Dictionary	(1)
unique（唯一）	一元	Boolean, Null, Numeric, Temporal, Binary- and String-like	输入类型	(2)
value_counts（值计数）	一元	Boolean, Null, Numeric, Temporal, Binary- and String-like	输入类型	(3)

• (1) 输出是 Dictionary(Int32, 输入类型)。 如果输入已经是字典数组，则它是空操作。

• (2) 从输出中删除重复项，同时保持原始顺序。

• (3) 输出是一个 {"values": 输入类型, "counts": Int64} 结构体。 每个输出元素对应于输入中的唯一值，以及此值出现的次数。

选择

这些函数选择并返回其输入的一个子集。

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	注释
array_filter（数组_过滤）	二进制	任何	布尔值	输入类型 1	FilterOptions（过滤选项）	(2)
array_take（数组_取）	二进制	任何	Integer（整数）	输入类型 1	TakeOptions（取选项）	(3)
drop_null（删除_空值）	一元	任何		输入类型 1		(1)
filter（过滤）	二进制	任何	布尔值	输入类型 1	FilterOptions（过滤选项）	(2)
inverse_permutation（逆_置换）	一元	Signed Integer（有符号整数）		Signed Integer (4)（有符号整数（4））	InversePermutationOptions（逆置换选项）	(5)
scatter（散布）	二进制	任何	Integer（整数）	输入类型 1	ScatterOptions（散布选项）	(6)
take（取）	二进制	任何	Integer（整数）	输入类型 1	TakeOptions（取选项）	(3)

• (1) 当且仅当输入中的每个元素为非空时，才将其附加到输出。 如果输入是记录批处理或表格，则列中的任何空值都会删除整行。

• (2) 如果输入 2（过滤器）中对应的元素为真，则将输入 1（值）中的每个元素添加到输出。如何处理过滤器中的 null 值可以通过 FilterOptions 进行配置。

• (3) 对于输入 2（索引）中的每个元素 i，将输入 1（值）中的第 i 个元素添加到输出。

• (4) 输出类型在 InversePermutationOptions 中指定。

• (5) 对于 indices[i] = x, inverse_permutation[x] = i。如果 x 没有出现在输入索引中，则 inverse_permutation[x] = null。索引必须在 [0, max_index] 的范围内，或者为 null，null 值将被忽略。如果多个索引指向相同的值，则使用最后一个。

• (6) 对于 indices[i] = x, output[x] = values[i]。如果 x 没有出现在输入索引中，则 output[x] = null。索引必须在 [0, max_index] 的范围内，或者为 null，在这种情况下，对应的值将被忽略。如果多个索引指向相同的值，则使用最后一个。

包含性测试

此函数返回数组元素为非 null 且非零的索引。

函数名称	元数	输入类型	输出类型	选项类	注释
indices_nonzero	一元	布尔型、Null、数值型、十进制	UInt64

排序和分区

默认情况下，在这些函数中，null 值被认为大于任何其他值（它们将在数组的末尾进行排序或分区）。浮点 NaN 值被认为大于任何其他非 null 值，但小于 null 值。可以使用相应选项类中的 null_placement 设置来更改此行为。

注意

二进制和类似字符串的输入按字节字符串按字典顺序排序，即使对于字符串类型也是如此。

函数名称	元数	输入类型	输出类型	选项类	注释
array_sort_indices	一元	布尔型、数值型、时间型、二进制和类似字符串	UInt64	ArraySortOptions	(1) (2)
partition_nth_indices	一元	布尔型、数值型、时间型、二进制和类似字符串	UInt64	PartitionNthOptions	(3)
rank	一元	布尔型、数值型、时间型、二进制和类似字符串	UInt64	RankOptions	(4)
rank_normal	一元	布尔型、数值型、时间型、二进制和类似字符串	Float64	RankQuantileOptions	(5)
rank_quantile	一元	布尔型、数值型、时间型、二进制和类似字符串	Float64	RankQuantileOptions	(5)
select_k_unstable	一元	布尔型、数值型、时间型、二进制和类似字符串	UInt64	SelectKOptions	(6) (7)
sort_indices	一元	布尔型、数值型、时间型、二进制和类似字符串	UInt64	SortOptions	(1) (6)

• (1) 输出是一个索引数组，指向输入，定义了输入的稳定排序。

• (2) 输入必须是一个数组。默认顺序是升序。

• (3) 输出是一个索引数组，指向输入数组，定义了一个非稳定的部分排序，使得第 N 个索引指向已排序顺序中的第 N 个元素，并且第 N 个索引之前的所有索引指向小于或等于第 N 个及其之后的元素（类似于 std::nth_element()）。N 在 PartitionNthOptions::pivot 中给出。

• (4) 输出是一个从 1 开始的数值型排名数组。

• (5) rank_quantile 的输出是一个严格介于 0 和 1 之间的分位数数组。rank_normal 的输出是一个有限实数值数组，对应于正态分布中的点，这些点反映了输入的分位数排名。

• (6) 输入可以是数组、分块数组、记录批处理或表。如果输入是记录批处理或表，则必须指定一个或多个排序键。

• (7) 输出是一个索引数组，指向输入，定义了输入的非稳定排序。

结构转换

函数名称	元数	输入类型	输出类型	选项类	注释
list_element	二进制	类似列表 (Arg 0), 整数 (Arg 1)	列表值类型		(1)
list_flatten	一元	List-like	列表值类型		(2)
list_parent_indices	一元	List-like	Int64		(3)
list_slice	一元	List-like	List-like	ListSliceOptions	(4)
map_lookup	一元	Map	已计算	MapLookupOptions	(5)
struct_field	一元	结构体或联合体	已计算	StructFieldOptions	(6)

• (1) 输出是一个与输入列表数组长度相同的数组。输出值是每个子列表的指定索引处的值。

• (2) 移除顶层嵌套：列表子数组中的所有值（包括 null 值）都附加到输出。但是，父列表数组中的 null 值将被丢弃。

• (3) 对于列表子数组中的每个值，将其在类似列表的数组中找到的索引附加到输出。如果父数组是非空 null 列表，则父数组中 null 列表的索引仍可能存在于输出中。如果父数组是列表视图，则任何非 null 列表视图未使用的子数组值在输出中为 null。

• (4) 对于每个列表元素，计算该列表元素的切片，然后返回另一个列表切片的列表状数组。 可以根据提供的选项返回固定或可变大小的类似列表的数组。

• (5) 从键与通过选项传递的给定查询键匹配的映射中提取 FIRST、LAST 或 ALL 项。 输出类型是 FIRST/LAST 选项的项数组，以及 ALL 选项的项列表数组。

• (6) 根据选项中传递的索引序列提取子值。 结果的有效性位图将是所有中间有效性位图的交集。 例如，对于类型为 struct<a: int32, b: struct<c: int64, d: float64>> 的数组

  • 一个空的索引序列会产生原始值不变。

  • 索引 0 会生成一个 int32 类型的数组，其有效性位图是最外层结构体和子级 a 的位图的交集。

  • 索引 1, 1 会生成一个 float64 类型的数组，其有效性位图是最外层结构体、结构体 b 和子级 d 的位图的交集。

  对于联合体，基于类型代码合成有效性位图。 此外，索引始终是子索引，而不是类型代码。 因此，对于类型为 sparse_union<2: int32, 7: utf8> 的数组

  • 索引 0 生成一个 int32 类型的数组，当且仅当子数组 a 在索引 n 处有效且索引 n 处的类型代码为 2 时，它在索引 n 处有效。

  • 索引 2 和 7 无效。

替换函数

这些函数创建第一个输入的副本，并根据剩余的输入替换某些元素。

函数名称	元数	输入类型 1	输入类型 2	输入类型 3	输出类型	注释
fill_null_backward	一元	固定宽度或二进制			输入类型 1	(1)
fill_null_forward	一元	固定宽度或二进制			输入类型 1	(1)
replace_with_mask	三元运算符	固定宽度或二进制	布尔值	输入类型 1	输入类型 1	(2)

• (1) 有效值向前/向后传递以填充 null 值。

• (2) 输入 1 中对应布尔值在输入 2 中为 true 的每个元素都将替换为输入 3 中的下一个值。输入 2 中的 null 值会导致输出中出现对应的 null 值。

  另请参见：if_else。

成对函数

成对函数是一元向量函数，它对输入数组中的一对元素执行二进制运算，通常是对相邻的元素。 第 n 个输出通过将二元运算应用于第 n 个和第 (n-p) 个输入来计算，其中 p 是周期。 默认周期为 1，在这种情况下，二元运算应用于相邻的输入对。 周期也可以为负数，在这种情况下，第 n 个输出通过将二元运算应用于第 n 个和第 (n+abs(p)) 个输入来计算。

函数名称	元数	输入类型	输出类型	选项类	注释
pairwise_diff	一元	数值/时间	数值/时间	PairwiseOptions	(1)(2)
pairwise_diff_checked	一元	数值/时间	数值/时间	PairwiseOptions	(1)(3)

• (1) 计算数组的一阶差分。它内部调用标量函数 Subtract （或检查过的变体）来计算差分，因此其行为和支持的类型与 Subtract 相同。可以在 PairwiseOptions 中指定周期。

• (2) 检测到溢出时，会环绕结果。

• (3) 检测到溢出时，返回一个 Invalid Status。