计算函数

通用计算 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 列与 int16 列进行比较可能会发出错误，如果其中一个 uint64 值无法表示为公共类型 int64（例如，2 ** 63）。

可用函数

类型类别

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

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

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

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

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

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

• “嵌套”：类列表（包括 FixedSizeList）、结构体、联合体和相关类型（如 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	IndexOptions	(3)
last	一元	数字、二进制	标量输入类型	ScalarAggregateOptions	(11)
max	一元	非嵌套类型	标量输入类型	ScalarAggregateOptions
mean	一元	数字	标量 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": input type, "max": input type} 结构体。

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

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

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

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

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

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

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

  十进制参数首先转换为 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，则应用 Kleene 逻辑。不会考虑 min_count 选项。

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

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

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

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

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

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

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

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

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

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

  十进制参数首先转换为 Float64。

逐元素（“标量”）函数

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

• 标量输入产生标量输出

• 数组输入产生数组输出

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

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

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

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

算术函数

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

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

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

函数名称	元数	输入类型	输出类型	说明
abs	一元	数值/持续时间	数值/持续时间
abs_checked	一元	数值/持续时间	数值/持续时间
add	二元	数值/时间	数值/时间	(1)
add_checked	二元	数值/时间	数值/时间	(1)
divide	二元	数值/时间	数值/时间	(1)
divide_checked	二元	数值/时间	数值/时间	(1)
exp	一元	数字	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 的十进制提升规则兼容。所有十进制数字都会保留用于 add、subtract 和 multiply 运算。divide 的结果精度至少为两个操作数的精度之和，并保留足够的比例。如果结果精度超出十进制值的范围，则返回错误。

• (2) 对于非零输入，输出为 (-1,1) 之一，对于零输入，输出为 0。NaN 值返回 NaN。整数和十进制值返回 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 的默认值。

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	二元	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

比较

这些函数期望两个数值类型的输入（在这种情况下，它们将在比较之前转换为 通用数值类型），或两个二进制或字符串类型的输入，或两个时间类型的输入。如果任何输入是字典编码的，它将被扩展以用于比较。如果一对中的任何输入元素为 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），其中 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	二元	布尔值	布尔值
and_kleene	二元	布尔值	布尔值
and_not	二元	布尔值	布尔值
and_not_kleene	二元	布尔值	布尔值
invert	一元	布尔值	布尔值
or	二元	布尔值	布尔值
or_kleene	二元	布尔值	布尔值
xor	二元	布尔值	布尔值

字符串谓词

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

第一组函数基于每个字符，如果输入仅包含给定类别的字符，则在输出中发出真值。

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

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

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

• (3) 此处目前与 utf8_is_decimal 相同。

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

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

函数名称	元数	输入类型	输出类型	说明
ascii_is_title	一元	字符串状	布尔值	(1)
utf8_is_title	一元	字符串状	布尔值	(1)

• (1) 如果输入字符串元素为标题大小写，则输出为真值，即任何单词都以大写字符开头，后面跟着小写字符。单词边界由非大小写字符定义。

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

函数名称	元数	输入类型	输出类型	说明
string_is_ascii	一元	字符串状	布尔值	(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	二元	二进制/字符串（参数 0）；整数（参数 1）	二进制或字符串状		(4)
binary_replace_slice	一元	字符串状	二进制或字符串状	ReplaceSliceOptions	(5)
binary_reverse	一元	二元	二元		(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) 输出是每个输入元素的字节物理长度。输出类型是 Int32（对于二进制/字符串），Int64（对于 LargeBinary/LargeString）。

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

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

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

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

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

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

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

• (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 为真值时，拆分从字符串末尾开始进行；这仅在给出正数的 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) 将字符串切片为由 (start, stop, step) 定义的子字符串，如 SliceOptions 所示，其中 start 和 stop 以字节为单位测量。空输入发出空值。

• (2) 将字符串切片为由 (start, stop, step) 定义的子字符串，如 SliceOptions 所示，其中 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 出现的次数。输出类型是 Int32（对于二进制/字符串），Int64（对于 LargeBinary/LargeString）。

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

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

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

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

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

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

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

分类

函数名称	元数	输入类型	输出类型	选项类	说明
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）时，输出为 true。因此，对于 Decimal 和整数输入，这始终返回 true。

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

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

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

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

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

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

选择 / 多路复用

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

函数名称	元数	输入类型	输出类型	说明
case_when	变长参数	Boolean 结构 (Arg 0)，Any (rest)	输入类型	(1)
choose	变长参数	Integral (Arg 0)，Fixed-width/Binary-like (rest)	输入类型	(2)
coalesce	变长参数	任何	输入类型	(3)
if_else	三元运算符	Boolean (Arg 0)，Any (rest)	输入类型	(4)

• (1) 此函数类似于 SQL “case when” 语句或 switch-case。输入是“条件”值，它是一个 Boolean 结构，后面是每个“分支”的值。对于条件结构的每个子节点，必须正好有一个值参数，或者比子节点多一个值参数（在这种情况下，我们有一个“else”或“default”值）。输出与值输入的类型相同；每行将是第一个值数据的相应值，其对应的 Boolean 为 true，或者来自“default”输入的相应值，或者在其他情况下为 null。

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

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

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

• (4) 第一个输入必须是 Boolean 标量或数组。第二个和第三个输入可以是标量或数组，并且必须类型相同。输出是一个数组（如果所有输入都是标量，则为标量），其类型与第二个/第三个输入相同。如果第一个输入存在 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	一元	Temporal	Temporal	RoundTemporalOptions
floor_temporal	一元	Temporal	Temporal	RoundTemporalOptions
round_temporal	一元	Temporal	Temporal	RoundTemporalOptions
cast	一元	许多	可变	CastOptions
strftime	一元	Temporal	String	StrftimeOptions	(1)
strptime	一元	字符串状	Timestamp	StrptimeOptions

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

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

真值提取

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

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

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

同类转换

输入类型	输出类型	说明
Int32	32 位 Temporal	(1)
Int64	64 位 Temporal	(1)
(Large)Binary	(Large)String	(2)
(Large)String	(Large)Binary	(3)
数字	数字	(4) (5)
32 位 Temporal	Int32	(1)
64 位 Temporal	Int64	(1)
Temporal	Temporal	(4) (5)

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

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

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

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

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

字符串表示形式

输入类型	输出类型	说明
布尔值	字符串状
数字	字符串状

通用转换

输入类型	输出类型	说明
Dictionary	Dictionary 值类型	(1)
Extension	Extension 存储类型
结构体	结构体	(2)
列表状	List-like 或 (Large)ListView	(3)
(Large)ListView	List-like 或 (Large)ListView	(4)
Map	Map 或两个字段结构的 List	(5)
Null	任何
任何	Extension	(6)

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

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

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

• (4) 如果输出类型是 list-like，则可能需要重新构建偏移量（因此是值数组）以使其排序并适当间隔。如果输出类型是 list-view 类型，则偏移量和大小保持不变。在任何情况下，列表值都会从输入值类型转换为输出值类型（如果有转换可用）。

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

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

时间组件提取

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

函数名称	元数	输入类型	输出类型	选项类	说明
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 天或更多）都在 1 月。ISO 年从第一个 ISO 星期开始。ISO 星期从星期一开始。有关更多详细信息，请参阅 ISO 8601 星期日期定义。

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

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

• (5) 返回星期编号，允许设置多个参数。如果 WeekOptions::week_starts_monday 为 true，则星期从星期一开始，否则为星期日。如果 WeekOptions::count_from_zero 为 true，则当年落在上一年最后一个 ISO 星期的日期将被编号为第 0 周，否则为第 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	二元	Temporal	DayTime 间隔
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 间隔
month_interval_between	二元	Timestamp, Date	Month 间隔
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（默认值）时，将传播遇到的第一个空值。当设置为 true 时，输入中的每个空值都会在输出中产生一个相应的空值，并且不会影响累积向前。

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

结合变换

函数名称	元数	输入类型	输出类型	说明
dictionary_encode	一元	布尔值、空值、数字、时间、二进制和字符串状	Dictionary	(1)
unique	一元	布尔值、空值、数字、时间、二进制和字符串状	输入类型	(2)
value_counts	一元	布尔值、空值、数字、时间、二进制和字符串状	输入类型	(3)

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

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

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

选择

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

函数名称	元数	输入类型 1	输入类型 2	输出类型	选项类	说明
array_filter	二元	任何	布尔值	输入类型 1	FilterOptions	(2)
array_take	二元	任何	整数	输入类型 1	TakeOptions	(3)
drop_null	一元	任何		输入类型 1		(1)
filter	二元	任何	布尔值	输入类型 1	FilterOptions	(2)
take	二元	任何	整数	输入类型 1	TakeOptions	(3)

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

• (2) 只有当输入 2（过滤器）中的对应元素为真时，才会将输入 1（值）中的每个元素追加到输出中。如何处理过滤器中的空值可以使用 FilterOptions 进行配置。

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

包含测试

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

函数名称	元数	输入类型	输出类型	选项类	说明
indices_nonzero	一元	布尔值、空值、数字、小数	UInt64

排序和分区

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

注意

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

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

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

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

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

• (4) 输出是一维的基于 1 的数值排名数组

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

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

结构变换

函数名称	元数	输入类型	输出类型	选项类	说明
list_element	二元	列表类型（参数 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 的数组，该数组在索引 n 处有效，当且仅当子数组 a 在索引 n 处有效，并且索引 n 处的类型代码为 2。

  • 索引 1, 1 将产生类型为 float64 的数组，该数组的有效性位图是外部结构体、结构体 b 以及子项 d 的位图的交集。

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

  • 索引 0 将产生类型为 int32 的数组，该数组在索引 n 处有效，当且仅当子数组 a 在索引 n 处有效，并且索引 n 处的类型代码为 2。

  • 索引 2 和 7 无效。

替换函数

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

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

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

• (2) 将输入 2 中对应布尔值为真的输入 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。