計算函數

通用計算 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）、時間戳記、持續時間、間隔。

• 「二進制類」：二進制、大型二進制，有時也包括 FixedSizeBinary。

• 「字串類」：字串、大型字串。

• 「列表類」：列表、大型列表、ListView、大型 ListView，有時也包括 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": 輸入類型, "max": 輸入類型} 結構。

  在間隔類型中，僅支援月份間隔，因為日-時間和月-日-奈秒類型不可排序。

• (6) 輸出是一個 {"mode": 輸入類型, "count": Int64} 結構陣列。它包含輸入中最常見的 N 個元素，按降序排列，其中 N 在 ModeOptions::n 中給出。如果兩個值具有相同的計數，則較小的值排在前面。請注意，如果輸入的相異值少於 N 個，則輸出可能少於 N 個元素。

• (7) 輸出為 Int64、UInt64、Float64 或 Decimal128/256，具體取決於輸入類型。

• (8) 輸出為 Float64 或輸入類型，具體取決於 QuantileOptions。

• (9) 十進制參數首先轉換為 Float64。

• (10) tdigest/t-digest 計算近似分位數，因此只需要固定量的記憶體。請參閱 參考實作 以了解詳細資訊。

• (11) 結果基於輸入資料的順序

  十進制參數首先轉換為 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，它改為控制是否發出空值。這永遠不會影響分組鍵，只會影響群組值（即，您可能會獲得一個鍵為 null 的群組）。

• (3) hash_distinct 和 hash_list 將分組的值收集到一個列表陣列中。

• (4) 對於十進制輸入，結果十進制將具有相同的精度和小數位數。結果四捨五入遠離零。

• (5) 輸出是一個 {"min": 輸入類型, "max": 輸入類型} 結構陣列。

  在間隔類型中，僅支援月份間隔，因為日-時間和月-日-奈秒類型不可排序。

• (6) hash_one 針對每個群組從輸入傳回一個任意值。該函數偏向於非空值：如果某個群組至少有一個非空值，則傳回該值，只有當群組的所有值都為 null 時，函數才會傳回 null。

• (7) 輸出為 Int64、UInt64、Float64 或 Decimal128/256，具體取決於輸入類型。

• (8) 十進制參數首先轉換為 Float64。

• (9) T-digest 計算近似分位數，因此只需要固定量的記憶體。請參閱 參考實作 以了解詳細資訊。

• (10) 結果基於輸入資料的順序。

  十進制參數首先轉換為 Float64。

元素級（“純量”）函數

所有元素級函數都接受陣列和純量作為輸入。一元函數的語義如下

• 純量輸入產生純量輸出

• 陣列輸入產生陣列輸出

二元函數具有以下語義（在其他系統（如 NumPy）中有時稱為「廣播」）

• (純量, 純量) 輸入產生純量輸出

• (陣列, 陣列) 輸入產生陣列輸出（並且兩個輸入的長度必須相同）

• (純量, 陣列) 和 (陣列, 純量) 產生陣列輸出。純量輸入的處理方式就像它是與另一個輸入長度 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
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 的十進制提升規則相容。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	不適用	捨入到 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

比較

這些函數期望兩個數值類型的輸入（在這種情況下，它們將在比較之前轉換為 通用數值類型 ），或兩個二進制或字串類型的輸入，或兩個時間類型的輸入。如果任何輸入是字典編碼的，則將為比較目的展開它。如果一對輸入元素中的任何一個為 null，則對應的輸出元素為 null。十進制參數將以與 add 和 subtract 相同的方式提升。

函數名稱	元數	輸入類型	輸出類型
equal	二元	數值、時間、二進制和字串類	布林值
greater	二元	數值、時間、二進制和字串類	布林值
greater_equal	二元	數值、時間、二進制和字串類	布林值
less	二元	數值、時間、二進制和字串類	布林值
less_equal	二元	數值、時間、二進制和字串類	布林值
not_equal	二元	數值、時間、二進制和字串類	布林值

這些函數接受任何數量的數值型別輸入（在比較之前，它們將被轉換為通用數值型別）或時間型別輸入。如果任何輸入是字典編碼，它將為了比較的目的而被展開。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
max_element_wise	不定參數 (Varargs)	數值、時間、二進制和字串類	數值或時間型別	ElementWiseAggregateOptions	(1)
min_element_wise	不定參數 (Varargs)	數值、時間、二進制和字串類	數值或時間型別	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_kleene	二元	布林值	布林值
and_not	二元	布林值	布林值
and_not_kleene	二元	布林值	布林值
invert	一元	布林值	布林值
or	二元	布林值	布林值
or_kleene	二元	布林值	布林值
xor	二元	布林值	布林值

字串謂詞

這些函數根據輸入字串元素的字符內容对其进行分類。空的字串元素在輸出中發出 false。對於函數的 ASCII 變體（前綴為 ascii_），包含非 ASCII 字符的字串元素在輸出中發出 false。

第一組函數逐字符操作，如果輸入僅包含給定類別的字符，則在輸出中發出 true

函數名稱	元數	輸入類型	輸出類型	匹配的字符類別	註解
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) 僅當輸入字串元素為標題大小寫時，輸出才為 true，即任何單詞都以大寫字符開頭，後跟小寫字符。單詞邊界由非大小寫字符定義。

第三組函數逐字節檢查字串元素

函數名稱	元數	輸入類型	輸出類型	註解
string_is_ascii	一元	字串類型	布林值	(1)

• (1) 僅當輸入字串元素僅包含 ASCII 字符（即 [0, 127] 範圍內的字節）時，輸出才為 true。

字串轉換

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
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，LargeBinary/LargeString 的輸出類型為 Int64。

• (4) 將輸入二進制字串重複給定的次數。

• (5) 將子字串的切片從 ReplaceSliceOptions::start（包含）到 ReplaceSliceOptions::stop（排除）替換為 ReplaceSubstringOptions::replacement。二進制核心以字節為單位測量切片，而 UTF8 核心以碼位為單位測量切片。

• (6) 執行字節級別的反轉。

• (7) 將與 ReplaceSubstringOptions::pattern 匹配的非重疊子字串替換為 ReplaceSubstringOptions::replacement。如果 ReplaceSubstringOptions::max_replacements != -1，則它確定從左側開始進行的最大替換次數。

• (8) 使用 Google RE2 庫，將與正則表達式 ReplaceSubstringOptions::pattern 匹配的非重疊子字串替換為 ReplaceSubstringOptions::replacement。如果 ReplaceSubstringOptions::max_replacements != -1，則它確定從左側開始進行的最大替換次數。請注意，如果模式包含群組，則可以使用反向引用。

• (9) 輸入中的每個 UTF8 編碼字符都轉換為小寫或大寫。

• (10) 輸出是每個輸入元素的字符數（不是字節數）。字串的輸出類型為 Int32，LargeString 的輸出類型為 Int64。

• (11) 每個 UTF8 編碼的碼位都以相反的順序寫入輸出。如果輸入不是有效的 UTF8，則輸出未定義（但將保留輸出緩衝區的大小）。

字串填充

這些函數附加/前置給定的填充字節 (ASCII) 或碼位 (UTF8)，以便居中 (center)、右對齊 (lpad) 或左對齊 (rpad) 字串。

函數名稱	元數	輸入類型	輸出類型	選項類別
ascii_center	一元	字串類型	字串類型	PadOptions
ascii_lpad	一元	字串類型	字串類型	PadOptions
ascii_rpad	一元	字串類型	字串類型	PadOptions
utf8_center	一元	字串類型	字串類型	PadOptions
utf8_lpad	一元	字串類型	字串類型	PadOptions
utf8_rpad	一元	字串類型	字串類型	PadOptions

字串修剪

這些函數修剪掉兩側 (trim) 或左側 (ltrim) 或右側 (rtrim) 的字符。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
ascii_ltrim	一元	字串類型	字串類型	TrimOptions	(1)
ascii_ltrim_whitespace	一元	字串類型	字串類型		(2)
ascii_rtrim	一元	字串類型	字串類型	TrimOptions	(1)
ascii_rtrim_whitespace	一元	字串類型	字串類型		(2)
ascii_trim	一元	字串類型	字串類型	TrimOptions	(1)
ascii_trim_whitespace	一元	字串類型	字串類型		(2)
utf8_ltrim	一元	字串類型	字串類型	TrimOptions	(3)
utf8_ltrim_whitespace	一元	字串類型	字串類型		(4)
utf8_rtrim	一元	字串類型	字串類型	TrimOptions	(3)
utf8_rtrim_whitespace	一元	字串類型	字串類型		(4)
utf8_trim	一元	字串類型	字串類型	TrimOptions	(3)
utf8_trim_whitespace	一元	字串類型	字串類型		(4)

• (1) 僅會修剪掉 TrimOptions::characters 中指定的字符。輸入字串和 characters 參數都被解釋為 ASCII 字符。

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

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

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

字串分割

這些函數將字串分割成字串列表。所有核心都可以選擇配置 max_splits 和 reverse 參數，其中 max_splits == -1 表示沒有限制（預設值）。當 reverse 為 true 時，分割從字串末尾開始進行；這僅在給定正數 max_splits 時才相關。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
ascii_split_whitespace	一元	字串類型	列表類型	SplitOptions	(1)
split_pattern	一元	二進制或字串類型	列表類型	SplitPatternOptions	(2)
split_pattern_regex	一元	二進制或字串類型	列表類型	SplitPatternOptions	(3)
utf8_split_whitespace	一元	字串類型	列表類型	SplitOptions	(4)

• (1) 非零長度的 ASCII 定義空白字節序列（'\t'、'\n'、'\v'、'\f'、'\r' 和 ' '）被視為分隔符。

• (2) 當找到完全匹配的模式時，字串被分割（模式本身不包含在輸出中）。

• (3) 當找到正則表達式匹配時，字串被分割（匹配的子字串本身不包含在輸出中）。

• (4) 非零長度的 Unicode 定義空白碼位序列被視為分隔符。

字串組件提取

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
extract_regex	一元	二進制或字串類型	結構	ExtractRegexOptions	(1)

• (1) 使用 Google RE2 庫提取由正則表達式定義的子字串。輸出結構字段名稱參考命名的捕獲群組，例如正則表達式 (?P<letter>[ab])(?P<digit>\\d) 的 'letter' 和 'digit'。

字串連接

這些函數執行字串分割的逆操作。

函數名稱	元數	輸入類型 1	輸入類型 2	輸出類型	選項類別	註解
binary_join	二元	二進制或字串類型列表	字串類型	字串類型		(1)
binary_join_element_wise	不定參數 (Varargs)	二進制或字串類型 (不定參數)	二進制或字串類型	二進制或字串類型	JoinOptions	(2)

• (1) 第一個輸入必須是陣列，而第二個可以是純量或陣列。第一個輸入中的每個值列表都使用每個第二個輸入作為分隔符連接。如果任何輸入列表為 Null 或包含 Null 值，則相應的輸出將為 Null。

• (2) 所有參數都以元素方式連接，最後一個參數被視為分隔符（在任何情況下都會回收純量）。Null 分隔符發出 Null 值。如果任何其他參數為 Null，則預設情況下，相應的輸出將為 Null，但它可以選擇跳過或替換為給定的字串。

字串切片

此函數根據起始和停止索引以及非零步長（預設為 1）將陣列的每個序列轉換為子序列。切片語義遵循 Python 切片語義：起始索引是包含的，停止索引是排除的；如果步長為負數，則序列按相反順序進行。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
binary_slice	一元	二進制類型	二進制類型	SliceOptions	(1)
utf8_slice_codeunits	一元	字串類型	字串類型	SliceOptions	(2)

• (1) 將字串切片為由 SliceOptions 給定的 (start, stop, step) 定義的子字串，其中 start 和 stop 以字節為單位測量。Null 輸入發出 Null 值。

• (2) 將字串切片為由 SliceOptions 給定的 (start, stop, step) 定義的子字串，其中 start 和 stop 以碼位為單位測量。Null 輸入發出 Null 值。

包含性測試

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
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	一元	布林值、Null 值、數值、時間型別、二進制和字串類型	Int32	SetLookupOptions	(4)
is_in	一元	布林值、Null 值、數值、時間型別、二進制和字串類型	布林值	SetLookupOptions	(5)
match_like	一元	二進制或字串類型	布林值	MatchSubstringOptions	(6)
match_substring	一元	二進制或字串類型	布林值	MatchSubstringOptions	(7)
match_substring_regex	一元	二進制或字串類型	布林值	MatchSubstringOptions	(8)
starts_with	一元	二進制或字串類型	布林值	MatchSubstringOptions	(2)

• (1) 輸出是 MatchSubstringOptions::pattern 在相應輸入字串中出現的次數。二進制/字串的輸出類型為 Int32，LargeBinary/LargeString 的輸出類型為 Int64。

• (2) 如果 MatchSubstringOptions::pattern 是相應輸入的後綴/前綴，則輸出為 true。

• (3) 輸出是 MatchSubstringOptions::pattern 在相應輸入字串中首次出現的索引，否則為 -1。二進制/字串的輸出類型為 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 值、數值	布林值		(1)
is_inf	一元	Null 值、數值	布林值		(2)
is_nan	一元	Null 值、數值	布林值		(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	不定參數 (Varargs)	布林值結構 (參數 0)，任何類型 (其餘)	輸入類型	(1)
choose	不定參數 (Varargs)	整數 (參數 0)，固定寬度/二進制類型 (其餘)	輸入類型	(2)
coalesce	不定參數 (Varargs)	任何	輸入類型	(3)
if_else	三元運算	布林值 (參數 0)，任何類型 (其餘)	輸入類型	(4)

• (1) 此函數的作用類似於 SQL “case when” 語句或 switch-case。輸入是一個“條件”值，它是一個布林值結構，後跟每個“分支”的值。條件結構的每個子項必須恰好有一個值參數，或者比子項多一個值參數（在後一種情況下，我們有一個“else”或“default”值）。輸出類型與值輸入的類型相同；每一行將是第一個布林值為 true 的值數據中的相應值，或者是來自“default”輸入的相應值，否則為 Null。

  請注意，目前，雖然支援所有類型，但字典將被解封裝。

• (2) 第一個輸入必須是整數類型。其餘參數可以是任何類型，但都必須是相同的類型或可提升為通用類型。第一個輸入（“索引”）的每個值都用作其餘參數的從零開始的索引（即，索引 0 是第二個參數，索引 1 是第三個參數，依此類推），並且該行的輸出的值將是選定輸入在該行的相應值。如果索引為 Null，則輸出也將為 Null。

• (3) 輸出的每一行將是該行第一個為非 Null 的輸入的相應值，否則為 Null。

• (4) 第一個輸入必須是布林值純量或陣列。第二個和第三個輸入可以是純量或陣列，並且必須是相同的類型。輸出是與第二/第三個輸入類型相同的陣列（如果所有輸入都是純量，則為純量）。如果第一個輸入中存在 Null 值，它們將被提升到輸出，否則將根據第一個輸入值選擇 Null 值。

  另請參閱：replace_with_mask。

結構轉換

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
list_value_length	一元	列表類型	Int32 或 Int64		(1)
make_struct	不定參數 (Varargs)	任何	結構	MakeStructOptions	(2)

• (1) 每個輸出元素都是相應輸入元素的長度（如果輸入為 Null，則為 Null）。列表、ListView 和 FixedSizeList 的輸出類型為 Int32，LargeList 和 LargeListView 的輸出類型為 Int64。

• (2) 輸出結構的字段類型是其參數的類型。字段名稱使用 MakeStructOptions 的實例指定。如果所有輸入都是純量，則輸出形狀將為純量，否則任何純量都將廣播到陣列。

轉換

提供了一個名為 cast 的通用轉換函數，它接受大量的輸入和輸出類型。要轉換成的類型可以在 CastOptions 實例中傳遞。作為替代方案，具體函數 Cast() 提供了相同的服務。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
ceil_temporal	一元	時間型別	時間型別	RoundTemporalOptions
floor_temporal	一元	時間型別	時間型別	RoundTemporalOptions
round_temporal	一元	時間型別	時間型別	RoundTemporalOptions
cast	一元	多種	可變	CastOptions
strftime	一元	時間型別	字串	StrftimeOptions	(1)
strptime	一元	字串類型	時間戳記	StrptimeOptions

下面列出了 cast 提供的轉換。在所有情況下，Null 輸入值都會轉換為 Null 輸出值。

• (1) %S（秒）標誌的輸出精度取決於輸入時間戳記精度。具有秒精度的時間戳記表示為整數，而毫秒、微秒和奈秒表示為具有分別為 3、6 和 9 位小數的固定浮點數。要獲得整數秒，請轉換為具有秒解析度的時間戳記。小數點的字符根據語言環境本地化。有關其他標誌的描述，請參閱 詳細的格式化文檔。

真值提取

輸入類型	輸出類型	註解
二進制和字串類型	布林值	(1)
數值	布林值	(2)

• (1) 如果相應的輸入值具有非零長度，則輸出為 true。

• (2) 如果相應的輸入值為非零，則輸出為 true。

同類型轉換

輸入類型	輸出類型	註解
Int32	32 位元時間型別	(1)
Int64	64 位元時間型別	(1)
(Large)二進制	(Large)字串	(2)
(Large)字串	(Large)二進制	(3)
數值	數值	(4) (5)
32 位元時間型別	Int32	(1)
64 位元時間型別	Int64	(1)
時間型別	時間型別	(4) (5)

• (1) 無操作轉換：原始值保持不變，僅類型更改。

• (2) 如果 CastOptions::allow_invalid_utf8 為 false，則驗證內容。

• (3) 無操作轉換：僅類型更改。

• (4) 溢出和截斷檢查根據給定的 CastOptions 啟用。

• (5) 並非所有此類轉換都已實現。

字串表示形式

輸入類型	輸出類型	註解
布林值	字串類型
數值	字串類型

通用轉換

輸入類型	輸出類型	註解
字典	字典值類型	(1)
擴展	擴展存儲類型
結構	結構	(2)
列表類型	列表類型或 (Large)ListView	(3)
(Large)ListView	列表類型或 (Large)ListView	(4)
Map	Map 或雙字段結構列表	(5)
Null 值	任何
任何	擴展	(6)

• (1) 字典索引保持不變，字典值從輸入值類型轉換為輸出值類型（如果轉換可用）。

• (2) 輸出類型的字段名稱必須與輸入類型的字段名稱相同或為其子集；它們也必須具有相同的順序。轉換為字段名稱的子集“選擇”這些字段，以便每個輸出字段都與具有相同名稱的輸入字段的數據匹配。

• (3) 列表偏移量保持不變，列表值從輸入值類型轉換為輸出值類型（如果轉換可用）。如果輸出類型為 (Large)ListView，則大小從偏移量派生。

• (4) 如果輸出類型為列表類型，則可能必須重建偏移量（因此，值陣列）以進行排序並適當間隔。如果輸出類型為列表視圖類型，則偏移量和大小保持不變。在任何情況下，列表值都從輸入值類型轉換為輸出值類型（如果轉換可用）。

• (5) 偏移量保持不變，鍵和值從各自的輸入類型轉換為輸出類型（如果轉換可用）。如果輸出類型是結構列表，則鍵字段作為第一個字段輸出，值字段作為第二個字段輸出，無論選擇的字段名稱如何。

• (6) 可以轉換為結果擴展的存儲類型的任何輸入類型。這不包括擴展類型，除非轉換為相同的擴展類型。

時間組件提取

這些函數從時間型別中提取日期時間組件（年、月、日等）。對於具有非空時區的時間戳記輸入，將返回本地化的時間戳記組件。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
day	一元	時間型別	Int64
day_of_week	一元	時間型別	Int64	DayOfWeekOptions	(1)
day_of_year	一元	時間型別	Int64
hour	一元	時間戳記、時間	Int64
is_dst	一元	時間戳記	布林值
iso_week	一元	時間型別	Int64		(2)
iso_year	一元	時間型別	Int64		(2)
iso_calendar	一元	時間型別	結構		(3)
is_leap_year	一元	時間戳記、日期	布林值
microsecond	一元	時間戳記、時間	Int64
millisecond	一元	時間戳記、時間	Int64
minute	一元	時間戳記、時間	Int64
month	一元	時間型別	Int64
nanosecond	一元	時間戳記、時間	Int64
quarter	一元	時間型別	Int64
second	一元	時間戳記、時間	Int64
subsecond	一元	時間戳記、時間	Float64
us_week	一元	時間型別	Int64		(4)
us_year	一元	時間型別	Int64		(4)
week	一元	時間戳記	Int64	WeekOptions	(5)
year	一元	時間型別	Int64
year_month_day	一元	時間型別	結構		(6)

• (1) 輸出星期幾的數字。預設情況下，星期從星期一（表示為 0）開始，到星期日（表示為 6）結束。日期編號可以從 0 或 1 開始，具體取決於 DayOfWeekOptions::count_from_zero 參數。DayOfWeekOptions::week_start 可用於使用 ISO 慣例（星期一=1，星期日=7）設定星期的開始日。DayOfWeekOptions::week_start 參數不受 DayOfWeekOptions::count_from_zero 的影響。

• (2) 第一個 ISO 週在其一月中有大多數（4 天或更多）的天數。ISO 年從第一個 ISO 週開始。ISO 週從星期一開始。有關更多詳細信息，請參閱 ISO 8601 週日期定義。

• (3) 輸出是一個 {"iso_year": 輸出類型, "iso_week": 輸出類型, "iso_day_of_week":  輸出類型} 結構。

• (4) 第一個美國週在其一月中有大多數（4 天或更多）的天數。美國年從第一個美國週開始。美國週從星期日開始。

• (5) 返回週數，允許設定多個參數。如果 WeekOptions::week_starts_monday 為 true，則週從星期一開始，否則如果為 false，則從星期日開始。如果 WeekOptions::count_from_zero 為 true，則當年屬於上一年最後一個 ISO 週的日期編號為第 0 週，否則如果為 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	二元	時間型別	DayTime 間隔
days_between	二元	時間戳記、日期	Int64
hours_between	二元	時間型別	Int64
microseconds_between	二元	時間型別	Int64
milliseconds_between	二元	時間型別	Int64
minutes_between	二元	時間型別	Int64
month_day_nano_interval_between	二元	時間型別	MonthDayNano 間隔
month_interval_between	二元	時間戳記、日期	Month 間隔
nanoseconds_between	二元	時間型別	Int64
quarters_between	二元	時間戳記、日期	Int64
seconds_between	二元	時間型別	Int64
weeks_between	二元	時間戳記、日期	Int64	DayOfWeekOptions
years_between	二元	時間戳記、日期	Int64

時區處理

assume_timezone 函數旨在用於外部系統產生“時區感知不足”的時間戳記時，這些時間戳記需要轉換為“時區感知”時間戳記（例如，請參閱 Python 文檔中的 定義）。

假設輸入時間戳記是相對於 AssumeTimezoneOptions::timezone 中指定的時區。它們會被轉換為 UTC 相對時間戳記，並將時區元數據設定為上述值。如果時間戳記已經設定了時區元數據，則會返回錯誤。

local_timestamp 函數將 UTC 相對時間戳記轉換為本地「不含時區資訊」的時間戳記。時區取自輸入時間戳記的時區元數據。此函數是 assume_timezone 的反向操作。請注意：所有時間函數都已經以元數據提供的時區本地時間運行時間戳記。僅當外部系統期望本地時間戳記時，才應使用 local_timestamp。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
assume_timezone	一元	時間戳記	時間戳記	AssumeTimezoneOptions	(1)
local_timestamp	一元	時間戳記	時間戳記		(2)

• (1) 除了時區值之外，AssumeTimezoneOptions 還允許選擇在給定時區中時間戳記模糊或不存在時（由於日光節約時間調整）的行為。

隨機數生成

此函數生成一個陣列，其中包含 [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 被忽略。

結合轉換

函數名稱	元數	輸入類型	輸出類型	註解
dictionary_encode	一元	布林值、Null 值、數值、時間型別、二進制和字串類型	字典	(1)
unique	一元	布林值、Null 值、數值、時間型別、二進制和字串類型	輸入類型	(2)
value_counts	一元	布林值、Null 值、數值、時間型別、二進制和字串類型	輸入類型	(3)

• (1) 輸出為 Dictionary(Int32, input type)。如果輸入已經是 Dictionary 陣列，則不執行任何操作。

• (2) 重複項會從輸出中移除，同時保持原始順序。

• (3) 輸出為 {"values": input type, "counts": Int64} 結構。每個輸出元素對應於輸入中的唯一值，以及此值出現的次數。

選擇

這些函數選擇並返回其輸入的子集。

函數名稱	元數	輸入類型 1	輸入類型 2	輸出類型	選項類別	註解
array_filter	二元	任何	布林值	輸入類型 1	FilterOptions	(2)
array_take	二元	任何	Integer	輸入類型 1	TakeOptions	(3)
drop_null	一元	任何		輸入類型 1		(1)
filter	二元	任何	布林值	輸入類型 1	FilterOptions	(2)
take	二元	任何	Integer	輸入類型 1	TakeOptions	(3)

• (1) 輸入中的每個元素都會附加到輸出，前提是它不是 null 值。如果輸入是記錄批次或表格，則任何列中的任何 null 值都會捨棄整行。

• (2) 輸入 1（值）中的每個元素都會附加到輸出，前提是輸入 2（篩選器）中的對應元素為 true。篩選器中 null 值的處理方式可以使用 FilterOptions 進行配置。

• (3) 對於輸入 2（索引）中的每個元素 i，輸入 1（值）中的第 i 個元素會附加到輸出。

包含性測試

此函數返回陣列元素為非 null 且非零的索引。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
indices_nonzero	一元	Boolean, Null, Numeric, Decimal	UInt64

排序和分割

預設情況下，在這些函數中，null 值被認為大於任何其他值（它們將在陣列的末尾排序或分割）。浮點 NaN 值被認為大於任何其他非 null 值，但小於 null 值。此行為可以使用各選項類別中的 null_placement 設定進行更改。

注意

二進制和類字串輸入會按照字節串以詞彙順序排序，即使對於字串類型也是如此。

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
array_sort_indices	一元	Boolean, Numeric, Temporal, Binary- and String-like	UInt64	ArraySortOptions	(1) (2)
partition_nth_indices	一元	Boolean, Numeric, Temporal, Binary- and String-like	UInt64	PartitionNthOptions	(3)
rank	一元	Boolean, Numeric, Temporal, Binary- and String-like	UInt64	RankOptions	(4)
select_k_unstable	一元	Boolean, Numeric, Temporal, Binary- and String-like	UInt64	SelectKOptions	(5) (6)
sort_indices	一元	Boolean, Numeric, Temporal, Binary- and String-like	UInt64	SortOptions	(1) (5)

• (1) 輸出是一個索引陣列，指向輸入，定義了輸入的穩定排序。

• (2) 輸入必須是陣列。預設順序為升序。

• (3) 輸出是一個索引陣列，指向輸入陣列，定義了部分非穩定排序，使得第 N 個索引指向排序順序中的第 N 個元素，並且第 N 個索引之前的所有索引指向小於或等於第 N 個索引或之後的元素的元素（類似於 std::nth_element()）。N 在 PartitionNthOptions::pivot 中給出。

• (4) 輸出是一個基於一的數值排序陣列

• (5) 輸入可以是陣列、分塊陣列、記錄批次或表格。如果輸入是記錄批次或表格，則必須指定一個或多個排序鍵。

• (6) 輸出是一個索引陣列，指向輸入，定義了輸入的非穩定排序。

結構轉換

函數名稱	元數	輸入類型	輸出類型	選項類別	註解
list_element	二元	List-like (Arg 0), Integral (Arg 1)	List value type		(1)
list_flatten	一元	列表類型	List value type		(2)
list_parent_indices	一元	列表類型	Int64		(3)
list_slice	一元	列表類型	列表類型	ListSliceOptions	(4)
map_lookup	一元	Map	Computed	MapLookupOptions	(5)
struct_field	一元	Struct or Union	Computed	StructFieldOptions	(6)

• (1) 輸出是一個與輸入列表陣列長度相同的陣列。輸出值是每個子列表的指定索引處的值。

• (2) 移除了最上層的巢狀結構：列表子陣列中的所有值（包括 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	一元	數值/時間	數值/時間	PairwiseOptions	(1)(2)
pairwise_diff_checked	一元	數值/時間	數值/時間	PairwiseOptions	(1)(3)

• (1) 計算陣列的一階差分。它在內部調用純量函數 Subtract（或檢查過的變體）來計算差分，因此其行為和支援的類型與 Subtract 相同。週期可以在 PairwiseOptions 中指定。

• (2) 當檢測到溢位時，會環繞結果。

• (3) 當檢測到溢位時，返回 Invalid Status。