计算函数

通用计算API

另请参阅

计算函数API参考

函数和函数注册表

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

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

计算初始化

计算库需要调用arrow::compute::Initialize()才能将各个函数注册到全局FunctionRegistry中，否则将只提供Arrow核心功能所需的函数。

注意

Arrow核心功能所需的函数集是库的实现细节，不应视为稳定。

输入形状

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

特别注意，如果uint64的值不能表示为通用类型int64（例如，2 ** 63），则比较uint64列与int16列可能会发出错误。

可用函数

类型类别

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

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

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

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

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

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

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

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

聚合

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

函数名称	元数	输入类型	输出类型	选项类	备注
all	一元	Boolean	标量布尔	ScalarAggregateOptions	(1)
any	一元	Boolean	标量布尔	ScalarAggregateOptions	(1)
approximate_median	一元	数值型	标量Float64	ScalarAggregateOptions
count	一元	任何	标量Int64	CountOptions	(2)
count_all	零元		标量Int64
count_distinct	一元	非嵌套类型	标量Int64	CountOptions	(2)
first	一元	数值型，二进制型	标量输入类型	ScalarAggregateOptions	(3)
first_last	一元	数值型，二进制型	标量Struct	ScalarAggregateOptions	(3)
index	一元	任何	标量Int64	IndexOptions	(4)
kurtosis	一元	数值型	标量Float64	SkewOptions	(12)
last	一元	数值型，二进制型	标量输入类型	ScalarAggregateOptions	(3)
max	一元	非嵌套类型	标量输入类型	ScalarAggregateOptions
mean	一元	数值型	标量Decimal/Float64	ScalarAggregateOptions	(5)
min	一元	非嵌套类型	标量输入类型	ScalarAggregateOptions
min_max	一元	非嵌套类型	标量Struct	ScalarAggregateOptions	(6)
模式	一元	数值型	结构体	ModeOptions	(7)
pivot_wider	Binary	二进制型、字符串型、整数型（参数0）；任何类型（参数1）	标量Struct	PivotWiderOptions	(8)
product	一元	数值型	标量数值型	ScalarAggregateOptions	(9)
quantile	一元	数值型	标量数值型	QuantileOptions	(11)
skew	一元	数值型	标量Float64	SkewOptions	(12)
stddev	一元	数值型	标量Float64	VarianceOptions	(12)
sum	一元	数值型	标量数值型	ScalarAggregateOptions	(9) (10)
tdigest	一元	数值型	Float64	TDigestOptions	(13)
variance	一元	数值型	标量Float64	VarianceOptions	(12)

• (1) 如果考虑空值，通过将ScalarAggregateOptions参数skip_nulls = false，则应用克莱尼逻辑。min_count选项不被尊重。

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

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

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

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

• (6) 输出为{"min": 输入类型, "max": 输入类型}结构体。

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

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

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

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

• (10) 对于Decimal输入，输出精度增加到输入类型宽度的最大精度。例如，一个decimal128(3, 2)的数组将返回一个decimal128(38, 2)标量。

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

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

• (13) 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	一元	Boolean	Boolean	ScalarAggregateOptions	(1)
hash_any	一元	Boolean	Boolean	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	Binary	二进制型、字符串型、整数型（参数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，则应用克莱尼逻辑。min_count选项不被尊重。

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

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

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

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

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

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

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

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

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

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

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

逐元素（“标量”）函数

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

• 标量输入生成标量输出

• 数组输入生成数组输出

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

• (scalar, scalar)输入生成标量输出

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

• (scalar, array)和(array, scalar)生成数组输出。标量输入被处理为与另一个输入长度N相同的数组，其中相同的值重复N次。

算术函数

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

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

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

函数名称	元数	输入类型	输出类型	备注
abs	一元	数值型/持续时间型	数值型/持续时间型
abs_checked	一元	数值型/持续时间型	数值型/持续时间型
add	Binary	数值型/时间型	数值型/时间型	(1)
add_checked	Binary	数值型/时间型	数值型/时间型	(1)
divide	Binary	数值型/时间型	数值型/时间型	(1)
divide_checked	Binary	数值型/时间型	数值型/时间型	(1)
exp	一元	数值型	Float32/Float64
expm1	一元	数值型	Float32/Float64
multiply	Binary	数值型/时间型	数值型/时间型	(1)
multiply_checked	Binary	数值型/时间型	数值型/时间型	(1)
negate	一元	数值型/持续时间型	数值型/持续时间型
negate_checked	一元	有符号数值型/持续时间型	有符号数值型/持续时间型
power	Binary	数值型	数值型
power_checked	Binary	数值型	数值型
sign	一元	数值型/持续时间型	Int8/Float16/Float32/Float64	(2)
sqrt	一元	数值型	数值型
sqrt_checked	一元	数值型	数值型
subtract	Binary	数值型/时间型	数值型/时间型	(1)
subtract_checked	Binary	数值型/时间型	数值型/时间型	(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的十进制提升规则兼容。对于add、subtract和multiply操作，所有十进制数字都保留。 divide的结果精度至少是两个操作数精度之和，并保留足够的比例。如果结果精度超出十进制值范围，则返回错误。

• (2) 对于非零输入，输出为(-1,1)中的任意一个，对于零输入，输出为0。NaN值返回NaN。整数和十进制值返回Int8形式的符号，浮点值返回与输入值相同类型的符号。

位函数

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

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

舍入函数

舍入函数根据舍入准则将数值输入位移到具有更简单表示的近似值。

函数名称	元数	输入类型	输出类型	选项类	备注
ceil	一元	数值型	Float32/Float64/Decimal
floor	一元	数值型	Float32/Float64/Decimal
round	一元	数值型	输入类型	RoundOptions	(1)(2)
round_to_multiple	一元	数值型	输入类型	RoundToMultipleOptions	(1)(3)
round_binary	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的默认值给出的。

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规则舍入	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	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	Binary	Float32/Float64/Decimal	Float32/Float64
logb_checked	Binary	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	Binary	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	Binary	数值型、时间型、二进制和字符串类似型	Boolean
greater	Binary	数值型、时间型、二进制和字符串类似型	Boolean
greater_equal	Binary	数值型、时间型、二进制和字符串类似型	Boolean
less	Binary	数值型、时间型、二进制和字符串类似型	Boolean
less_equal	Binary	数值型、时间型、二进制和字符串类似型	Boolean
not_equal	Binary	数值型、时间型、二进制和字符串类似型	Boolean

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

函数名称	元数	输入类型	输出类型	选项类	备注
max_element_wise	可变参数	数值型、时间型、二进制和字符串类似型	数值型或时间型	ElementWiseAggregateOptions	(1)
min_element_wise	可变参数	数值型、时间型、二进制和字符串类似型	数值型或时间型	ElementWiseAggregateOptions	(1)

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

逻辑函数

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

其中一些也提供了克莱尼逻辑变体（后缀为_kleene），其中null被解释为“未定义”。这是SQL系统以及R和Julia等使用的null解释。

因此，对于克莱尼逻辑变体

• “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	Binary	Boolean	Boolean
and_kleene	Binary	Boolean	Boolean
and_not	Binary	Boolean	Boolean
and_not_kleene	Binary	Boolean	Boolean
invert	一元	Boolean	Boolean
or	Binary	Boolean	Boolean
or_kleene	Binary	Boolean	Boolean
xor	Binary	Boolean	Boolean

字符串谓词

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

第一组函数逐字符操作，如果输入只包含给定类别的字符，则在输出中发出true

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

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

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

• (3) 这目前与utf8_is_decimal相同。

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

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

函数名称	元数	输入类型	输出类型	备注
ascii_is_title	一元	字符串类似	Boolean	(1)
utf8_is_title	一元	字符串类似	Boolean	(1)

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

第三组函数逐字节检查字符串元素

函数名称	元数	输入类型	输出类型	备注
string_is_ascii	一元	字符串类似	Boolean	(1)

• (1) 输出为真当且仅当输入字符串元素仅包含ASCII字符，即仅包含[0, 127]范围内的字节。

字符串转换

函数名称	元数	输入类型	输出类型	选项类	备注
ascii_capitalize	一元	字符串类似	字符串类似		(1)
ascii_lower	一元	字符串类似	字符串类似		(1)
ascii_reverse	一元	字符串类似	字符串类似		(2)
ascii_swapcase	一元	字符串类似	字符串类似		(1)
ascii_title	一元	字符串类似	字符串类似		(1)
ascii_upper	一元	字符串类似	字符串类似		(1)
binary_length	一元	二进制或字符串类型	Int32或Int64		(3)
binary_repeat	Binary	二进制/字符串（参数0）；整数（参数1）	二进制或字符串类型		(4)
binary_replace_slice	一元	字符串类似	二进制或字符串类型	ReplaceSliceOptions	(5)
binary_reverse	一元	Binary	Binary		(6)
replace_substring	一元	字符串类似	字符串类似	ReplaceSubstringOptions	(7)
replace_substring_regex	一元	字符串类似	字符串类似	ReplaceSubstringOptions	(8)
utf8_capitalize	一元	字符串类似	字符串类似		(9)
utf8_length	一元	字符串类似	Int32或Int64		(10)
utf8_lower	一元	字符串类似	字符串类似		(9)
utf8_replace_slice	一元	字符串类似	字符串类似	ReplaceSliceOptions	(7)
utf8_reverse	一元	字符串类似	字符串类似		(11)
utf8_swapcase	一元	字符串类似	字符串类似		(9)
utf8_title	一元	字符串类似	字符串类似		(9)
utf8_upper	一元	字符串类似	字符串类似		(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
utf8_zero_fill	一元	字符串类似	字符串类似	ZeroFillOptions

字符串修剪

这些函数修剪两侧的字符（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)
extract_regex_span	一元	二进制或字符串类型	结构体	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	二进制或字符串类型列表	字符串类似	字符串类似		(1)
binary_join_element_wise	可变参数	二进制或字符串类型（可变参数）	二进制或字符串类型	二进制或字符串类型	JoinOptions	(2)

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

• (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	一元	二进制或字符串类型	Boolean	MatchSubstringOptions	(2)
find_substring	一元	二进制和字符串类型	Int32或Int64	MatchSubstringOptions	(3)
find_substring_regex	一元	二进制和字符串类型	Int32或Int64	MatchSubstringOptions	(3)
index_in	一元	布尔型、Null、数值型、时间型、二进制和字符串类似型	Int32	SetLookupOptions	(4)
is_in	一元	布尔型、Null、数值型、时间型、二进制和字符串类似型	Boolean	SetLookupOptions	(5)
match_like	一元	二进制或字符串类型	Boolean	MatchSubstringOptions	(6)
match_substring	一元	二进制或字符串类型	Boolean	MatchSubstringOptions	(7)
match_substring_regex	一元	二进制或字符串类型	Boolean	MatchSubstringOptions	(8)
starts_with	一元	二进制或字符串类型	Boolean	MatchSubstringOptions	(2)

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

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

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

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

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

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

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

• (8) 输出为真当且仅当MatchSubstringOptions::pattern在任意位置匹配相应的输入元素。

分类

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

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

• (2) 输出为真当且仅当相应输入元素为无穷大/-无穷大。因此，对于Decimal和整数输入，这始终返回假。

• (3) 输出为真当且仅当相应输入元素为NaN。因此，对于Decimal和整数输入，这始终返回假。

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

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

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

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

选择/多路复用

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

函数名称	元数	输入类型	输出类型	备注
case_when	可变参数	布尔型结构体（参数0），任何其他类型	输入类型	(1)
choose	可变参数	整数型（参数0），定宽/二进制类似型（其他）	输入类型	(2)
coalesce	可变参数	任何	输入类型	(3)
if_else	三元	布尔型（参数0），任何其他类型	输入类型	(4)

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

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

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

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

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

  另请参阅：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	一元	时间型	String	StrftimeOptions	(1)
strptime	一元	字符串类似	Timestamp	StrptimeOptions

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

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

真值提取

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

• (1) 输出为真当且仅当相应输入值的长度非零。

• (2) 输出为真当且仅当相应输入值为非零。

同类转换

输入类型	输出类型	备注
Int32	32位时间型	(1)
Int64	64位时间型	(1)
(大)二进制	(大)字符串	(2)
(大)字符串	(大)二进制	(3)
数值型	数值型	(4) (5)
32位时间型	Int32	(1)
64位时间型	Int64	(1)
时间型	时间型	(4) (5)

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

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

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

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

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

字符串表示

输入类型	输出类型	备注
Boolean	字符串类似
数值型	字符串类似

通用转换

输入类型	输出类型	备注
字典	字典值类型	(1)
扩展	扩展存储类型
结构体	结构体	(2)
列表类似	列表类似或（大）列表视图	(3)
(大)列表视图	列表类似或（大）列表视图	(4)
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	一元	Timestamp, Time	Int64
is_dst	一元	Timestamp	Boolean
iso_week	一元	时间型	Int64		(2)
iso_year	一元	时间型	Int64		(2)
iso_calendar	一元	时间型	结构体		(3)
is_leap_year	一元	Timestamp, Date	Boolean
microsecond	一元	Timestamp, Time	Int64
millisecond	一元	Timestamp, Time	Int64
minute	一元	Timestamp, Time	Int64
month	一元	时间型	Int64
nanosecond	一元	Timestamp, Time	Int64
quarter	一元	时间型	Int64
second	一元	Timestamp, Time	Int64
subsecond	一元	Timestamp, Time	Float64
us_week	一元	时间型	Int64		(4)
us_year	一元	时间型	Int64		(4)
week	一元	Timestamp	Int64	WeekOptions	(5)
year	一元	时间型	Int64
year_month_day	一元	时间型	结构体		(6)

• (1) 输出星期几的编号。默认情况下，星期从星期一（表示为0）开始，到星期日（表示为6）结束。日期编号可以从0或1开始，具体取决于DayOfWeekOptions::count_from_zero参数。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周，否则为第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	Binary	时间型	天时间隔
days_between	Binary	Timestamp, Date	Int64
hours_between	Binary	时间型	Int64
microseconds_between	Binary	时间型	Int64
milliseconds_between	Binary	时间型	Int64
minutes_between	Binary	时间型	Int64
month_day_nano_interval_between	Binary	时间型	年月纳秒间隔
month_interval_between	Binary	Timestamp, Date	月间隔
nanoseconds_between	Binary	时间型	Int64
quarters_between	Binary	Timestamp, Date	Int64
seconds_between	Binary	时间型	Int64
weeks_between	Binary	Timestamp, Date	Int64	DayOfWeekOptions
years_between	Binary	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 允许在给定日期的时区中，时间戳出现模棱两可或不存在（由于夏令时调整）时，选择其行为。

随机数生成

此函数生成一个在 [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 被忽略。

统计函数

函数名称	元数	输入类型	输出类型	选项类	备注
winsorize	一元	数值型	数值型	WinsorizeOptions	(1)

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

关联变换

函数名称	元数	输入类型	输出类型	备注
dictionary_encode	一元	布尔型、Null、数值型、时间型、二进制和字符串类似型	字典	(1)
unique	一元	布尔型、Null、数值型、时间型、二进制和字符串类似型	输入类型	(2)
value_counts	一元	布尔型、Null、数值型、时间型、二进制和字符串类似型	输入类型	(3)

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

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

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

选择

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

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	备注
array_filter	Binary	任何	Boolean	输入类型 1	FilterOptions	(2)
array_take	Binary	任何	Integer	输入类型 1	TakeOptions	(3)
drop_null	一元	任何		输入类型 1		(1)
filter	Binary	任何	Boolean	输入类型 1	FilterOptions	(2)
inverse_permutation	一元	有符号整数		有符号整数 (4)	InversePermutationOptions	(5)
scatter	Binary	任何	Integer	输入类型 1	ScatterOptions	(6)
take	Binary	任何	Integer	输入类型 1	TakeOptions	(3)

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

• (2) 输入 1（值）中的每个元素，当且仅当输入 2（过滤器）中的相应元素为真时，才附加到输出。如何处理过滤器中的空值可以使用 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，在这种情况下，相应的值将被忽略。如果多个索引指向相同的值，则使用最后一个。

包含性测试

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

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

排序和分区

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

注意

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

函数名称	元数	输入类型	输出类型	选项类	备注
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	Binary	列表类 (参数 0)，整型 (参数 1)	列表值类型		(1)
list_flatten	一元	列表类似	列表值类型		(2)
list_parent_indices	一元	列表类似	Int64		(3)
list_slice	一元	列表类似	列表类似	ListSliceOptions	(4)
map_lookup	一元	Map	计算	MapLookupOptions	(5)
struct_field	一元	结构或联合	计算	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	三元	定宽或二进制	Boolean	输入类型 1	输入类型 1	(2)

• (1) 有效值向前/向后填充空值。

• (2) 输入 1 中对应于输入 2 中布尔值为 true 的每个元素都替换为输入 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。