计算函数#
通用计算 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
调用。
另请参阅
隐式转换#
如果内核与参数类型不完全匹配,则函数可能需要在执行之前转换其参数。 例如,任何内核都不直接支持字典编码数组的比较,但是可以进行隐式转换,从而可以与解码后的数组进行比较。
每个函数都可以根据需要定义隐式转换行为。 例如,比较和算术内核需要类型相同的参数,并通过将其参数提升为可以容纳来自任何输入的任何值的数值类型来支持对不同数值类型的执行。
公共数值类型#
一组输入数值类型的公共数值类型是可以容纳任何输入类型的任何值的最小数值类型。 如果任何输入是浮点类型,则公共数值类型是输入中最宽的浮点类型。 否则,公共数值类型是整数,如果任何输入都是有符号的,则为有符号的。 例如
输入类型 |
公共数值类型 |
注释 |
---|---|---|
int32, int32 |
int32 |
|
int16, int32 |
int32 |
最大宽度为 32,将 LHS 提升为 int32 |
uint16, int32 |
int32 |
一个输入有符号,覆盖无符号 |
uint32, int32 |
int64 |
加宽以适应 uint32 的范围 |
uint16, uint32 |
uint32 |
所有输入均为无符号,保持无符号 |
int16, uint32 |
int64 |
|
uint64, int16 |
int64 |
int64 无法容纳所有 uint64 值 |
float32, int32 |
float32 |
将 RHS 提升为 float32 |
float32, float64 |
float64 |
|
float32, int64 |
float32 |
int64 更宽,仍然提升为 float32 |
特别要注意的是,如果 uint64
列中的某个值不能表示为公共类型 int64
(例如,2 ** 63
),则将 uint64
列与 int16
列进行比较可能会发出错误。
可用函数#
类型类别#
为了避免详尽列出支持的类型,下表使用了一些通用类型类别
“数值”:整数类型(Int8 等)和浮点类型(Float32、Float64,有时为 Float16)。 某些函数还接受 Decimal128 和 Decimal256 输入。
“时间”:日期类型(Date32、Date64)、时间类型(Time32、Time64)、时间戳、持续时间、间隔。
“类似二进制”:二进制、大二进制,有时也是固定大小二进制。
“类似字符串”:字符串、大字符串。
“类似列表”:列表、大列表、列表视图、大列表视图,有时也是固定大小列表。
“嵌套”:类似列表(包括固定大小列表)、结构体、联合,以及相关类型(如映射)。
如果您不确定函数是否支持具体的输入类型,我们建议您尝试一下。 不支持的输入类型会返回 TypeError
Status
。
聚合#
标量聚合对(分块)数组或标量值进行操作,并将输入缩减为单个输出值。
(1) 如果通过设置 ScalarAggregateOptions 参数 skip_nulls = false 来考虑空值,则应用 Kleene 逻辑。 不遵守 min_count 选项。
(2) CountMode 控制是仅计算非空值(默认值)、仅计算空值还是计算所有值。
(3) 结果基于输入数据的排序。
(4) 如果未找到该值,则返回 -1。 空值的索引始终为 -1,无论输入中是否存在空值。
(5) 对于十进制输入,生成的十进制将具有相同的精度和刻度。 结果四舍五入远离零。
(6) 输出是
{"min": input type, "max": input type}
结构体。在间隔类型中,仅支持月份间隔,因为日期时间和月份日期时间纳米类型不可排序。
(7) 输出是一个
{"mode": input type, "count": Int64}
结构的数组。它包含输入中最常见的 N 个元素,按降序排列,其中 N 由ModeOptions::n
给出。如果两个值的计数相同,则较小的值排在前面。请注意,如果输入的离散值少于 N 个,则输出的元素可能少于 N 个。(8) 第一个输入包含透视键,而第二个输入包含要透视的值。 输出是一个结构体,其中包含
PivotOptions::key_names
中每个键的字段。(9) 输出是 Int64、UInt64、Float64 或 Decimal128/256,具体取决于输入类型。
(10) 输出是 Float64 或输入类型,具体取决于 QuantileOptions。
(11) Decimal 参数首先被强制转换为 Float64。
(12) tdigest/t-digest 计算近似分位数,因此只需要固定数量的内存。 有关详细信息,请参阅参考实现。
Decimal 参数首先被强制转换为 Float64。
分组聚合(“group by”)#
分组聚合不能直接调用,而是用作 SQL 风格的“group by”操作的一部分。 与标量聚合一样,分组聚合将多个输入值减少为单个输出值。 但是,分组聚合不是聚合输入的所有值,而是将输入值在某些“键”列集合上进行分区,然后分别聚合每个组,为每个输入组发出一个输出值。
例如,对于下表
列 |
列 |
---|---|
“a” |
2 |
“a” |
5 |
“b” |
null |
“b” |
null |
null |
null |
null |
9 |
我们可以计算列 x
的总和,按列 key
分组。 这给了我们三个组,结果如下。 请注意,null 被视为不同的键值。
列 |
列 |
---|---|
“a” |
7 |
“b” |
null |
null |
9 |
支持的聚合函数如下。 所有函数名称都以 hash_
作为前缀,这使它们与上面的标量等效函数区分开来,并反映了它们在内部的实现方式。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
hash_all |
一元 |
布尔值 |
布尔值 |
(1) |
|
hash_any |
一元 |
布尔值 |
布尔值 |
(1) |
|
hash_approximate_median |
一元 |
数值 |
Float64 |
||
hash_count |
一元 |
任何 |
Int64 |
(2) |
|
hash_count_all |
零元 |
Int64 |
|||
hash_count_distinct |
一元 |
任何 |
Int64 |
(2) |
|
hash_distinct |
一元 |
任何 |
输入类型的列表 |
(2) (3) |
|
hash_first |
一元 |
数值,二进制 |
输入类型 |
(11) |
|
hash_first_last |
一元 |
数值,二进制 |
结构体 |
(11) |
|
hash_kurtosis |
一元 |
数值 |
Float64 |
(9) |
|
hash_last |
一元 |
数值,二进制 |
输入类型 |
(11) |
|
hash_list |
一元 |
任何 |
输入类型的列表 |
(3) |
|
hash_max |
一元 |
非嵌套、非二进制/类字符串 |
输入类型 |
||
hash_mean |
一元 |
数值 |
Decimal/Float64 |
(4) |
|
hash_min |
一元 |
非嵌套、非二进制/类字符串 |
输入类型 |
||
hash_min_max |
一元 |
非嵌套类型 |
结构体 |
(5) |
|
hash_one |
一元 |
任何 |
输入类型 |
(6) |
|
hash_pivot_wider |
二进制 |
二进制,字符串,整数(参数 0);任何(参数 1) |
结构体 |
(7) |
|
hash_product |
一元 |
数值 |
数值 |
(8) |
|
hash_skew |
一元 |
数值 |
Float64 |
(9) |
|
hash_stddev |
一元 |
数值 |
Float64 |
(9) |
|
hash_sum |
一元 |
数值 |
数值 |
(8) |
|
hash_tdigest |
一元 |
数值 |
FixedSizeList[Float64] |
(10) |
|
hash_variance |
一元 |
数值 |
Float64 |
(9) |
(1) 如果考虑空值,通过将
ScalarAggregateOptions::skip_nulls
设置为 false,则应用Kleene 逻辑。 min_count 选项不生效。(2) CountMode 控制是仅计算非空值(默认),仅计算空值,还是计算所有值。 对于 hash_distinct,它改为控制是否发出空值。 这永远不会影响分组键,只会影响组值(即,您可能会得到一个键为空的组)。
(3)
hash_distinct
和hash_list
将分组的值收集到列表数组中。(4) 对于 decimal 输入,生成的 decimal 将具有相同的精度和比例。 结果四舍五入远离零。
(5) 输出是一个
{"min": input type, "max": input type}
结构体数组。在间隔类型中,仅支持月份间隔,因为日期时间和月份日期时间纳米类型不可排序。
(6)
hash_one
从每个组的输入中返回一个任意值。 该函数偏向于非空值:如果某个组至少有一个非空值,则返回该值,只有当该组的所有值都为null
时,该函数才会返回null
。(7) 第一个输入包含透视键,而第二个输入包含要透视的值。 输出是一个结构体,其中包含
PivotOptions::key_names
中每个键的字段。(8) 输出是 Int64、UInt64、Float64 或 Decimal128/256,具体取决于输入类型。
(9) Decimal 参数首先被强制转换为 Float64。
(10) T-digest 计算近似分位数,因此只需要固定数量的内存。 有关详细信息,请参阅参考实现。
(11) 结果基于输入数据的排序。
逐元素(“标量”)函数#
所有逐元素函数都接受数组和标量作为输入。 一元函数的语义如下
标量输入产生标量输出
数组输入产生数组输出
二元函数具有以下语义(在 NumPy 等其他系统中有时称为“广播”)
(标量, 标量)
输入产生标量输出(数组, 数组)
输入产生数组输出(并且两个输入必须具有相同的长度)(标量, 数组)
和(数组, 标量)
产生数组输出。 标量输入被视为长度为 N 的数组,与另一个输入相同,并且相同的值重复 N 次。
算术函数#
这些函数期望数值类型的输入,并将给定的算术运算应用于从输入中收集的每个元素。 如果任何输入元素为空,则相应的输出元素为空。 对于二元函数,输入将在应用运算之前强制转换为通用数值类型(并在适用时进行字典解码)。
这些函数的默认变体不检测溢出(然后结果通常会回绕)。 大多数函数还有一种溢出检查变体,后缀为 _checked
,当检测到溢出时,该变体会返回一个 Invalid
Status
。
对于支持 decimal 输入的函数(目前为 add
, subtract
, multiply
和 divide
及其 checked 变体),不同精度/比例的 decimals 将被适当地提升。 混合的 decimal 和浮点参数会将所有参数强制转换为浮点数,而混合的 decimal 和整数参数会将所有参数强制转换为 decimals。 混合的时间分辨率时间输入将被强制转换为最精细的输入分辨率。
函数名称 |
元数 |
输入类型 |
输出类型 |
注释 |
---|---|---|---|---|
abs |
一元 |
数值/持续时间 |
数值/持续时间 |
|
abs_checked |
一元 |
数值/持续时间 |
数值/持续时间 |
|
add |
二进制 |
数值/时间 |
数值/时间 |
(1) |
add_checked |
二进制 |
数值/时间 |
数值/时间 |
(1) |
divide |
二进制 |
数值/时间 |
数值/时间 |
(1) |
divide_checked |
二进制 |
数值/时间 |
数值/时间 |
(1) |
exp |
一元 |
数值 |
Float32/Float64 |
|
expm1 |
一元 |
数值 |
Float32/Float64 |
|
multiply |
二进制 |
数值/时间 |
数值/时间 |
(1) |
multiply_checked |
二进制 |
数值/时间 |
数值/时间 |
(1) |
negate |
一元 |
数值/持续时间 |
数值/持续时间 |
|
negate_checked |
一元 |
有符号数值/持续时间 |
有符号数值/持续时间 |
|
power |
二进制 |
数值 |
数值 |
|
power_checked |
二进制 |
数值 |
数值 |
|
sign |
一元 |
数值/持续时间 |
Int8/Float32/Float64 |
(2) |
sqrt |
一元 |
数值 |
数值 |
|
sqrt_checked |
一元 |
数值 |
数值 |
|
subtract |
二进制 |
数值/时间 |
数值/时间 |
(1) |
subtract_checked |
二进制 |
数值/时间 |
数值/时间 |
(1) |
(1) 计算的 DECIMAL 结果的精度和比例
操作
结果精度和比例
addsubtractscale = max(s1, s2)precision = max(p1-s1, p2-s2) + 1 + scalemultiply
scale = s1 + s2precision = p1 + p2 + 1divide
scale = max(4, s1 + p2 - s2 + 1)precision = p1 - s1 + s2 + scale它与 Redshift 的 decimal 提升规则兼容。 所有 decimal 数字都保留用于
add
,subtract
和multiply
操作。divide
的结果精度至少是两个操作数的精度之和,并保留足够的比例。 如果结果精度超出 decimal 值范围,则返回错误。(2) 对于非零输入,输出为 (-1,1) 中的任何一个,对于零输入,输出为 0。 NaN 值返回 NaN。 积分和 decimal 值将有符号性作为 Int8 返回,浮点值以与输入值相同的类型返回它。
位运算函数#
函数名称 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
bit_wise_and |
二进制 |
数值 |
数值 |
bit_wise_not |
一元 |
数值 |
数值 |
bit_wise_or |
二进制 |
数值 |
数值 |
bit_wise_xor |
二进制 |
数值 |
数值 |
shift_left |
二进制 |
数值 |
数值 |
shift_left_checked |
二进制 |
数值 |
数值 (1) |
shift_right |
二进制 |
数值 |
数值 |
shift_right_checked |
二进制 |
数值 |
数值 (1) |
(1) 如果移位量(即第二个输入)超出数据类型的范围,则会发出错误。 但是,移位第一个输入时的溢出不是错误(截断的位将被静默丢弃)。
舍入函数#
舍入函数根据舍入标准将数值输入替换为具有更简单表示的近似值。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
ceil |
一元 |
数值 |
Float32/Float64/Decimal |
||
floor |
一元 |
数值 |
Float32/Float64/Decimal |
||
round |
一元 |
数值 |
输入类型 |
(1)(2) |
|
round_to_multiple |
一元 |
数值 |
输入类型 |
(1)(3) |
|
round_binary |
二进制 |
数值 |
输入类型 |
(1)(4) |
|
trunc |
一元 |
数值 |
Float32/Float64/Decimal |
(1) 默认情况下,舍入函数使用 HALF_TO_EVEN 将值更改为最接近的整数以解决联系。 可以使用选项来控制舍入标准。 所有
round
函数都有round_mode
选项来设置舍入模式。(2) 舍入到指定位数的数字,其中
ndigits
RoundOptions
的选项指定了舍入精度,以位数来表示。负值对应于非小数部分的位数。例如,-2 对应于舍入到最接近 100 的倍数(将个位和十位数字置零)。ndigits
的默认值为 0,表示舍入到最接近的整数。对于整数输入,非负的ndigits
值将被忽略,输入将保持不变。对于整数输入,如果-ndigits
大于输入类型可以容纳的最大位数,则会返回错误。(3) 舍入到倍数,其中
multiple
RoundToMultipleOptions
的选项指定舍入比例。舍入倍数必须是正值,并且可以强制转换为输入类型。例如,100 对应于舍入到最接近 100 的倍数(将个位和十位数字置零)。multiple
的默认值为 1,表示舍入到最接近的整数。(4) 将第一个输入舍入到第二个输入的倍数。舍入倍数必须是正值,并且可以强制转换为第一个输入类型。例如,100 对应于舍入到最接近 100 的倍数(将个位和十位数字置零)。
对于 round
函数,可以使用以下舍入模式。Tie-breaking 模式以 HALF 为前缀,并将非 ties 舍入到最接近的整数。给出的示例值适用于 ndigits
和 multiple
的默认值。
|
执行的操作 |
示例值 |
---|---|---|
DOWN |
舍入到最接近的,小于或等于其绝对值的整数;也称为 |
3.2 -> 3, 3.7 -> 3, -3.2 -> -4, -3.7 -> -4 |
UP |
舍入到最接近的,大于或等于其绝对值的整数;也称为 |
3.2 -> 4, 3.7 -> 4, -3.2 -> -3, -3.7 -> -3 |
TOWARDS_ZERO |
获取不带小数位的整数部分;也称为 |
3.2 -> 3, 3.7 -> 3, -3.2 -> -3, -3.7 -> -3 |
TOWARDS_INFINITY |
对负值使用 |
3.2 -> 4, 3.7 -> 4, -3.2 -> -4, -3.7 -> -4 |
HALF_DOWN |
使用 |
3.5 -> 3, 4.5 -> 4, -3.5 -> -4, -4.5 -> -5 |
HALF_UP |
使用 |
3.5 -> 4, 4.5 -> 5, -3.5 -> -3, -4.5 -> -4 |
HALF_TOWARDS_ZERO |
使用 |
3.5 -> 3, 4.5 -> 4, -3.5 -> -3, -4.5 -> -4 |
HALF_TOWARDS_INFINITY |
使用 |
3.5 -> 4, 4.5 -> 5, -3.5 -> -4, -4.5 -> -5 |
HALF_TO_EVEN |
将 ties 舍入到最接近的偶数整数 |
3.5 -> 4, 4.5 -> 4, -3.5 -> -4, -4.5 -> -4 |
HALF_TO_ODD |
将 ties 舍入到最接近的奇数整数 |
3.5 -> 3, 4.5 -> 5, -3.5 -> -3, -4.5 -> -5 |
下表给出了 ndigits
(对于 round
和 round_binary
函数)和 multiple
(对于 round_to_multiple
函数)分别如何影响执行的操作的示例。
舍入 |
舍入 |
执行的操作 |
---|---|---|
1 |
0 |
舍入到整数 |
0.001 |
3 |
舍入到小数点后 3 位 |
10 |
-1 |
舍入到 10 的倍数 |
2 |
NA |
舍入到 2 的倍数 |
对数函数#
还支持对数函数,并且还提供 _checked
变体,如果需要,可以检查域错误。
接受十进制值,但首先将其转换为 Float64。
函数名称 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
ln |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
ln_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log10 |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log10_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log1p |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log1p_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log2 |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
log2_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
logb |
二进制 |
Float32/Float64/Decimal |
Float32/Float64 |
logb_checked |
二进制 |
Float32/Float64/Decimal |
Float32/Float64 |
三角函数#
还支持三角函数,并且还提供 _checked
变体,如果需要,可以检查域错误。
接受十进制值,但首先将其转换为 Float64。
函数名称 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
acos |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
acos_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
asin |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
asin_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
atan |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
atan2 |
二进制 |
Float32/Float64/Decimal |
Float32/Float64 |
cos |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
cos_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
sin |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
sin_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
tan |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
tan_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
双曲三角函数#
还支持双曲三角函数,并且在适用的情况下,还提供 _checked
变体,用于检查域错误。
接受十进制值,但首先将其转换为 Float64。
函数名称 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
acosh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
acosh_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
asinh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
atanh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
atanh_checked |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
cosh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
sinh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
tanh |
一元 |
Float32/Float64/Decimal |
Float32/Float64 |
比较#
这些函数期望两个数字类型的输入(在这种情况下,它们将在比较之前转换为 common numeric type),或者两个 Binary- 或 String-like 类型的输入,或者两个 Temporal 类型的输入。如果任何输入是字典编码的,它将被展开以进行比较。如果一对输入元素中的任何一个为空,则相应的输出元素为空。Decimal 参数将以与 add
和 subtract
相同的方式进行提升。
函数名 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
equal |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
greater |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
greater_equal |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
less |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
less_equal |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
not_equal |
二进制 |
数字、Temporal、Binary- 和 String-like |
布尔值 |
这些函数接受任意数量的数字类型输入(在这种情况下,它们将在比较之前转换为 common numeric type)或 Temporal 类型的输入。如果任何输入是字典编码的,它将被展开以进行比较。
函数名 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
max_element_wise |
Varargs |
数字、Temporal、Binary- 和 String-like |
数字或 Temporal |
(1) |
|
min_element_wise |
Varargs |
数字、Temporal、Binary- 和 String-like |
数字或 Temporal |
(1) |
(1) 默认情况下,nulls 被跳过(但可以将内核配置为传播 nulls)。对于浮点值,NaN 将优先于 null,但不优先于任何其他值。对于 binary- 和 string-like 值,仅支持相同的类型参数。
逻辑函数#
这些函数的正常行为是,如果任何输入为空,则发出 null(类似于浮点计算中 NaN
的语义)。
其中一些函数还提供 Kleene 逻辑变体(后缀为 _kleene
),其中 null 被认为是“未定义”。这是在 SQL 系统以及 R 和 Julia 中使用的 null 解释示例。
因此,对于 Kleene 逻辑变体
“true AND null”、“null AND true”给出“null”(结果未定义)
“true OR null”、“null OR true”给出“true”
“false AND null”、“null AND false”给出“false”
“false OR null”、“null OR false”给出“null”(结果未定义)
函数名称 |
元数 |
输入类型 |
输出类型 |
---|---|---|---|
和 |
二进制 |
布尔值 |
布尔值 |
and_kleene |
二进制 |
布尔值 |
布尔值 |
and_not |
二进制 |
布尔值 |
布尔值 |
and_not_kleene |
二进制 |
布尔值 |
布尔值 |
invert |
一元 |
布尔值 |
布尔值 |
or |
二进制 |
布尔值 |
布尔值 |
or_kleene |
二进制 |
布尔值 |
布尔值 |
xor |
二进制 |
布尔值 |
布尔值 |
字符串谓词#
这些函数根据输入字符串元素的字符内容对其进行分类。空字符串元素在输出中发出 false。对于函数的 ASCII 变体(前缀为 ascii_
),包含非 ASCII 字符的字符串元素在输出中发出 false。
第一组函数以逐个字符为基础运行,如果输入仅包含给定类的字符,则在输出中发出 true
函数名称 |
元数 |
输入类型 |
输出类型 |
匹配的字符类 |
注释 |
---|---|---|---|---|---|
ascii_is_alnum |
一元 |
String-like |
布尔值 |
字母数字 ASCII |
|
ascii_is_alpha |
一元 |
String-like |
布尔值 |
字母 ASCII |
|
ascii_is_decimal |
一元 |
String-like |
布尔值 |
十进制 ASCII |
(1) |
ascii_is_lower |
一元 |
String-like |
布尔值 |
小写 ASCII |
(2) |
ascii_is_printable |
一元 |
String-like |
布尔值 |
可打印 ASCII |
|
ascii_is_space |
一元 |
String-like |
布尔值 |
空格 ASCII |
|
ascii_is_upper |
一元 |
String-like |
布尔值 |
大写 ASCII |
(2) |
utf8_is_alnum |
一元 |
String-like |
布尔值 |
字母数字 Unicode |
|
utf8_is_alpha |
一元 |
String-like |
布尔值 |
字母 Unicode |
|
utf8_is_decimal |
一元 |
String-like |
布尔值 |
十进制 Unicode |
|
utf8_is_digit |
一元 |
String-like |
布尔值 |
Unicode 数字 |
(3) |
utf8_is_lower |
一元 |
String-like |
布尔值 |
小写 Unicode |
(2) |
utf8_is_numeric |
一元 |
String-like |
布尔值 |
数字 Unicode |
(4) |
utf8_is_printable |
一元 |
String-like |
布尔值 |
可打印 Unicode |
|
utf8_is_space |
一元 |
String-like |
布尔值 |
空格 Unicode |
|
utf8_is_upper |
一元 |
String-like |
布尔值 |
大写 Unicode |
(2) |
(1) 还匹配所有数字 ASCII 字符和所有 ASCII 数字。
(2) 非大小写字符(例如标点符号)不匹配。
(3) 当前与
utf8_is_decimal
相同。(4) 与
utf8_is_decimal
不同,非十进制数字字符也匹配。
第二组函数还考虑字符串元素中的字符顺序
函数名称 |
元数 |
输入类型 |
输出类型 |
注释 |
---|---|---|---|---|
ascii_is_title |
一元 |
String-like |
布尔值 |
(1) |
utf8_is_title |
一元 |
String-like |
布尔值 |
(1) |
(1) 仅当输入字符串元素为首字母大写时,输出才为 true,即任何单词都以大写字符开头,后跟小写字符。单词边界由非大小写字符定义。
第三组函数以逐字节为基础检查字符串元素
函数名称 |
元数 |
输入类型 |
输出类型 |
注释 |
---|---|---|---|---|
string_is_ascii |
一元 |
String-like |
布尔值 |
(1) |
(1) 仅当输入字符串元素仅包含 ASCII 字符时,输出才为 true,即仅包含 [0, 127] 中的字节。
字符串转换#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
ascii_capitalize |
一元 |
String-like |
String-like |
(1) |
|
ascii_lower |
一元 |
String-like |
String-like |
(1) |
|
ascii_reverse |
一元 |
String-like |
String-like |
(2) |
|
ascii_swapcase |
一元 |
String-like |
String-like |
(1) |
|
ascii_title |
一元 |
String-like |
String-like |
(1) |
|
ascii_upper |
一元 |
String-like |
String-like |
(1) |
|
binary_length |
一元 |
Binary- 或 String-like |
Int32 或 Int64 |
(3) |
|
binary_repeat |
二进制 |
Binary/String (Arg 0); Integral (Arg 1) |
Binary- 或 String-like |
(4) |
|
binary_replace_slice |
一元 |
String-like |
Binary- 或 String-like |
(5) |
|
binary_reverse |
一元 |
二进制 |
二进制 |
(6) |
|
replace_substring |
一元 |
String-like |
String-like |
(7) |
|
replace_substring_regex |
一元 |
String-like |
String-like |
(8) |
|
utf8_capitalize |
一元 |
String-like |
String-like |
(9) |
|
utf8_length |
一元 |
String-like |
Int32 或 Int64 |
(10) |
|
utf8_lower |
一元 |
String-like |
String-like |
(9) |
|
utf8_replace_slice |
一元 |
String-like |
String-like |
(7) |
|
utf8_reverse |
一元 |
String-like |
String-like |
(11) |
|
utf8_swapcase |
一元 |
String-like |
String-like |
(9) |
|
utf8_title |
一元 |
String-like |
String-like |
(9) |
|
utf8_upper |
一元 |
String-like |
String-like |
(9) |
(1) 输入中的每个 ASCII 字符都会转换为小写或大写。非 ASCII 字符保持不变。
(2) ASCII 输入被反转到输出。如果存在非 ASCII 字符,则将返回
Invalid
Status
。(3) 输出是每个输入元素的物理长度(以字节为单位)。对于 Binary/String,输出类型为 Int32,对于 LargeBinary/LargeString,输出类型为 Int64。
(4) 将输入的二进制字符串重复给定的次数。
(5) 将子字符串中从
ReplaceSliceOptions::start
(包含) 到ReplaceSliceOptions::stop
(不包含) 的切片,替换为ReplaceSubstringOptions::replacement
。 binary kernel 以字节为单位测量切片,而 UTF8 kernel 以代码单元为单位测量切片。(6) 执行字节级别的反转。
(7) 将与
ReplaceSubstringOptions::pattern
匹配的非重叠子字符串替换为ReplaceSubstringOptions::replacement
。 如果ReplaceSubstringOptions::max_replacements
!= -1,则它确定进行的最大替换次数,从左侧开始计数。(8) 将与正则表达式
ReplaceSubstringOptions::pattern
匹配的非重叠子字符串替换为ReplaceSubstringOptions::replacement
,使用 Google RE2 库。 如果ReplaceSubstringOptions::max_replacements
!= -1,则它确定进行的最大替换次数,从左侧开始计数。 请注意,如果模式包含组,则可以使用反向引用。(9) 输入中的每个 UTF8 编码字符都转换为小写或大写。
(10) 输出是每个输入元素的字符数(不是字节数)。 String 的输出类型为 Int32,LargeString 的输出类型为 Int64。
(11) 每个 UTF8 编码的代码单元以相反的顺序写入输出。 如果输入不是有效的 UTF8,则输出未定义(但会保留输出缓冲区的大小)。
字符串填充#
这些函数附加/前置给定的填充字节 (ASCII) 或代码点 (UTF8),以便使字符串居中 (center)、右对齐 (lpad) 或左对齐 (rpad)。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
---|---|---|---|---|
ascii_center |
一元 |
String-like |
String-like |
|
ascii_lpad |
一元 |
String-like |
String-like |
|
ascii_rpad |
一元 |
String-like |
String-like |
|
utf8_center |
一元 |
String-like |
String-like |
|
utf8_lpad |
一元 |
String-like |
String-like |
|
utf8_rpad |
一元 |
String-like |
String-like |
字符串修剪#
这些函数修剪掉两侧 (trim) 或左侧 (ltrim) 或右侧 (rtrim) 的字符。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
ascii_ltrim |
一元 |
String-like |
String-like |
(1) |
|
ascii_ltrim_whitespace |
一元 |
String-like |
String-like |
(2) |
|
ascii_rtrim |
一元 |
String-like |
String-like |
(1) |
|
ascii_rtrim_whitespace |
一元 |
String-like |
String-like |
(2) |
|
ascii_trim |
一元 |
String-like |
String-like |
(1) |
|
ascii_trim_whitespace |
一元 |
String-like |
String-like |
(2) |
|
utf8_ltrim |
一元 |
String-like |
String-like |
(3) |
|
utf8_ltrim_whitespace |
一元 |
String-like |
String-like |
(4) |
|
utf8_rtrim |
一元 |
String-like |
String-like |
(3) |
|
utf8_rtrim_whitespace |
一元 |
String-like |
String-like |
(4) |
|
utf8_trim |
一元 |
String-like |
String-like |
(3) |
|
utf8_trim_whitespace |
一元 |
String-like |
String-like |
(4) |
(1) 仅修剪掉
TrimOptions::characters
中指定的字符。 输入字符串和characters
参数都解释为 ASCII 字符。(2) 仅修剪掉 ASCII 空格字符 (
'\t'
、'\n'
、'\v'
、'\f'
、'\r'
和' '
)。(3) 仅修剪掉
TrimOptions::characters
中指定的字符。(4) 仅修剪掉 Unicode 空格字符。
字符串分割#
这些函数将字符串分割成字符串列表。 所有 kernel 都可以选择使用 max_splits
和 reverse
参数进行配置,其中 max_splits == -1
表示没有限制(默认值)。 当 reverse
为 true 时,分割从字符串的末尾开始进行;这仅在给定正 max_splits
时相关。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
ascii_split_whitespace |
一元 |
String-like |
List-like |
(1) |
|
split_pattern |
一元 |
Binary- 或 String-like |
List-like |
(2) |
|
split_pattern_regex |
一元 |
Binary- 或 String-like |
List-like |
(3) |
|
utf8_split_whitespace |
一元 |
String-like |
List-like |
(4) |
(1) 非零长度的 ASCII 定义的空格字节序列 (
'\t'
、'\n'
、'\v'
、'\f'
、'\r'
和' '
) 被视为分隔符。(2) 当找到完全匹配的模式时,字符串将被分割(模式本身不包含在输出中)。
(3) 当找到正则表达式匹配项时,字符串将被分割(匹配的子字符串本身不包含在输出中)。
(4) 非零长度的 Unicode 定义的空格代码点序列被视为分隔符。
字符串组件提取#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
extract_regex |
一元 |
Binary- 或 String-like |
结构体 |
(1) |
|
extract_regex_span |
一元 |
Binary- 或 String-like |
结构体 |
(2) |
(1) 使用 Google RE2 库提取由正则表达式定义的子字符串。 输出结构字段名称引用命名的捕获组,例如正则表达式
(?P<letter>[ab])(?P<digit>\\d)
的 ‘letter’ 和 ‘digit’。(2) 使用 Google RE2 库提取由正则表达式定义的子字符串的偏移量和长度。 输出结构字段名称引用命名的捕获组,例如正则表达式
(?P<letter>[ab])(?P<digit>\\d)
的 ‘letter’ 和 ‘digit’。 每个输出结构字段都是一个固定大小的两个整数列表:捕获组的起始索引和捕获组的长度。
字符串连接#
这些函数执行字符串分割的逆操作。
函数名称 |
元数 |
输入类型 1 |
输入类型 2 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|---|
binary_join |
二进制 |
Binary- or String-like 的列表 |
String-like |
String-like |
(1) |
|
binary_join_element_wise |
Varargs |
Binary- or String-like (varargs) |
Binary- 或 String-like |
Binary- 或 String-like |
(2) |
(1) 第一个输入必须是一个数组,而第二个输入可以是标量或数组。 第一个输入中的每个值列表都使用每个第二个输入作为分隔符进行连接。 如果任何输入列表为 null 或包含 null 值,则相应的输出将为 null。
(2) 所有参数都按元素方式连接,最后一个参数被视为分隔符(无论哪种情况,标量都会被回收)。 Null 分隔符发出 null。 如果任何其他参数为 null,则默认情况下相应的输出将为 null,但它可以选择跳过或替换为给定的字符串。
字符串切片#
此函数根据起始和停止索引以及非零步长(默认为 1)将数组的每个序列转换为子序列。 切片语义遵循 Python 切片语义:起始索引是包含的,停止索引是不包含的;如果步长为负数,则序列以相反的顺序执行。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
binary_slice |
一元 |
Binary-like |
Binary-like |
(1) |
|
utf8_slice_codeunits |
一元 |
String-like |
String-like |
(2) |
(1) 将字符串切片为由
SliceOptions
给出的 (start
,stop
,step
) 定义的子字符串,其中start
和stop
以字节为单位测量。 Null 输入发出 null。(2) 将字符串切片为由
SliceOptions
给出的 (start
,stop
,step
) 定义的子字符串,其中start
和stop
以代码单元为单位测量。 Null 输入发出 null。
包含测试#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
count_substring |
一元 |
Binary- 或 String-like |
Int32 或 Int64 |
(1) |
|
count_substring_regex |
一元 |
Binary- 或 String-like |
Int32 或 Int64 |
(1) |
|
ends_with |
一元 |
Binary- 或 String-like |
布尔值 |
(2) |
|
find_substring |
一元 |
Binary- and String-like |
Int32 或 Int64 |
(3) |
|
find_substring_regex |
一元 |
Binary- and String-like |
Int32 或 Int64 |
(3) |
|
index_in |
一元 |
Boolean, Null, Numeric, Temporal, Binary- and String-like |
Int32 |
(4) |
|
is_in |
一元 |
Boolean, Null, Numeric, Temporal, Binary- and String-like |
布尔值 |
(5) |
|
match_like |
一元 |
Binary- 或 String-like |
布尔值 |
(6) |
|
match_substring |
一元 |
Binary- 或 String-like |
布尔值 |
(7) |
|
match_substring_regex |
一元 |
Binary- 或 String-like |
布尔值 |
(8) |
|
starts_with |
一元 |
Binary- 或 String-like |
布尔值 |
(2) |
(1) 输出是
MatchSubstringOptions::pattern
在相应输入字符串中出现的次数。 Binary/String 的输出类型为 Int32,LargeBinary/LargeString 的输出类型为 Int64。(2) 当且仅当
MatchSubstringOptions::pattern
是相应输入的后缀/前缀时,输出为 true。(3) 输出是
MatchSubstringOptions::pattern
在相应输入字符串中第一次出现的索引,否则为 -1。 Binary/String 的输出类型为 Int32,LargeBinary/LargeString 的输出类型为 Int64。(4) 如果在
SetLookupOptions::value_set
中找到对应的输入元素,则输出是该元素的索引。否则,输出为空值。(5) 当且仅当对应的输入元素等于
SetLookupOptions::value_set
中的一个元素时,输出为真。(6) 当且仅当 SQL 风格的 LIKE 模式
MatchSubstringOptions::pattern
与对应的输入元素完全匹配时,输出为真。也就是说,%
将匹配任意数量的字符,_
将精确匹配一个字符,任何其他字符匹配它本身。要匹配字面百分号或下划线,请在该字符前加反斜杠。(7) 当且仅当
MatchSubstringOptions::pattern
是对应输入元素的子字符串时,输出为真。(8) 当且仅当
MatchSubstringOptions::pattern
在任何位置与对应的输入元素匹配时,输出为真。
分类#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
is_finite |
一元 |
Null, Numeric |
布尔值 |
(1) |
|
is_inf |
一元 |
Null, Numeric |
布尔值 |
(2) |
|
is_nan |
一元 |
Null, Numeric |
布尔值 |
(3) |
|
is_null |
一元 |
任何 |
布尔值 |
(4) |
|
is_valid |
一元 |
任何 |
布尔值 |
(5) |
|
true_unless_null |
一元 |
任何 |
布尔值 |
(6) |
(1) 当且仅当对应的输入元素是有限的(既不是 Infinity,也不是 -Infinity,也不是 NaN)时,输出为真。因此,对于 Decimal 和整数输入,此函数始终返回 true。
(2) 当且仅当对应的输入元素是 Infinity/-Infinity 时,输出为真。因此,对于 Decimal 和整数输入,此函数始终返回 false。
(3) 当且仅当对应的输入元素是 NaN 时,输出为真。因此,对于 Decimal 和整数输入,此函数始终返回 false。
(4) 当且仅当对应的输入元素为空值时,输出为真。通过设置
NullOptions::nan_is_null
,NaN 值也可以被视为空值。(5) 当且仅当对应的输入元素非空时,输出为真,否则为假。
- (6) 当且仅当对应的输入元素非空时,输出为真,否则为空值。
主要用于表达式简化/保证。
选择 / 多路复用#
对于每行输入值,这些函数根据条件发出其中一个输入值。
函数名称 |
元数 |
输入类型 |
输出类型 |
注释 |
---|---|---|---|---|
case_when |
Varargs |
Boolean 的结构 (Arg 0), 任何 (其余) |
输入类型 |
(1) |
choose |
Varargs |
Integral (Arg 0), 定宽/类似二进制 (其余) |
输入类型 |
(2) |
coalesce |
Varargs |
任何 |
输入类型 |
(3) |
if_else |
三元运算符 |
Boolean (Arg 0), 任何 (其余) |
输入类型 |
(4) |
(1) 此函数的作用类似于 SQL “case when” 语句或 switch-case。输入是一个 “condition” 值,它是一个 Boolean 的结构体,后跟每个 “branch” 的值。条件结构体的每个子项必须恰好有一个值参数,或者比子项多一个值参数(在这种情况下,我们有一个 “else” 或 “default” 值)。输出与值输入的类型相同;每行将是第一个布尔值为 true 的值数据对应的value值,或者是 “default” 输入对应的value值,否则为空值。
请注意,目前,虽然支持所有类型,但字典将被解包。
(2) 第一个输入必须是 integral 类型。其余参数可以是任何类型,但必须都是相同类型或可提升为通用类型。第一个输入(“index”)的每个值都用作其余参数的基于零的索引(即,索引 0 是第二个参数,索引 1 是第三个参数,依此类推),并且该行的输出值将是所选输入的相应值在该行。如果索引为空值,则输出也将为空值。
(3) 输出的每一行将是该行第一个非空的输入值,否则为空值。
(4) 第一个输入必须是 Boolean 标量或数组。第二和第三个输入可以是标量或数组,并且必须是相同类型。输出是一个数组(如果所有输入都是标量,则为标量),其类型与第二个/第三个输入相同。如果第一个输入中存在空值,则它们将被提升到输出,否则将根据第一个输入值选择空值。
另请参见:replace_with_mask。
结构转换#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
list_value_length |
一元 |
List-like |
Int32 或 Int64 |
(1) |
|
make_struct |
Varargs |
任何 |
结构体 |
(2) |
(1) 每个输出元素都是对应输入元素的长度(如果输入为空值,则为空值)。对于 List、ListView 和 FixedSizeList,输出类型为 Int32,对于 LargeList 和 LargeListView,输出类型为 Int64。
(2) 输出结构体的字段类型是其参数的类型。字段名称使用
MakeStructOptions
的实例指定。如果所有输入都是标量,则输出形状将是标量,否则任何标量都将广播到数组。
转换#
提供了一个名为 cast
的通用转换函数,该函数接受大量的输入和输出类型。要转换为的类型可以在 CastOptions
实例中传递。或者,具体的函数 Cast()
提供了相同的服务。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
ceil_temporal |
一元 |
Temporal |
Temporal |
||
floor_temporal |
一元 |
Temporal |
Temporal |
||
round_temporal |
一元 |
Temporal |
Temporal |
||
cast |
一元 |
Many |
Variable |
||
strftime |
一元 |
Temporal |
String |
(1) |
|
strptime |
一元 |
String-like |
Timestamp |
下面列出了 cast
可用的转换。在所有情况下,空输入值都会转换为空输出值。
(1)
%S
(秒)标志的输出精度取决于输入时间戳精度。具有秒精度的时间戳表示为整数,而毫秒、微秒和纳秒表示为固定浮点数,分别具有 3、6 和 9 位小数。要获得整数秒,请强制转换为具有秒分辨率的时间戳。小数点字符根据区域设置进行本地化。有关其他标志的说明,请参见详细格式化文档。
真值提取
输入类型 |
输出类型 |
注释 |
---|---|---|
Binary- and String-like |
布尔值 |
(1) |
数值 |
布尔值 |
(2) |
(1) 当且仅当对应的输入值具有非零长度时,输出为真。
(2) 当且仅当对应的输入值为非零时,输出为真。
同类转换
输入类型 |
输出类型 |
注释 |
---|---|---|
Int32 |
32 位时间 |
(1) |
Int64 |
64 位时间 |
(1) |
(Large)Binary |
(Large)String |
(2) |
(Large)String |
(Large)Binary |
(3) |
数值 |
数值 |
(4) (5) |
32 位时间 |
Int32 |
(1) |
64 位时间 |
Int64 |
(1) |
Temporal |
Temporal |
(4) (5) |
(1) 无操作转换:原始值保持不变,仅更改类型。
(2) 如果
CastOptions::allow_invalid_utf8
为 false,则验证内容。(3) 无操作转换:仅更改类型。
(4) 启用溢出和截断检查,具体取决于给定的
CastOptions
。(5) 并非所有此类转换都已实现。
字符串表示
输入类型 |
输出类型 |
注释 |
---|---|---|
布尔值 |
String-like |
|
数值 |
String-like |
通用转换
输入类型 |
输出类型 |
注释 |
---|---|---|
Dictionary |
Dictionary 值类型 |
(1) |
Extension |
Extension 存储类型 |
|
结构体 |
结构体 |
(2) |
List-like |
List-like 或 (Large)ListView |
(3) |
(Large)ListView |
List-like 或 (Large)ListView |
(4) |
Map |
Map 或 List of two-field struct |
(5) |
Null |
任何 |
|
任何 |
Extension |
(6) |
(1) 字典索引不变,字典值从输入值类型转换为输出值类型(如果可以使用转换)。
(2) 输出类型的字段名称必须与输入类型的字段名称相同或为输入类型的字段名称的子集;它们也必须具有相同的顺序。转换为字段名称的子集 “选择” 这些字段,使得每个输出字段与具有相同名称的输入字段的数据匹配。
(3) 列表偏移量不变,列表值从输入值类型转换为输出值类型(如果可以使用转换)。如果输出类型为 (Large)ListView,则大小从偏移量派生。
(4) 如果输出类型类似于列表,则可能必须重建偏移量(因此,重建值数组)才能进行排序和充分间隔。如果输出类型是列表视图类型,则偏移量和大小不变。在任何情况下,列表值都从输入值类型转换为输出值类型(如果可以使用转换)。
(5) 偏移量不变,键和值从各自的输入类型转换为输出类型(如果可以使用转换)。如果输出类型是结构体列表,则键字段输出为第一个字段,值字段输出为第二个字段,无论选择的字段名称如何。
(6) 任何可以转换为结果扩展的存储类型的输入类型。这排除了扩展类型,除非转换为相同的扩展类型。
时间分量提取#
这些函数从时间类型中提取日期时间分量(年、月、日等)。对于具有非空时区的时间戳输入,将返回本地化时间戳分量。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
day |
一元 |
Temporal |
Int64 |
||
day_of_week |
一元 |
Temporal |
Int64 |
(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 |
(5) |
|
year(年份) |
一元 |
Temporal |
Int64 |
||
year_month_day(年_月_日) |
一元 |
Temporal |
结构体 |
(6) |
(1) 输出星期几的数字。默认情况下,周从星期一开始,用 0 表示,到星期日结束,用 6 表示。根据
DayOfWeekOptions::count_from_zero
参数,日编号可以从 0 或 1 开始。DayOfWeekOptions::week_start
可用于使用 ISO 约定设置一周的起始日(星期一=1,星期日=7)。DayOfWeekOptions::week_start
参数不受DayOfWeekOptions::count_from_zero
的影响。(2) 第一个 ISO 周在一月份拥有大部分(4 天或更多)天数。 ISO 年从第一个 ISO 周开始。 ISO 周从星期一开始。 更多详情请参阅 ISO 8601 周日期定义。
(3) 输出是一个
{"iso_year": 输出类型, "iso_week": 输出类型, "iso_day_of_week": 输出类型}
结构体。(4) 第一个美式周在一月份拥有大部分(4 天或更多)天数。美式年从第一个美式周开始。美式周从星期日开始。
(5) 返回周数,允许设置多个参数。 如果
WeekOptions::week_starts_monday
为 true,则周从星期一开始,否则如果为 false,则从星期日开始。 如果WeekOptions::count_from_zero
为 true,则当年份中属于上一年最后一个 ISO 周的日期将编号为第 0 周,否则如果为 false,则为第 52 或 53 周。 如果WeekOptions::first_week_is_fully_in_year
为 true,则第一周(第 1 周)必须完全在一月份;否则如果为 false,则从 12 月 29 日、30 日或 31 日开始的一周将被视为新年的第一周。(6) 输出是一个
{"year": int64(), "month": int64(), "day": int64()}
结构体。
时间差#
这些函数计算两个时间戳之间在指定单元中的差值。 该差值由跨越的边界数量决定,而不是时间跨度。 例如,一天中 23:59:59 和第二天 00:00:01 之间的天数差为一天(因为跨越了午夜),而不是零天(即使经过的时间少于 24 小时)。 此外,如果时间戳具有定义的时区,则以本地时区计算差值。 例如,“2019-12-31 18:00:00-0500”和“2019-12-31 23:00:00-0500”之间的年差为零年,因为本地年份相同,即使 UTC 年份不同。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
---|---|---|---|---|
day_time_interval_between(日_时间_间隔_之间) |
二进制 |
Temporal |
DayTime interval(日时间隔) |
|
days_between(天_之间) |
二进制 |
Timestamp, Date(时间戳,日期) |
Int64 |
|
hours_between(小时_之间) |
二进制 |
Temporal |
Int64 |
|
microseconds_between(微秒_之间) |
二进制 |
Temporal |
Int64 |
|
milliseconds_between(毫秒_之间) |
二进制 |
Temporal |
Int64 |
|
minutes_between(分钟_之间) |
二进制 |
Temporal |
Int64 |
|
month_day_nano_interval_between(月_日_纳秒_间隔_之间) |
二进制 |
Temporal |
MonthDayNano interval(月日纳秒间隔) |
|
month_interval_between(月_间隔_之间) |
二进制 |
Timestamp, Date(时间戳,日期) |
Month interval(月间隔) |
|
nanoseconds_between(纳秒_之间) |
二进制 |
Temporal |
Int64 |
|
quarters_between(季度_之间) |
二进制 |
Timestamp, Date(时间戳,日期) |
Int64 |
|
seconds_between(秒_之间) |
二进制 |
Temporal |
Int64 |
|
weeks_between(周_之间) |
二进制 |
Timestamp, Date(时间戳,日期) |
Int64 |
|
years_between(年_之间) |
二进制 |
Timestamp, Date(时间戳,日期) |
Int64 |
时区处理#
assume_timezone
函数旨在用于当外部系统产生“时区感知缺失”的时间戳时,需要将这些时间戳转换为“时区感知”的时间戳(例如,请参阅 Python 文档中的 定义)。
输入时间戳被假定为相对于 AssumeTimezoneOptions::timezone
中给出的时区。 它们被转换为 UTC 相对的时间戳,并将时区元数据设置为上述值。 如果时间戳已经设置了时区元数据,则返回错误。
local_timestamp
函数将 UTC 相对的时间戳转换为本地的“时区感知缺失”的时间戳。 时区取自输入时间戳的时区元数据。 此函数是 assume_timezone
的逆函数。 请注意:所有时间函数已经像在元数据提供的时区的本地时间一样对时间戳进行操作。 使用 local_timestamp
仅用于当外部系统期望本地时间戳时。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
assume_timezone(假定时区) |
一元 |
Timestamp |
Timestamp |
(1) |
|
local_timestamp(本地时间戳) |
一元 |
Timestamp |
Timestamp |
(2) |
(1) 除了时区值之外,
AssumeTimezoneOptions
还允许选择在给定时区中时间戳不明确或不存在时的行为(由于 DST 转换)。
随机数生成#
此函数生成一个数组,其中包含范围 [0, 1) 内的均匀分布的双精度数字。 这些选项提供输出的长度和生成随机数的算法,使用种子或系统提供的、特定于平台的随机生成器。
函数名称 |
元数 |
输出类型 |
选项类 |
---|---|---|---|
random(随机) |
零元 |
Float64 |
数组式(“向量”)函数#
累积函数#
累积函数是向量函数,它们使用给定的二元结合运算以及标识元素(幺半群)对其输入执行运行累积,并输出一个包含相应中间运行值的数组。 输入应为数字类型。 默认情况下,这些函数不检测溢出。 它们也有溢出检查变体,后缀为 _checked
,当检测到溢出时,它会返回一个 Invalid
Status
。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
cumulative_sum(累积_和) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_sum_checked(累积_和_已检查) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_prod(累积_积) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_prod_checked(累积_积_已检查) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_max(累积_最大值) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_min(累积_最小值) |
一元 |
数值 |
数值 |
(1) |
|
cumulative_mean(累积_平均值) |
一元 |
数值 |
Float64 |
(1) (2) |
(1) CumulativeOptions 有两个可选参数。 第一个参数
CumulativeOptions::start
是运行累积的起始值。 对于sum
,其默认值为 0,对于prod
,其默认值为 1,对于max
,其默认值为输入类型的最小值,对于min
,其默认值为输入类型的最大值。 指定的start
值必须可以强制转换为输入类型。 第二个参数CumulativeOptions::skip_nulls
是一个布尔值。 当设置为 false(默认值)时,传播第一个遇到的 null。 当设置为 true 时,输入中的每个 null 都会在输出中产生相应的 null,并且不会影响向前累积。(2)
CumulativeOptions::start
被忽略。
统计函数#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
winsorize(缩尾) |
一元 |
数值 |
数值 |
(1) |
(1) 钳制较低和较高分位数中的值,以减少异常值的统计影响。 可以在
WinsorizeOptions
中配置分位数。
关联变换#
函数名称 |
元数 |
输入类型 |
输出类型 |
注释 |
---|---|---|---|---|
dictionary_encode(字典编码) |
一元 |
Boolean, Null, Numeric, Temporal, Binary- and String-like |
Dictionary |
(1) |
unique(唯一) |
一元 |
Boolean, Null, Numeric, Temporal, Binary- and String-like |
输入类型 |
(2) |
value_counts(值计数) |
一元 |
Boolean, Null, Numeric, Temporal, Binary- and String-like |
输入类型 |
(3) |
(1) 输出是
Dictionary(Int32, 输入类型)
。 如果输入已经是字典数组,则它是空操作。(2) 从输出中删除重复项,同时保持原始顺序。
(3) 输出是一个
{"values": 输入类型, "counts": Int64}
结构体。 每个输出元素对应于输入中的唯一值,以及此值出现的次数。
选择#
这些函数选择并返回其输入的一个子集。
函数名称 |
元数 |
输入类型 1 |
输入类型 2 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|---|
array_filter(数组_过滤) |
二进制 |
任何 |
布尔值 |
输入类型 1 |
(2) |
|
array_take(数组_取) |
二进制 |
任何 |
Integer(整数) |
输入类型 1 |
(3) |
|
drop_null(删除_空值) |
一元 |
任何 |
输入类型 1 |
(1) |
||
filter(过滤) |
二进制 |
任何 |
布尔值 |
输入类型 1 |
(2) |
|
inverse_permutation(逆_置换) |
一元 |
Signed Integer(有符号整数) |
Signed Integer (4)(有符号整数(4)) |
(5) |
||
scatter(散布) |
二进制 |
任何 |
Integer(整数) |
输入类型 1 |
(6) |
|
take(取) |
二进制 |
任何 |
Integer(整数) |
输入类型 1 |
(3) |
(1) 当且仅当输入中的每个元素为非空时,才将其附加到输出。 如果输入是记录批处理或表格,则列中的任何空值都会删除整行。
(2) 如果输入 2(过滤器)中对应的元素为真,则将输入 1(值)中的每个元素添加到输出。如何处理过滤器中的 null 值可以通过 FilterOptions 进行配置。
(3) 对于输入 2(索引)中的每个元素 i,将输入 1(值)中的第 i 个元素添加到输出。
(4) 输出类型在
InversePermutationOptions
中指定。(5) 对于 indices[i] = x, inverse_permutation[x] = i。如果 x 没有出现在输入索引中,则 inverse_permutation[x] = null。索引必须在 [0, max_index] 的范围内,或者为 null,null 值将被忽略。如果多个索引指向相同的值,则使用最后一个。
(6) 对于 indices[i] = x, output[x] = values[i]。如果 x 没有出现在输入索引中,则 output[x] = null。索引必须在 [0, max_index] 的范围内,或者为 null,在这种情况下,对应的值将被忽略。如果多个索引指向相同的值,则使用最后一个。
包含性测试#
此函数返回数组元素为非 null 且非零的索引。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
indices_nonzero |
一元 |
布尔型、Null、数值型、十进制 |
UInt64 |
排序和分区#
默认情况下,在这些函数中,null 值被认为大于任何其他值(它们将在数组的末尾进行排序或分区)。浮点 NaN 值被认为大于任何其他非 null 值,但小于 null 值。可以使用相应选项类中的 null_placement
设置来更改此行为。
注意
二进制和类似字符串的输入按字节字符串按字典顺序排序,即使对于字符串类型也是如此。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
array_sort_indices |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
UInt64 |
(1) (2) |
|
partition_nth_indices |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
UInt64 |
(3) |
|
rank |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
UInt64 |
(4) |
|
rank_normal |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
Float64 |
(5) |
|
rank_quantile |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
Float64 |
(5) |
|
select_k_unstable |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
UInt64 |
(6) (7) |
|
sort_indices |
一元 |
布尔型、数值型、时间型、二进制和类似字符串 |
UInt64 |
(1) (6) |
(1) 输出是一个索引数组,指向输入,定义了输入的稳定排序。
(2) 输入必须是一个数组。默认顺序是升序。
(3) 输出是一个索引数组,指向输入数组,定义了一个非稳定的部分排序,使得第 N 个索引指向已排序顺序中的第 N 个元素,并且第 N 个索引之前的所有索引指向小于或等于第 N 个及其之后的元素(类似于
std::nth_element()
)。N 在PartitionNthOptions::pivot
中给出。(4) 输出是一个从 1 开始的数值型排名数组。
(5)
rank_quantile
的输出是一个严格介于 0 和 1 之间的分位数数组。rank_normal
的输出是一个有限实数值数组,对应于正态分布中的点,这些点反映了输入的分位数排名。(6) 输入可以是数组、分块数组、记录批处理或表。如果输入是记录批处理或表,则必须指定一个或多个排序键。
(7) 输出是一个索引数组,指向输入,定义了输入的非稳定排序。
结构转换#
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
list_element |
二进制 |
类似列表 (Arg 0), 整数 (Arg 1) |
列表值类型 |
(1) |
|
list_flatten |
一元 |
List-like |
列表值类型 |
(2) |
|
list_parent_indices |
一元 |
List-like |
Int64 |
(3) |
|
list_slice |
一元 |
List-like |
List-like |
(4) |
|
map_lookup |
一元 |
Map |
已计算 |
(5) |
|
struct_field |
一元 |
结构体或联合体 |
已计算 |
(6) |
(1) 输出是一个与输入列表数组长度相同的数组。输出值是每个子列表的指定索引处的值。
(2) 移除顶层嵌套:列表子数组中的所有值(包括 null 值)都附加到输出。但是,父列表数组中的 null 值将被丢弃。
(3) 对于列表子数组中的每个值,将其在类似列表的数组中找到的索引附加到输出。如果父数组是非空 null 列表,则父数组中 null 列表的索引仍可能存在于输出中。如果父数组是列表视图,则任何非 null 列表视图未使用的子数组值在输出中为 null。
(4) 对于每个列表元素,计算该列表元素的切片,然后返回另一个列表切片的列表状数组。 可以根据提供的选项返回固定或可变大小的类似列表的数组。
(5) 从键与通过选项传递的给定查询键匹配的映射中提取
FIRST
、LAST
或ALL
项。 输出类型是FIRST
/LAST
选项的项数组,以及ALL
选项的项列表数组。(6) 根据选项中传递的索引序列提取子值。 结果的有效性位图将是所有中间有效性位图的交集。 例如,对于类型为
struct<a: int32, b: struct<c: int64, d: float64>>
的数组一个空的索引序列会产生原始值不变。
索引
0
会生成一个int32
类型的数组,其有效性位图是最外层结构体和子级a
的位图的交集。索引
1, 1
会生成一个float64
类型的数组,其有效性位图是最外层结构体、结构体b
和子级d
的位图的交集。
对于联合体,基于类型代码合成有效性位图。 此外,索引始终是子索引,而不是类型代码。 因此,对于类型为
sparse_union<2: int32, 7: utf8>
的数组索引
0
生成一个int32
类型的数组,当且仅当子数组a
在索引 n 处有效且索引 n 处的类型代码为 2 时,它在索引 n 处有效。索引
2
和7
无效。
替换函数#
这些函数创建第一个输入的副本,并根据剩余的输入替换某些元素。
函数名称 |
元数 |
输入类型 1 |
输入类型 2 |
输入类型 3 |
输出类型 |
注释 |
---|---|---|---|---|---|---|
fill_null_backward |
一元 |
固定宽度或二进制 |
输入类型 1 |
(1) |
||
fill_null_forward |
一元 |
固定宽度或二进制 |
输入类型 1 |
(1) |
||
replace_with_mask |
三元运算符 |
固定宽度或二进制 |
布尔值 |
输入类型 1 |
输入类型 1 |
(2) |
(1) 有效值向前/向后传递以填充 null 值。
(2) 输入 1 中对应布尔值在输入 2 中为 true 的每个元素都将替换为输入 3 中的下一个值。输入 2 中的 null 值会导致输出中出现对应的 null 值。
另请参见:if_else。
成对函数#
成对函数是一元向量函数,它对输入数组中的一对元素执行二进制运算,通常是对相邻的元素。 第 n 个输出通过将二元运算应用于第 n 个和第 (n-p) 个输入来计算,其中 p 是周期。 默认周期为 1,在这种情况下,二元运算应用于相邻的输入对。 周期也可以为负数,在这种情况下,第 n 个输出通过将二元运算应用于第 n 个和第 (n+abs(p)) 个输入来计算。
函数名称 |
元数 |
输入类型 |
输出类型 |
选项类 |
注释 |
---|---|---|---|---|---|
pairwise_diff |
一元 |
数值/时间 |
数值/时间 |
(1)(2) |
|
pairwise_diff_checked |
一元 |
数值/时间 |
数值/时间 |
(1)(3) |
(1) 计算数组的一阶差分。它内部调用标量函数
Subtract
(或检查过的变体)来计算差分,因此其行为和支持的类型与Subtract
相同。可以在PairwiseOptions
中指定周期。(2) 检测到溢出时,会环绕结果。
(3) 检测到溢出时,返回一个
Invalid
Status
。