计算函数

通用计算 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	int32 最大宽度为 32，将左侧提升为 int32
uint16, int32	int32	int32 一个输入有符号，覆盖无符号
uint32, int32	int64	加宽以适应 uint32 的范围
uint16, uint32	uint32	所有输入均为无符号，保持无符号
int16, uint32	int64
int64	int64	错误 int64 不能容纳所有 uint64 值
float32, int32	float32	将右侧提升为 float32
float32, float64	float64
float32, int64	float32	float32 int64 更宽，仍然提升为 float32

尤其要注意的是，将 uint64 列与 int16 列进行比较可能会产生错误，如果其中一个 uint64 值无法表示为通用类型 int64（例如，2 ** 63）。

可用函数

类型类别

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

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

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

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

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

• “类列表”：List、LargeList、ListView、LargeListView，有时也包括 FixedSizeList。

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

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

聚合

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

函数名称	元数	输入类型	输出类型	选项类	备注
all(全部)	一元	布尔值	标量布尔值	ScalarAggregateOptions	(1)
any(任意)	一元	布尔值	标量布尔值	ScalarAggregateOptions	(1)
approximate_median(近似中位数)	一元	数值	标量 Float64	ScalarAggregateOptions
count(计数)	一元	任意	标量 Int64	CountOptions	(2)
count_all(计数全部)	零元		标量 Int64
count_distinct(计数不同)	一元	非嵌套类型	标量 Int64	CountOptions	(2)
first(第一个)	一元	数值，二进制	标量输入类型	ScalarAggregateOptions	(11)
first_last(第一个和最后一个)	一元	数值，二进制	标量结构体	ScalarAggregateOptions	(11)
index(索引)	一元	任意	标量 Int64	任意	(3)
IndexOptions	一元	数值，二进制	标量输入类型	ScalarAggregateOptions	(11)
last(最后一个)	一元	非嵌套类型	标量输入类型	ScalarAggregateOptions
max(最大值)	一元	数值	标量 Decimal/Float64	ScalarAggregateOptions	(4)
min(最小值)	一元	非嵌套类型	标量输入类型	ScalarAggregateOptions
min_max(最小最大值)	一元	非嵌套类型	标量结构体	ScalarAggregateOptions	(5)
mode(众数)	一元	数值	结构体	ModeOptions	(6)
product(乘积)	一元	数值	标量数值	ScalarAggregateOptions	(7)
quantile(分位数)	一元	数值	标量数值	QuantileOptions	(8)
stddev(标准差)	一元	数值	标量 Float64	VarianceOptions	(9)
sum(总和)	一元	数值	标量数值	ScalarAggregateOptions	(7)
tdigest	一元	数值	Float64	TDigestOptions	(10)
variance(方差)	一元	数值	标量 Float64	VarianceOptions	(9)

• (1) 如果考虑空值，通过设置 ScalarAggregateOptions 参数 skip_nulls = false，则应用 Kleene 逻辑。min_count 选项将被忽略。

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

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

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

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

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

• (6) 输出是一个 {"mode": 输入类型, "count": Int64} 结构体数组。它包含输入中最常见的 _N_ 个元素，按降序排列，其中 _N_ 在 ModeOptions::n 中给出。如果两个值具有相同的计数，则较小的值优先。请注意，如果输入的不同值少于 _N_ 个，则输出的元素可能少于 _N_ 个。

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

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

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

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

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

  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	(10)
hash_first_last	一元	数值，二进制	结构体	ScalarAggregateOptions	(10)
hash_last	一元	数值，二进制	输入类型	ScalarAggregateOptions	(10)
hash_list	一元	任意	输入类型列表		(3)
hash_max	一元	非嵌套、非二进制/字符串类型	输入类型	ScalarAggregateOptions
hash_mean	一元	数值	Decimal/Float64	ScalarAggregateOptions	(4)
hash_min	一元	非嵌套、非二进制/字符串类型	输入类型	ScalarAggregateOptions
hash_min_max	一元	非嵌套类型	结构体	ScalarAggregateOptions	(5)
hash_one	一元	任意	输入类型		(6)
hash_product	一元	数值	数值	ScalarAggregateOptions	(7)
hash_stddev	一元	数值	Float64	VarianceOptions	(8)
hash_sum	一元	数值	数值	ScalarAggregateOptions	(7)
hash_tdigest	一元	数值	FixedSizeList[Float64]	TDigestOptions	(9)
hash_variance	一元	数值	Float64	VarianceOptions	(8)

• (1) 如果将空值考虑在内，通过将 ScalarAggregateOptions::skip_nulls 设置为 false，则应用 克莱尼逻辑。min_count 选项将被忽略。

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

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

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

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

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

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

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

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

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

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

  Decimal 参数首先会被转换为 Float64。

逐元素（“标量”）函数

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

• 标量输入产生标量输出

• 数组输入产生数组输出

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

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

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

• (标量, 数组) 和 (数组, 标量) 产生数组输出。标量输入的处理方式就像它是一个与另一个输入长度 N 相同的数组，其中相同的值重复 N 次。

算术函数

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

这些函数的默认变体不检测溢出（结果通常会回绕）。大多数函数也提供溢出检查变体，后缀为 _checked，当检测到溢出时，它会返回 Invalid Status。

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

函数名称	元数	输入类型	输出类型	备注
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	比例 = max(s1, s2) 精度 = max(p1-s1, p2-s2) + 1 + 比例
  multiply	比例 = s1 + s2 精度 = p1 + p2 + 1
  divide	比例 = max(4, s1 + p2 - s2 + 1) 精度 = p1 - s1 + s2 + 比例

  它与 Redshift 的 decimal 提升规则兼容。对于 add、subtract 和 multiply 运算，所有 decimal 数字都将保留。 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) 舍入到 RoundOptions 的 ndigits 选项指定的位数，其中负值对应于非小数部分的位数。例如，-2 对应于舍入到最接近的 100 的倍数（将个位和十位归零）。ndigits 的默认值为 0，表示舍入到最接近的整数。对于整数输入，非负的 ndigits 值将被忽略，并且输入将保持不变。对于整数输入，如果 -ndigits 大于输入类型可以容纳的最大位数，则返回错误。

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

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

对于 round 函数，可以使用以下舍入模式。平局决胜模式以 HALF 为前缀，并将非平局舍入到最接近的整数。示例值针对 ndigits 和 multiple 的默认值给出。

舍入模式	执行的操作	示例值
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 规则舍入关系	3.5 -> 3, 4.5 -> 4, -3.5 -> -4, -4.5 -> -5
HALF_UP	使用 UP 规则舍入关系	3.5 -> 4, 4.5 -> 5, -3.5 -> -3, -4.5 -> -4
HALF_TOWARDS_ZERO	使用 TOWARDS_ZERO 规则舍入关系	3.5 -> 3, 4.5 -> 4, -3.5 -> -3, -4.5 -> -4
HALF_TOWARDS_INFINITY	使用 TOWARDS_INFINITY 规则舍入关系	3.5 -> 4, 4.5 -> 5, -3.5 -> -4, -4.5 -> -5
HALF_TO_EVEN	舍入到最接近的偶数	3.5 -> 4, 4.5 -> 4, -3.5 -> -4, -4.5 -> -4
HALF_TO_ODD	舍入到最接近的奇数	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	不适用	舍入到 2 的倍数

对数函数

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

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

函数名称	元数	输入类型	输出类型
ln（自然对数）	一元	Float32/Float64/Decimal	Float32/Float64
ln_checked（带检查的自然对数）	一元	Float32/Float64/Decimal	Float32/Float64
log10（以 10 为底的对数）	一元	Float32/Float64/Decimal	Float32/Float64
log10_checked（带检查的以 10 为底的对数）	一元	Float32/Float64/Decimal	Float32/Float64
log1p(ln(1+x))	一元	Float32/Float64/Decimal	Float32/Float64
log1p_checked(带检查的ln(1+x))	一元	Float32/Float64/Decimal	Float32/Float64
log2（以 2 为底的对数）	一元	Float32/Float64/Decimal	Float32/Float64
log2_checked（带检查的以 2 为底的对数）	一元	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

比较

这些函数需要两个数字类型的输入（在这种情况下，它们将在比较之前转换为公共数字类型），或者两个二进制或字符串类型的输入，或者两个时间类型的输入。如果任何输入是字典编码的，它将被展开用于比较。如果一对输入元素中的任何一个是 null，则对应的输出元素是 null。 十进制参数将以与 add 和 subtract 相同的方式进行提升。

函数名称	元数	输入类型	输出类型
equal（等于）	二元	数字、时间、二进制和字符串类型	布尔值
greater（大于）	二元	数字、时间、二进制和字符串类型	布尔值
greater_equal（大于等于）	二元	数字、时间、二进制和字符串类型	布尔值
less（小于）	二元	数字、时间、二进制和字符串类型	布尔值
less_equal（小于等于）	二元	数字、时间、二进制和字符串类型	布尔值
not_equal（不等于）	二元	数字、时间、二进制和字符串类型	布尔值

这些函数接受任意数量的数字类型输入（在这种情况下，它们将在比较之前转换为公共数字类型）或时间类型输入。如果任何输入是字典编码的，它将被展开用于比较。

函数名称	元数	输入类型	输出类型	选项类	备注
max_element_wise（按元素取最大值）	可变参数	数字、时间、二进制和字符串类型	数字或时间类型	ElementWiseAggregateOptions（按元素聚合选项）	(1)
min_element_wise（按元素取最小值）	可变参数	数字、时间、二进制和字符串类型	数字或时间类型	ElementWiseAggregateOptions（按元素聚合选项）	(1)

• （1）默认情况下，跳过 null 值（但可以将内核配置为传播 null 值）。 对于浮点值，NaN 将优先于 null，但不优先于任何其他值。 对于二进制和字符串类型值，仅支持相同类型的参数。

逻辑函数

这些函数的正常行为是，如果任何输入为 null，则发出 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（与）	二元	布尔值	布尔值
and_kleene（Kleene 与）	二元	布尔值	布尔值
and_not（与非）	二元	布尔值	布尔值
and_not_kleene（Kleene 与非）	二元	布尔值	布尔值
invert（反转）	一元	布尔值	布尔值
or（或）	二元	布尔值	布尔值
or_kleene（Kleene 或）	二元	布尔值	布尔值
xor（异或）	二元	布尔值	布尔值

字符串谓词

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

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

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

• （1）也匹配所有数字 ASCII 字符和所有 ASCII 数字。

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

• （3）目前与 utf8_is_decimal 相同。

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

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

函数名称	元数	输入类型	输出类型	备注
ascii_is_title（ASCII 标题格式）	一元	字符串类型	布尔值	(1)
utf8_is_title(Unicode 标题格式)	一元	字符串类型	布尔值	(1)

• （1）当且仅当输入字符串元素为标题格式时，输出为 true，即任何单词以大写字符开头，后跟小写字符。单词边界由非大小写字符定义。

第三组函数以逐字节的方式检查字符串元素

函数名称	元数	输入类型	输出类型	备注
string_is_ascii(字符串是ASCII码)	一元	字符串类型	布尔值	(1)

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

字符串转换

函数名称	元数	输入类型	输出类型	选项类	备注
ascii_capitalize（ASCII 首字母大写）	一元	字符串类型	字符串类型		(1)
ascii_lower（ASCII 转换为小写）	一元	字符串类型	字符串类型		(1)
ascii_reverse（ASCII 反转）	一元	字符串类型	字符串类型		(2)
ascii_swapcase（ASCII 大小写互换）	一元	字符串类型	字符串类型		(1)
ascii_title（ASCII 标题格式）	一元	字符串类型	字符串类型		(1)
ascii_upper（ASCII 转换为大写）	一元	字符串类型	字符串类型		(1)
binary_length（二进制长度）	一元	二进制或字符串类型	Int32 或 Int64		(3)
binary_repeat（二进制重复）	二元	二进制/字符串（参数 0）; 整数（参数 1）	二进制或字符串类型		(4)
binary_replace_slice（二进制替换切片）	一元	字符串类型	二进制或字符串类型	ReplaceSliceOptions（替换切片选项）	(5)
binary_reverse（二进制反转）	一元	二元	二元		(6)
replace_substring（替换子字符串）	一元	字符串类型	字符串类型	ReplaceSubstringOptions（替换子字符串选项）	(7)
replace_substring_regex（使用正则表达式替换子字符串）	一元	字符串类型	字符串类型	ReplaceSubstringOptions（替换子字符串选项）	(8)
utf8_capitalize（Unicode 首字母大写）	一元	字符串类型	字符串类型		(9)
utf8_length(Unicode 长度)	一元	字符串类型	Int32 或 Int64		(10)
utf8_lower（Unicode 转换为小写）	一元	字符串类型	字符串类型		(9)
utf8_replace_slice（Unicode 替换切片）	一元	字符串类型	字符串类型	ReplaceSliceOptions（替换切片选项）	(7)
utf8_reverse（Unicode 反转）	一元	字符串类型	字符串类型		(11)
utf8_swapcase（Unicode 大小写互换）	一元	字符串类型	字符串类型		(9)
utf8_title（Unicode 标题格式）	一元	字符串类型	字符串类型		(9)
utf8_upper（Unicode 转换为大写）	一元	字符串类型	字符串类型		(9)

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

• （2）ASCII 输入反转到输出。如果存在非 ASCII 字符，将返回 Invalid Status。

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

• （4）将输入的二进制字符串重复指定的次数。

• （5）将子字符串的切片从 ReplaceSliceOptions::start（包括）到 ReplaceSliceOptions::stop（不包括）替换为 ReplaceSubstringOptions::replacement。二进制内核以字节为单位测量切片，而 UTF8 内核以代码单元为单位测量切片。

• （6）执行字节级反转。

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

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

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

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

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

字符串填充

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

函数名称	元数	输入类型	输出类型	选项类
ascii_center	一元	字符串类型	字符串类型	PadOptions
ascii_lpad	一元	字符串类型	字符串类型	PadOptions
ascii_rpad	一元	字符串类型	字符串类型	PadOptions
utf8_center	一元	字符串类型	字符串类型	PadOptions
utf8_lpad	一元	字符串类型	字符串类型	PadOptions
utf8_rpad	一元	字符串类型	字符串类型	PadOptions

字符串修剪

这些函数修剪两侧（trim）、左侧（ltrim）或右侧（rtrim）的字符。

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

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

• (2) 只修剪掉 ASCII 空白字符（'\t'、'\n'、'\v'、'\f'、'\r' 和 ' '）。

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

• (4) 只修剪掉 Unicode 空白字符。

字符串拆分

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

函数名称	元数	输入类型	输出类型	选项类	备注
ascii_split_whitespace	一元	字符串类型	类列表	SplitOptions	(1)
split_pattern	一元	二进制或字符串类型	类列表	SplitPatternOptions	(2)
split_pattern_regex	一元	二进制或字符串类型	类列表	SplitPatternOptions	(3)
utf8_split_whitespace	一元	字符串类型	类列表	SplitOptions	(4)

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

• (2) 当找到确切的模式时，字符串将被拆分（模式本身不包含在输出中）。

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

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

字符串组件提取

函数名称	元数	输入类型	输出类型	选项类	备注
extract_regex	一元	二进制或字符串类型	结构体	ExtractRegexOptions	(1)

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

字符串连接

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

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	备注
binary_join	二元	二进制或字符串类型的列表	字符串类型	字符串类型		(1)
binary_join_element_wise	可变参数	二进制或字符串类型 (可变参数)	二进制或字符串类型	二进制或字符串类型	JoinOptions	(2)

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

• (2) 所有参数都按元素进行连接，最后一个参数被视为分隔符（标量在任一情况下都会被循环使用）。空分隔符发出空值。如果任何其他参数为空，则默认情况下相应的输出将为空，但可以跳过它或将其替换为给定的字符串。

字符串切片

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

函数名称	元数	输入类型	输出类型	选项类	备注
binary_slice	一元	类二进制	类二进制	SliceOptions	(1)
utf8_slice_codeunits	一元	字符串类型	字符串类型	SliceOptions	(2)

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

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

包含测试

函数名称	元数	输入类型	输出类型	选项类	备注
count_substring	一元	二进制或字符串类型	Int32 或 Int64	MatchSubstringOptions	(1)
count_substring_regex	一元	二进制或字符串类型	Int32 或 Int64	MatchSubstringOptions	(1)
ends_with	一元	二进制或字符串类型	布尔值	MatchSubstringOptions	(2)
find_substring	一元	二进制和字符串类型	Int32 或 Int64	MatchSubstringOptions	(3)
find_substring_regex	一元	二进制和字符串类型	Int32 或 Int64	MatchSubstringOptions	(3)
index_in	一元	布尔值、空值、数值、时间、二进制和字符串类型	Int32	SetLookupOptions	(4)
is_in	一元	布尔值、空值、数值、时间、二进制和字符串类型	布尔值	SetLookupOptions	(5)
match_like	一元	二进制或字符串类型	布尔值	MatchSubstringOptions	(6)
match_substring	一元	二进制或字符串类型	布尔值	MatchSubstringOptions	(7)
match_substring_regex	一元	二进制或字符串类型	布尔值	MatchSubstringOptions	(8)
starts_with	一元	二进制或字符串类型	布尔值	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中的某个元素时，输出为 true。

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

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

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

分类

函数名称	元数	输入类型	输出类型	选项类	备注
is_finite	一元	空值、数值	布尔值		(1)
is_inf	一元	空值、数值	布尔值		(2)
is_nan	一元	空值、数值	布尔值		(3)
is_null	一元	任意	布尔值	NullOptions	(4)
is_valid	一元	任意	布尔值		(5)
true_unless_null	一元	任意	布尔值		(6)

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

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

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

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

• (5) 当且仅当相应的输入元素为非 null 时，输出为 true，否则为 false。

• (6) 当且仅当相应的输入元素为非 null 时，输出为 true，否则为 null。

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

选择 / 多路复用

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

函数名称	元数	输入类型	输出类型	备注
case_when	可变参数	布尔值结构体 (参数 0), 任意类型 (其余)	输入类型	(1)
choose	可变参数	整数 (参数 0), 固定宽度/二进制类型 (其余)	输入类型	(2)
coalesce	可变参数	任意	输入类型	(3)
if_else	三元运算	布尔值 (参数 0), 任意类型 (其余)	输入类型	(4)

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

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

• (2) 第一个输入必须是整数类型。其余参数可以是任何类型，但必须都相同或可提升为公共类型。第一个输入的每个值（“索引”）都用作其余参数的从零开始的索引（即索引 0 是第二个参数，索引 1 是第三个参数，等等），并且该行的输出值将是所选输入在该行的对应值。如果索引为 null，则输出也将为 null。

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

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

  另请参阅：replace_with_mask。

结构转换

函数名称	元数	输入类型	输出类型	选项类	备注
list_value_length	一元	类列表	Int32 或 Int64		(1)
make_struct	可变参数	任意	结构体	MakeStructOptions	(2)

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

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

转换

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

函数名称	元数	输入类型	输出类型	选项类	备注
ceil_temporal	一元	时间类型	时间类型	RoundTemporalOptions
floor_temporal	一元	时间类型	时间类型	RoundTemporalOptions
round_temporal	一元	时间类型	时间类型	RoundTemporalOptions
cast	一元	多种	可变	CastOptions
strftime	一元	时间类型	字符串	StrftimeOptions	(1)
strptime	一元	字符串类型	时间戳	StrptimeOptions

cast 可用的转换如下所示。在所有情况下，null 输入值都将转换为 null 输出值。

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

真值提取

输入类型	输出类型	备注
二进制和字符串类型	布尔值	(1)
数值	布尔值	(2)

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

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

同类转换

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

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

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

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

• (4) 根据给定的 CastOptions 启用溢出和截断检查。

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

字符串表示形式

输入类型	输出类型	备注
布尔值	字符串类型
数值	字符串类型

通用转换

输入类型	输出类型	备注
字典	字典值类型	(1)
扩展类型	扩展存储类型
结构体	结构体	(2)
类列表	类列表或 (Large)ListView	(3)
(Large)ListView	类列表或 (Large)ListView	(4)
Map	Map 或包含两个字段的结构体列表	(5)
Null	任意
任意	扩展类型	(6)

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

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

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

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

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

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

时间成分提取

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

函数名称	元数	输入类型	输出类型	选项类	备注
day	一元	时间类型	Int64
day_of_week	一元	时间类型	Int64	DayOfWeekOptions	(1)
day_of_year	一元	时间类型	Int64
hour	一元	时间戳，时间	Int64
is_dst	一元	时间戳	布尔值
iso_week	一元	时间类型	Int64		(2)
iso_year	一元	时间类型	Int64		(2)
iso_calendar	一元	时间类型	结构体		(3)
is_leap_year	一元	时间戳，日期	布尔值
microsecond	一元	时间戳，时间	Int64
millisecond	一元	时间戳，时间	Int64
minute	一元	时间戳，时间	Int64
month	一元	时间类型	Int64
nanosecond	一元	时间戳，时间	Int64
quarter	一元	时间类型	Int64
second	一元	时间戳，时间	Int64
subsecond	一元	时间戳，时间	Float64
us_week	一元	时间类型	Int64		(4)
us_year	一元	时间类型	Int64		(4)
week	一元	时间戳	Int64	WeekOptions	(5)
year	一元	时间类型	Int64
year_month_day	一元	时间类型	结构体		(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 天或更多）在 1 月。ISO 年从第一个 ISO 周开始。ISO 周从星期一开始。有关更多详细信息，请参阅ISO 8601 周日期定义。

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

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

• (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 周）必须完全在 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	二元	时间类型	日期时间间隔
days_between	二元	时间戳，日期	Int64
hours_between	二元	时间类型	Int64
microseconds_between	二元	时间类型	Int64
milliseconds_between	二元	时间类型	Int64
minutes_between	二元	时间类型	Int64
month_day_nano_interval_between	二元	时间类型	月日纳秒间隔
month_interval_between	二元	时间戳，日期	月间隔
nanoseconds_between	二元	时间类型	Int64
quarters_between	二元	时间戳，日期	Int64
seconds_between	二元	时间类型	Int64
weeks_between	二元	时间戳，日期	Int64	DayOfWeekOptions
years_between	二元	时间戳，日期	Int64

时区处理

assume_timezone 函数用于处理外部系统产生的“时区无感知”时间戳，将其转换为“时区感知”时间戳（例如，参见 Python 文档中的定义）。

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

local_timestamp 函数将相对于 UTC 的时间戳转换为本地“时区无感知”时间戳。时区取自输入时间戳的时区元数据。此函数与 assume_timezone 相反。请注意：**所有时间函数都对时间戳进行操作，就好像它们位于元数据提供的时区的本地时间一样**。使用 local_timestamp 仅用于外部系统需要本地时间戳的情况。

函数名称	元数	输入类型	输出类型	选项类	备注
assume_timezone（假设时区）	一元	时间戳	时间戳	AssumeTimezoneOptions（假设时区选项）	(1)
local_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（默认值）时，第一个遇到的空值将被传播。当设置为 true 时，输入中的每个空值都会在输出中产生相应的空值，并且不会影响向前累积。

• (2) CumulativeOptions::start 将被忽略.

关联转换

函数名称	元数	输入类型	输出类型	备注
dictionary_encode（字典编码）	一元	布尔值、空值、数值、时间、二进制和字符串类型	字典	(1)
unique（去重）	一元	布尔值、空值、数值、时间、二进制和字符串类型	输入类型	(2)
value_counts（值计数）	一元	布尔值、空值、数值、时间、二进制和字符串类型	输入类型	(3)

• (1) 输出为 Dictionary(Int32, input type)。如果输入已经是字典数组，则此操作无效。

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

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

选择

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

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	备注
array_filter（数组过滤）	二元	任意	布尔值	输入类型 1	FilterOptions（过滤选项）	(2)
array_take（数组提取）	二元	任意	Integer (整数)	输入类型 1	TakeOptions（提取选项）	(3)
drop_null（删除空值）	一元	任意		输入类型 1		(1)
filter（过滤）	二元	任意	布尔值	输入类型 1	FilterOptions（过滤选项）	(2)
take（提取）	二元	任意	Integer (整数)	输入类型 1	TakeOptions（提取选项）	(3)

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

• (2) 当且仅当输入 2（过滤器）中的相应元素为 true 时，输入 1（值）中的每个元素才会追加到输出中。可以使用 FilterOptions 配置如何处理过滤器中的空值。

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

包含测试

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

函数名称	元数	输入类型	输出类型	选项类	备注
indices_nonzero (非零索引)	一元	Boolean, Null, Numeric, Decimal (布尔值、空值、数值、十进制数)	UInt64 (无符号64位整数)

排序和分区

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

注意

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

函数名称	元数	输入类型	输出类型	选项类	备注
array_sort_indices (数组排序索引)	一元	Boolean, Numeric, Temporal, Binary- and String-like (布尔值、数值、时间、二进制和字符串类)	UInt64 (无符号64位整数)	ArraySortOptions (数组排序选项)	(1) (2)
partition_nth_indices (第N个分区索引)	一元	Boolean, Numeric, Temporal, Binary- and String-like (布尔值、数值、时间、二进制和字符串类)	UInt64 (无符号64位整数)	PartitionNthOptions (第N个分区选项)	(3)
rank (排名)	一元	Boolean, Numeric, Temporal, Binary- and String-like (布尔值、数值、时间、二进制和字符串类)	UInt64 (无符号64位整数)	RankOptions (排名选项)	(4)
select_k_unstable (不稳定选择K个)	一元	Boolean, Numeric, Temporal, Binary- and String-like (布尔值、数值、时间、二进制和字符串类)	UInt64 (无符号64位整数)	SelectKOptions (选择K个选项)	(5) (6)
sort_indices (排序索引)	一元	Boolean, Numeric, Temporal, Binary- and String-like (布尔值、数值、时间、二进制和字符串类)	UInt64 (无符号64位整数)	SortOptions (排序选项)	(1) (5)

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

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

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

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

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

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

结构转换

函数名称	元数	输入类型	输出类型	选项类	备注
list_element (列表元素)	二元	List-like (Arg 0), Integral (Arg 1) (类似列表的参数 0，整数参数 1)	List value type (列表值类型)		(1)
list_flatten (列表扁平化)	一元	类列表	List value type (列表值类型)		(2)
list_parent_indices (列表父索引)	一元	类列表	Int64		(3)
list_slice (列表切片)	一元	类列表	类列表	ListSliceOptions (列表切片选项)	(4)
map_lookup (映射查找)	一元	Map	Computed (已计算)	MapLookupOptions (映射查找选项)	(5)
struct_field (结构字段)	一元	Struct or Union (结构或联合)	Computed (已计算)	StructFieldOptions (结构字段选项)	(6)

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

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

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

• (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) 将有效值向前/向后填充以填充空值。

• (2) 对于输入 2 中相应的布尔值为 true 的输入 1 中的每个元素，将用输入 3 中的下一个值替换。输入 2 中的空值将导致输出中相应的空值。

  另见：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。