计算函数#

通用计算 API#

函数和函数注册表#

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

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

输入形状#

计算输入表示为通用的 Datum 类,它是几种数据形状的标记联合,例如 ScalarArrayChunkedArray。 许多计算函数同时支持数组(分块或不分块)和标量输入,但是某些函数将强制使用特定的输入类型。 例如,虽然 array_sort_indices 要求其第一个也是唯一的输入是数组,但通用的 sort_indices 函数接受数组、分块数组、记录批处理或表。

调用函数#

可以使用 arrow::compute::CallFunction() 通过名称调用计算函数

std::shared_ptr<arrow::Array> numbers_array = ...;
std::shared_ptr<arrow::Scalar> increment = ...;
arrow::Datum incremented_datum;

ARROW_ASSIGN_OR_RAISE(incremented_datum,
                      arrow::compute::CallFunction("add", {numbers_array, increment}));
std::shared_ptr<Array> incremented_array = std::move(incremented_datum).make_array();

(请注意,此示例使用了从 std::shared_ptr<Array>Datum 的隐式转换)

许多计算函数也可以直接作为具体的 API 使用,此处为 arrow::compute::Add()

std::shared_ptr<arrow::Array> numbers_array = ...;
std::shared_ptr<arrow::Scalar> increment = ...;
arrow::Datum incremented_datum;

ARROW_ASSIGN_OR_RAISE(incremented_datum,
                      arrow::compute::Add(numbers_array, increment));
std::shared_ptr<Array> incremented_array = std::move(incremented_datum).make_array();

某些函数接受或需要一个选项结构,该结构确定函数的确切语义

ScalarAggregateOptions scalar_aggregate_options;
scalar_aggregate_options.skip_nulls = false;

std::shared_ptr<arrow::Array> array = ...;
arrow::Datum min_max;

ARROW_ASSIGN_OR_RAISE(min_max,
                      arrow::compute::CallFunction("min_max", {array},
                                                   &scalar_aggregate_options));

// Unpack struct scalar result (a two-field {"min", "max"} scalar)
std::shared_ptr<arrow::Scalar> min_value, max_value;
min_value = min_max.scalar_as<arrow::StructScalar>().value[0];
max_value = min_max.scalar_as<arrow::StructScalar>().value[1];

但是,分组聚合 不能通过 CallFunction 调用。

另请参阅

计算 API 参考

隐式转换#

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

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

公共数值类型#

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

输入类型

公共数值类型

注释

int32, int32

int32

int16, int32

int32

最大宽度为 32,将 LHS 提升为 int32

uint16, int32

int32

一个输入有符号,覆盖无符号

uint32, int32

int64

加宽以适应 uint32 的范围

uint16, uint32

uint32

所有输入均为无符号,保持无符号

int16, uint32

int64

uint64, int16

int64

int64 无法容纳所有 uint64 值

float32, int32

float32

将 RHS 提升为 float32

float32, float64

float64

float32, int64

float32

int64 更宽,仍然提升为 float32

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

可用函数#

类型类别#

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

  • “数值”:整数类型(Int8 等)和浮点类型(Float32、Float64,有时为 Float16)。 某些函数还接受 Decimal128 和 Decimal256 输入。

  • “时间”:日期类型(Date32、Date64)、时间类型(Time32、Time64)、时间戳、持续时间、间隔。

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

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

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

  • “嵌套”:类似列表(包括固定大小列表)、结构体、联合,以及相关类型(如映射)。

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

聚合#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

分组聚合(“group by”)#

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

例如,对于下表

key

x

“a”

2

“a”

5

“b”

null

“b”

null

null

null

null

9

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

key

sum(x)

“a”

7

“b”

null

null

9

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

函数名称

元数

输入类型

输出类型

选项类

注释

hash_all

一元

布尔值

布尔值

ScalarAggregateOptions

(1)

hash_any

一元

布尔值

布尔值

ScalarAggregateOptions

(1)

hash_approximate_median

一元

数值

Float64

ScalarAggregateOptions

hash_count

一元

任何

Int64

CountOptions

(2)

hash_count_all

零元

Int64

hash_count_distinct

一元

任何

Int64

CountOptions

(2)

hash_distinct

一元

任何

输入类型的列表

CountOptions

(2) (3)

hash_first

一元

数值,二进制

输入类型

ScalarAggregateOptions

(11)

hash_first_last

一元

数值,二进制

结构体

ScalarAggregateOptions

(11)

hash_kurtosis

一元

数值

Float64

SkewOptions

(9)

hash_last

一元

数值,二进制

输入类型

ScalarAggregateOptions

(11)

hash_list

一元

任何

输入类型的列表

(3)

hash_max

一元

非嵌套、非二进制/类字符串

输入类型

ScalarAggregateOptions

hash_mean

一元

数值

Decimal/Float64

ScalarAggregateOptions

(4)

hash_min

一元

非嵌套、非二进制/类字符串

输入类型

ScalarAggregateOptions

hash_min_max

一元

非嵌套类型

结构体

ScalarAggregateOptions

(5)

hash_one

一元

任何

输入类型

(6)

hash_pivot_wider

二进制

二进制,字符串,整数(参数 0);任何(参数 1)

结构体

PivotWiderOptions

(7)

hash_product

一元

数值

数值

ScalarAggregateOptions

(8)

hash_skew

一元

数值

Float64

SkewOptions

(9)

hash_stddev

一元

数值

Float64

VarianceOptions

(9)

hash_sum

一元

数值

数值

ScalarAggregateOptions

(8)

hash_tdigest

一元

数值

FixedSizeList[Float64]

TDigestOptions

(10)

hash_variance

一元

数值

Float64

VarianceOptions

(9)

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

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

  • (3) hash_distincthash_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, multiplydivide 及其 checked 变体),不同精度/比例的 decimals 将被适当地提升。 混合的 decimal 和浮点参数会将所有参数强制转换为浮点数,而混合的 decimal 和整数参数会将所有参数强制转换为 decimals。 混合的时间分辨率时间输入将被强制转换为最精细的输入分辨率。

函数名称

元数

输入类型

输出类型

注释

abs

一元

数值/持续时间

数值/持续时间

abs_checked

一元

数值/持续时间

数值/持续时间

add

二进制

数值/时间

数值/时间

(1)

add_checked

二进制

数值/时间

数值/时间

(1)

divide

二进制

数值/时间

数值/时间

(1)

divide_checked

二进制

数值/时间

数值/时间

(1)

exp

一元

数值

Float32/Float64

expm1

一元

数值

Float32/Float64

multiply

二进制

数值/时间

数值/时间

(1)

multiply_checked

二进制

数值/时间

数值/时间

(1)

negate

一元

数值/持续时间

数值/持续时间

negate_checked

一元

有符号数值/持续时间

有符号数值/持续时间

power

二进制

数值

数值

power_checked

二进制

数值

数值

sign

一元

数值/持续时间

Int8/Float32/Float64

(2)

sqrt

一元

数值

数值

sqrt_checked

一元

数值

数值

subtract

二进制

数值/时间

数值/时间

(1)

subtract_checked

二进制

数值/时间

数值/时间

(1)

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

    操作

    结果精度和比例

    add
    subtract
    scale = max(s1, s2)
    precision = max(p1-s1, p2-s2) + 1 + scale

    multiply

    scale = s1 + s2
    precision = p1 + p2 + 1

    divide

    scale = max(4, s1 + p2 - s2 + 1)
    precision = p1 - s1 + s2 + scale

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

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

位运算函数#

函数名称

元数

输入类型

输出类型

bit_wise_and

二进制

数值

数值

bit_wise_not

一元

数值

数值

bit_wise_or

二进制

数值

数值

bit_wise_xor

二进制

数值

数值

shift_left

二进制

数值

数值

shift_left_checked

二进制

数值

数值 (1)

shift_right

二进制

数值

数值

shift_right_checked

二进制

数值

数值 (1)

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

舍入函数#

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

函数名称

元数

输入类型

输出类型

选项类

注释

ceil

一元

数值

Float32/Float64/Decimal

floor

一元

数值

Float32/Float64/Decimal

round

一元

数值

输入类型

RoundOptions

(1)(2)

round_to_multiple

一元

数值

输入类型

RoundToMultipleOptions

(1)(3)

round_binary

二进制

数值

输入类型

RoundBinaryOptions

(1)(4)

trunc

一元

数值

Float32/Float64/Decimal

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

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

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

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

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

round_mode

执行的操作

示例值

DOWN

舍入到最接近的,小于或等于其绝对值的整数;也称为 floor(x)

3.2 -> 3, 3.7 -> 3, -3.2 -> -4, -3.7 -> -4

UP

舍入到最接近的,大于或等于其绝对值的整数;也称为 ceil(x)

3.2 -> 4, 3.7 -> 4, -3.2 -> -3, -3.7 -> -3

TOWARDS_ZERO

获取不带小数位的整数部分;也称为 trunc(x)

3.2 -> 3, 3.7 -> 3, -3.2 -> -3, -3.7 -> -3

TOWARDS_INFINITY

对负值使用 DOWN 规则进行舍入,对正值使用 UP 规则进行舍入

3.2 -> 4, 3.7 -> 4, -3.2 -> -4, -3.7 -> -4

HALF_DOWN

使用 DOWN 规则对 ties 进行舍入

3.5 -> 3, 4.5 -> 4, -3.5 -> -4, -4.5 -> -5

HALF_UP

使用 UP 规则对 ties 进行舍入

3.5 -> 4, 4.5 -> 5, -3.5 -> -3, -4.5 -> -4

HALF_TOWARDS_ZERO

使用 TOWARDS_ZERO 规则对 ties 进行舍入

3.5 -> 3, 4.5 -> 4, -3.5 -> -3, -4.5 -> -4

HALF_TOWARDS_INFINITY

使用 TOWARDS_INFINITY 规则对 ties 进行舍入

3.5 -> 4, 4.5 -> 5, -3.5 -> -4, -4.5 -> -5

HALF_TO_EVEN

将 ties 舍入到最接近的偶数整数

3.5 -> 4, 4.5 -> 4, -3.5 -> -4, -4.5 -> -4

HALF_TO_ODD

将 ties 舍入到最接近的奇数整数

3.5 -> 3, 4.5 -> 5, -3.5 -> -3, -4.5 -> -5

下表给出了 ndigits(对于 roundround_binary 函数)和 multiple(对于 round_to_multiple 函数)分别如何影响执行的操作的示例。

舍入 multiple

舍入 ndigits

执行的操作

1

0

舍入到整数

0.001

3

舍入到小数点后 3 位

10

-1

舍入到 10 的倍数

2

NA

舍入到 2 的倍数

对数函数#

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

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

函数名称

元数

输入类型

输出类型

ln

一元

Float32/Float64/Decimal

Float32/Float64

ln_checked

一元

Float32/Float64/Decimal

Float32/Float64

log10

一元

Float32/Float64/Decimal

Float32/Float64

log10_checked

一元

Float32/Float64/Decimal

Float32/Float64

log1p

一元

Float32/Float64/Decimal

Float32/Float64

log1p_checked

一元

Float32/Float64/Decimal

Float32/Float64

log2

一元

Float32/Float64/Decimal

Float32/Float64

log2_checked

一元

Float32/Float64/Decimal

Float32/Float64

logb

二进制

Float32/Float64/Decimal

Float32/Float64

logb_checked

二进制

Float32/Float64/Decimal

Float32/Float64

三角函数#

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

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

函数名称

元数

输入类型

输出类型

acos

一元

Float32/Float64/Decimal

Float32/Float64

acos_checked

一元

Float32/Float64/Decimal

Float32/Float64

asin

一元

Float32/Float64/Decimal

Float32/Float64

asin_checked

一元

Float32/Float64/Decimal

Float32/Float64

atan

一元

Float32/Float64/Decimal

Float32/Float64

atan2

二进制

Float32/Float64/Decimal

Float32/Float64

cos

一元

Float32/Float64/Decimal

Float32/Float64

cos_checked

一元

Float32/Float64/Decimal

Float32/Float64

sin

一元

Float32/Float64/Decimal

Float32/Float64

sin_checked

一元

Float32/Float64/Decimal

Float32/Float64

tan

一元

Float32/Float64/Decimal

Float32/Float64

tan_checked

一元

Float32/Float64/Decimal

Float32/Float64

双曲三角函数#

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

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

函数名称

元数

输入类型

输出类型

acosh

一元

Float32/Float64/Decimal

Float32/Float64

acosh_checked

一元

Float32/Float64/Decimal

Float32/Float64

asinh

一元

Float32/Float64/Decimal

Float32/Float64

atanh

一元

Float32/Float64/Decimal

Float32/Float64

atanh_checked

一元

Float32/Float64/Decimal

Float32/Float64

cosh

一元

Float32/Float64/Decimal

Float32/Float64

sinh

一元

Float32/Float64/Decimal

Float32/Float64

tanh

一元

Float32/Float64/Decimal

Float32/Float64

比较#

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

函数名

元数

输入类型

输出类型

equal

二进制

数字、Temporal、Binary- 和 String-like

布尔值

greater

二进制

数字、Temporal、Binary- 和 String-like

布尔值

greater_equal

二进制

数字、Temporal、Binary- 和 String-like

布尔值

less

二进制

数字、Temporal、Binary- 和 String-like

布尔值

less_equal

二进制

数字、Temporal、Binary- 和 String-like

布尔值

not_equal

二进制

数字、Temporal、Binary- 和 String-like

布尔值

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

函数名

元数

输入类型

输出类型

选项类

注释

max_element_wise

Varargs

数字、Temporal、Binary- 和 String-like

数字或 Temporal

ElementWiseAggregateOptions

(1)

min_element_wise

Varargs

数字、Temporal、Binary- 和 String-like

数字或 Temporal

ElementWiseAggregateOptions

(1)

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

逻辑函数#

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

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

因此,对于 Kleene 逻辑变体

  • “true AND null”、“null AND true”给出“null”(结果未定义)

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

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

  • “false OR null”、“null OR false”给出“null”(结果未定义)

函数名称

元数

输入类型

输出类型

二进制

布尔值

布尔值

and_kleene

二进制

布尔值

布尔值

and_not

二进制

布尔值

布尔值

and_not_kleene

二进制

布尔值

布尔值

invert

一元

布尔值

布尔值

or

二进制

布尔值

布尔值

or_kleene

二进制

布尔值

布尔值

xor

二进制

布尔值

布尔值

字符串谓词#

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

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

函数名称

元数

输入类型

输出类型

匹配的字符类

注释

ascii_is_alnum

一元

String-like

布尔值

字母数字 ASCII

ascii_is_alpha

一元

String-like

布尔值

字母 ASCII

ascii_is_decimal

一元

String-like

布尔值

十进制 ASCII

(1)

ascii_is_lower

一元

String-like

布尔值

小写 ASCII

(2)

ascii_is_printable

一元

String-like

布尔值

可打印 ASCII

ascii_is_space

一元

String-like

布尔值

空格 ASCII

ascii_is_upper

一元

String-like

布尔值

大写 ASCII

(2)

utf8_is_alnum

一元

String-like

布尔值

字母数字 Unicode

utf8_is_alpha

一元

String-like

布尔值

字母 Unicode

utf8_is_decimal

一元

String-like

布尔值

十进制 Unicode

utf8_is_digit

一元

String-like

布尔值

Unicode 数字

(3)

utf8_is_lower

一元

String-like

布尔值

小写 Unicode

(2)

utf8_is_numeric

一元

String-like

布尔值

数字 Unicode

(4)

utf8_is_printable

一元

String-like

布尔值

可打印 Unicode

utf8_is_space

一元

String-like

布尔值

空格 Unicode

utf8_is_upper

一元

String-like

布尔值

大写 Unicode

(2)

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

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

  • (3) 当前与 utf8_is_decimal 相同。

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

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

函数名称

元数

输入类型

输出类型

注释

ascii_is_title

一元

String-like

布尔值

(1)

utf8_is_title

一元

String-like

布尔值

(1)

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

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

函数名称

元数

输入类型

输出类型

注释

string_is_ascii

一元

String-like

布尔值

(1)

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

字符串转换#

函数名称

元数

输入类型

输出类型

选项类

注释

ascii_capitalize

一元

String-like

String-like

(1)

ascii_lower

一元

String-like

String-like

(1)

ascii_reverse

一元

String-like

String-like

(2)

ascii_swapcase

一元

String-like

String-like

(1)

ascii_title

一元

String-like

String-like

(1)

ascii_upper

一元

String-like

String-like

(1)

binary_length

一元

Binary- 或 String-like

Int32 或 Int64

(3)

binary_repeat

二进制

Binary/String (Arg 0); Integral (Arg 1)

Binary- 或 String-like

(4)

binary_replace_slice

一元

String-like

Binary- 或 String-like

ReplaceSliceOptions

(5)

binary_reverse

一元

二进制

二进制

(6)

replace_substring

一元

String-like

String-like

ReplaceSubstringOptions

(7)

replace_substring_regex

一元

String-like

String-like

ReplaceSubstringOptions

(8)

utf8_capitalize

一元

String-like

String-like

(9)

utf8_length

一元

String-like

Int32 或 Int64

(10)

utf8_lower

一元

String-like

String-like

(9)

utf8_replace_slice

一元

String-like

String-like

ReplaceSliceOptions

(7)

utf8_reverse

一元

String-like

String-like

(11)

utf8_swapcase

一元

String-like

String-like

(9)

utf8_title

一元

String-like

String-like

(9)

utf8_upper

一元

String-like

String-like

(9)

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

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

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

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

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

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

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

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

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

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

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

字符串填充#

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

函数名称

元数

输入类型

输出类型

选项类

ascii_center

一元

String-like

String-like

PadOptions

ascii_lpad

一元

String-like

String-like

PadOptions

ascii_rpad

一元

String-like

String-like

PadOptions

utf8_center

一元

String-like

String-like

PadOptions

utf8_lpad

一元

String-like

String-like

PadOptions

utf8_rpad

一元

String-like

String-like

PadOptions

字符串修剪#

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

函数名称

元数

输入类型

输出类型

选项类

注释

ascii_ltrim

一元

String-like

String-like

TrimOptions

(1)

ascii_ltrim_whitespace

一元

String-like

String-like

(2)

ascii_rtrim

一元

String-like

String-like

TrimOptions

(1)

ascii_rtrim_whitespace

一元

String-like

String-like

(2)

ascii_trim

一元

String-like

String-like

TrimOptions

(1)

ascii_trim_whitespace

一元

String-like

String-like

(2)

utf8_ltrim

一元

String-like

String-like

TrimOptions

(3)

utf8_ltrim_whitespace

一元

String-like

String-like

(4)

utf8_rtrim

一元

String-like

String-like

TrimOptions

(3)

utf8_rtrim_whitespace

一元

String-like

String-like

(4)

utf8_trim

一元

String-like

String-like

TrimOptions

(3)

utf8_trim_whitespace

一元

String-like

String-like

(4)

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

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

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

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

字符串分割#

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

函数名称

元数

输入类型

输出类型

选项类

注释

ascii_split_whitespace

一元

String-like

List-like

SplitOptions

(1)

split_pattern

一元

Binary- 或 String-like

List-like

SplitPatternOptions

(2)

split_pattern_regex

一元

Binary- 或 String-like

List-like

SplitPatternOptions

(3)

utf8_split_whitespace

一元

String-like

List-like

SplitOptions

(4)

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

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

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

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

字符串组件提取#

函数名称

元数

输入类型

输出类型

选项类

注释

extract_regex

一元

Binary- 或 String-like

结构体

ExtractRegexOptions

(1)

extract_regex_span

一元

Binary- 或 String-like

结构体

ExtractRegexSpanOptions

(2)

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

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

字符串连接#

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

函数名称

元数

输入类型 1

输入类型 2

输出类型

选项类

注释

binary_join

二进制

Binary- or String-like 的列表

String-like

String-like

(1)

binary_join_element_wise

Varargs

Binary- or String-like (varargs)

Binary- 或 String-like

Binary- 或 String-like

JoinOptions

(2)

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

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

字符串切片#

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

函数名称

元数

输入类型

输出类型

选项类

注释

binary_slice

一元

Binary-like

Binary-like

SliceOptions

(1)

utf8_slice_codeunits

一元

String-like

String-like

SliceOptions

(2)

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

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

包含测试#

函数名称

元数

输入类型

输出类型

选项类

注释

count_substring

一元

Binary- 或 String-like

Int32 或 Int64

MatchSubstringOptions

(1)

count_substring_regex

一元

Binary- 或 String-like

Int32 或 Int64

MatchSubstringOptions

(1)

ends_with

一元

Binary- 或 String-like

布尔值

MatchSubstringOptions

(2)

find_substring

一元

Binary- and String-like

Int32 或 Int64

MatchSubstringOptions

(3)

find_substring_regex

一元

Binary- and String-like

Int32 或 Int64

MatchSubstringOptions

(3)

index_in

一元

Boolean, Null, Numeric, Temporal, Binary- and String-like

Int32

SetLookupOptions

(4)

is_in

一元

Boolean, Null, Numeric, Temporal, Binary- and String-like

布尔值

SetLookupOptions

(5)

match_like

一元

Binary- 或 String-like

布尔值

MatchSubstringOptions

(6)

match_substring

一元

Binary- 或 String-like

布尔值

MatchSubstringOptions

(7)

match_substring_regex

一元

Binary- 或 String-like

布尔值

MatchSubstringOptions

(8)

starts_with

一元

Binary- 或 String-like

布尔值

MatchSubstringOptions

(2)

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

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

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

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

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

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

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

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

分类#

函数名称

元数

输入类型

输出类型

选项类

注释

is_finite

一元

Null, Numeric

布尔值

(1)

is_inf

一元

Null, Numeric

布尔值

(2)

is_nan

一元

Null, Numeric

布尔值

(3)

is_null

一元

任何

布尔值

NullOptions

(4)

is_valid

一元

任何

布尔值

(5)

true_unless_null

一元

任何

布尔值

(6)

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

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

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

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

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

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

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

选择 / 多路复用#

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

函数名称

元数

输入类型

输出类型

注释

case_when

Varargs

Boolean 的结构 (Arg 0), 任何 (其余)

输入类型

(1)

choose

Varargs

Integral (Arg 0), 定宽/类似二进制 (其余)

输入类型

(2)

coalesce

Varargs

任何

输入类型

(3)

if_else

三元运算符

Boolean (Arg 0), 任何 (其余)

输入类型

(4)

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

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

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

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

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

    另请参见:replace_with_mask

结构转换#

函数名称

元数

输入类型

输出类型

选项类

注释

list_value_length

一元

List-like

Int32 或 Int64

(1)

make_struct

Varargs

任何

结构体

MakeStructOptions

(2)

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

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

转换#

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

函数名称

元数

输入类型

输出类型

选项类

注释

ceil_temporal

一元

Temporal

Temporal

RoundTemporalOptions

floor_temporal

一元

Temporal

Temporal

RoundTemporalOptions

round_temporal

一元

Temporal

Temporal

RoundTemporalOptions

cast

一元

Many

Variable

CastOptions

strftime

一元

Temporal

String

StrftimeOptions

(1)

strptime

一元

String-like

Timestamp

StrptimeOptions

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

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

真值提取

输入类型

输出类型

注释

Binary- and String-like

布尔值

(1)

数值

布尔值

(2)

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

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

同类转换

输入类型

输出类型

注释

Int32

32 位时间

(1)

Int64

64 位时间

(1)

(Large)Binary

(Large)String

(2)

(Large)String

(Large)Binary

(3)

数值

数值

(4) (5)

32 位时间

Int32

(1)

64 位时间

Int64

(1)

Temporal

Temporal

(4) (5)

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

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

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

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

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

字符串表示

输入类型

输出类型

注释

布尔值

String-like

数值

String-like

通用转换

输入类型

输出类型

注释

Dictionary

Dictionary 值类型

(1)

Extension

Extension 存储类型

结构体

结构体

(2)

List-like

List-like 或 (Large)ListView

(3)

(Large)ListView

List-like 或 (Large)ListView

(4)

Map

Map 或 List of two-field struct

(5)

Null

任何

任何

Extension

(6)

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

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

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

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

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

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

时间分量提取#

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

函数名称

元数

输入类型

输出类型

选项类

注释

day

一元

Temporal

Int64

day_of_week

一元

Temporal

Int64

DayOfWeekOptions

(1)

day_of_year

一元

Temporal

Int64

hour

一元

Timestamp, Time

Int64

is_dst

一元

Timestamp

布尔值

iso_week

一元

Temporal

Int64

(2)

iso_year

一元

Temporal

Int64

(2)

iso_calendar

一元

Temporal

结构体

(3)

is_leap_year(是否为闰年)

一元

Timestamp, Date(时间戳,日期)

布尔值

microsecond(微秒)

一元

Timestamp, Time

Int64

millisecond(毫秒)

一元

Timestamp, Time

Int64

minute(分钟)

一元

Timestamp, Time

Int64

month(月份)

一元

Temporal

Int64

nanosecond(纳秒)

一元

Timestamp, Time

Int64

quarter(季度)

一元

Temporal

Int64

second(秒)

一元

Timestamp, Time

Int64

subsecond(亚秒)

一元

Timestamp, Time

Float64

us_week(美式周)

一元

Temporal

Int64

(4)

us_year(美式年份)

一元

Temporal

Int64

(4)

week(周)

一元

Timestamp

Int64

WeekOptions(周选项)

(5)

year(年份)

一元

Temporal

Int64

year_month_day(年_月_日)

一元

Temporal

结构体

(6)

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

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

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

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

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

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

时间差#

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

函数名称

元数

输入类型

输出类型

选项类

day_time_interval_between(日_时间_间隔_之间)

二进制

Temporal

DayTime interval(日时间隔)

days_between(天_之间)

二进制

Timestamp, Date(时间戳,日期)

Int64

hours_between(小时_之间)

二进制

Temporal

Int64

microseconds_between(微秒_之间)

二进制

Temporal

Int64

milliseconds_between(毫秒_之间)

二进制

Temporal

Int64

minutes_between(分钟_之间)

二进制

Temporal

Int64

month_day_nano_interval_between(月_日_纳秒_间隔_之间)

二进制

Temporal

MonthDayNano interval(月日纳秒间隔)

month_interval_between(月_间隔_之间)

二进制

Timestamp, Date(时间戳,日期)

Month interval(月间隔)

nanoseconds_between(纳秒_之间)

二进制

Temporal

Int64

quarters_between(季度_之间)

二进制

Timestamp, Date(时间戳,日期)

Int64

seconds_between(秒_之间)

二进制

Temporal

Int64

weeks_between(周_之间)

二进制

Timestamp, Date(时间戳,日期)

Int64

DayOfWeekOptions

years_between(年_之间)

二进制

Timestamp, Date(时间戳,日期)

Int64

时区处理#

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

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

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

函数名称

元数

输入类型

输出类型

选项类

注释

assume_timezone(假定时区)

一元

Timestamp

Timestamp

AssumeTimezoneOptions(假定时区选项)

(1)

local_timestamp(本地时间戳)

一元

Timestamp

Timestamp

(2)

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

随机数生成#

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

函数名称

元数

输出类型

选项类

random(随机)

零元

Float64

RandomOptions(随机选项)

数组式(“向量”)函数#

累积函数#

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

函数名称

元数

输入类型

输出类型

选项类

注释

cumulative_sum(累积_和)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_sum_checked(累积_和_已检查)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_prod(累积_积)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_prod_checked(累积_积_已检查)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_max(累积_最大值)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_min(累积_最小值)

一元

数值

数值

CumulativeOptions(累积选项)

(1)

cumulative_mean(累积_平均值)

一元

数值

Float64

CumulativeOptions(累积选项)

(1) (2)

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

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

统计函数#

函数名称

元数

输入类型

输出类型

选项类

注释

winsorize(缩尾)

一元

数值

数值

WinsorizeOptions(缩尾选项)

(1)

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

关联变换#

函数名称

元数

输入类型

输出类型

注释

dictionary_encode(字典编码)

一元

Boolean, Null, Numeric, Temporal, Binary- and String-like

Dictionary

(1)

unique(唯一)

一元

Boolean, Null, Numeric, Temporal, Binary- and String-like

输入类型

(2)

value_counts(值计数)

一元

Boolean, Null, Numeric, Temporal, Binary- and String-like

输入类型

(3)

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

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

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

选择#

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

函数名称

元数

输入类型 1

输入类型 2

输出类型

选项类

注释

array_filter(数组_过滤)

二进制

任何

布尔值

输入类型 1

FilterOptions(过滤选项)

(2)

array_take(数组_取)

二进制

任何

Integer(整数)

输入类型 1

TakeOptions(取选项)

(3)

drop_null(删除_空值)

一元

任何

输入类型 1

(1)

filter(过滤)

二进制

任何

布尔值

输入类型 1

FilterOptions(过滤选项)

(2)

inverse_permutation(逆_置换)

一元

Signed Integer(有符号整数)

Signed Integer (4)(有符号整数(4))

InversePermutationOptions(逆置换选项)

(5)

scatter(散布)

二进制

任何

Integer(整数)

输入类型 1

ScatterOptions(散布选项)

(6)

take(取)

二进制

任何

Integer(整数)

输入类型 1

TakeOptions(取选项)

(3)

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

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

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

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

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

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

包含性测试#

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

函数名称

元数

输入类型

输出类型

选项类

注释

indices_nonzero

一元

布尔型、Null、数值型、十进制

UInt64

排序和分区#

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

注意

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

函数名称

元数

输入类型

输出类型

选项类

注释

array_sort_indices

一元

布尔型、数值型、时间型、二进制和类似字符串

UInt64

ArraySortOptions

(1) (2)

partition_nth_indices

一元

布尔型、数值型、时间型、二进制和类似字符串

UInt64

PartitionNthOptions

(3)

rank

一元

布尔型、数值型、时间型、二进制和类似字符串

UInt64

RankOptions

(4)

rank_normal

一元

布尔型、数值型、时间型、二进制和类似字符串

Float64

RankQuantileOptions

(5)

rank_quantile

一元

布尔型、数值型、时间型、二进制和类似字符串

Float64

RankQuantileOptions

(5)

select_k_unstable

一元

布尔型、数值型、时间型、二进制和类似字符串

UInt64

SelectKOptions

(6) (7)

sort_indices

一元

布尔型、数值型、时间型、二进制和类似字符串

UInt64

SortOptions

(1) (6)

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

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

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

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

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

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

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

结构转换#

函数名称

元数

输入类型

输出类型

选项类

注释

list_element

二进制

类似列表 (Arg 0), 整数 (Arg 1)

列表值类型

(1)

list_flatten

一元

List-like

列表值类型

(2)

list_parent_indices

一元

List-like

Int64

(3)

list_slice

一元

List-like

List-like

ListSliceOptions

(4)

map_lookup

一元

Map

已计算

MapLookupOptions

(5)

struct_field

一元

结构体或联合体

已计算

StructFieldOptions

(6)

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

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

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

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

  • (5) 从键与通过选项传递的给定查询键匹配的映射中提取 FIRSTLASTALL 项。 输出类型是 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 处有效。

    • 索引 27 无效。

替换函数#

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

函数名称

元数

输入类型 1

输入类型 2

输入类型 3

输出类型

注释

fill_null_backward

一元

固定宽度或二进制

输入类型 1

(1)

fill_null_forward

一元

固定宽度或二进制

输入类型 1

(1)

replace_with_mask

三元运算符

固定宽度或二进制

布尔值

输入类型 1

输入类型 1

(2)

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

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

    另请参见:if_else

成对函数#

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

函数名称

元数

输入类型

输出类型

选项类

注释

pairwise_diff

一元

数值/时间

数值/时间

PairwiseOptions

(1)(2)

pairwise_diff_checked

一元

数值/时间

数值/时间

PairwiseOptions

(1)(3)

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

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

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