作者：yunjinqi 类别：
日期：2023-10-16 20:11:40
阅读：122 次 消耗积分：0 分
条件
这些函数根据给定的条件选择两个输入之一（或不作选择）。
(1) 此函数的行为类似于SQL中的"case when"语句或开关-情况。输入是一个"条件"值，它是一个包含布尔值的结构，然后是每个"分支"的值。对于"条件"结构的每个子元素，必须要有一个对应的值参数，或者比子元素多一个值参数（这种情况下就有一个"else"或"default"值）。输出的类型与值输入的类型相同；对于每一行，它将从第一个值数据中选择相应的值，其中对应的布尔值为true，或者从"default"输入中选择对应的值，否则为null。
需要注意的是，尽管目前支持所有类型，但字典类型将被展开。
(2) 第一个输入必须是整数类型。其余的参数可以是任何类型，但它们必须是相同类型或可以提升为公共类型。第一个输入（'索引'）的每个值都被用作对剩余参数的零基索引（即，索引0是第二个参数，索引1是第三个参数，依此类推），并且输出值将在该行选择的输入值对应值。如果索引为null，那么输出也将为null。
(3) 输出的每一行将是第一个输入的对应值，只要该行不为null，否则为null。
(4) 第一个输入必须是布尔标量或数组。第二个和第三个输入可以是标量或数组，并且它们必须是相同的类型。输出是与第二/第三个输入相同类型的数组（如果所有输入都是标量，那么输出也将是标量）。如果第一个输入中存在null值，它们将被提升到输出中，否则根据第一个输入的值选择null值。
结构性转换
转换
提供了一个名为cast的通用转换函数，可以接受大量的输入和输出类型。可以通过CastOptions实例传递要转换的类型。作为替代，还提供了一个名为Cast()的具体函数。
cast可用的转换如下所示。在所有情况下，将null输入值转换为null输出值。
真值提取
(1) 输出为真，当相应的输入值具有非零长度时。
(2) 输出为真，当相应的输入值为非零时。
相同类型转换
字符串表示
通用转换
(1) 字典的索引保持不变，字典的值从输入值类型转换为输出值类型（如果有可用的转换）。
(2) 输出类型的字段名称必须与输入类型的字段名称相同或是输入类型字段名称的子集；它们还必须具有相同的顺序。将字段名“选择”为子集，以使每个输出字段与具有相同名称的输入字段的数据匹配。
(3) 列表偏移保持不变，列表值从输入值类型转换为输出值类型（如果有可用的转换）。
(4) 偏移保持不变，键和值从相应的输入转换为输出类型（如果有可用的转换）。如果输出类型是结构的列表，则键字段将作为第一个字段输出，值字段将作为第二个字段输出，无论所选的字段名如何。
(5) 任何可以转换为生成扩展存储类型的输入类型。这不包括扩展类型，除非转换为相同的扩展类型。
时间组件提取
这些函数从时间类型中提取日期时间组件（年、月、日等）。对于带有非空时区的时间戳输入，将返回本地时间戳组件。
(1) 输出是星期的天数。默认情况下，星期从星期一（表示为0）开始，星期日（表示为6）结束。星期编号可以从0或1开始，具体取决于DayOfWeekOptions::count_from_zero参数。DayOfWeekOptions::week_start可用于使用ISO约定设置星期的起始日（星期一=1，星期日=7）。DayOfWeekOptions::week_start参数不受DayOfWeekOptions::count_from_zero影响。
(2) 第一个ISO周大部分（4个或更多）的日子都在一月份。ISO年从第一个ISO周开始。ISO周从星期一开始。有关更多详情，请参阅ISO 8601周日期定义。
(3) 输出是一个结构{"iso_year": 输出类型, "iso_week": 输出类型, "iso_day_of_week": 输出类型}。
(4) 第一个美国周大部分（4个或更多）的日子都在一月份。美国年从第一个美国周开始。美国周从星期日开始。
(5) 返回允许设置几个参数的周编号。如果WeekOptions::week_starts_monday为true，则周从星期一开始，否则如果为false，则从星期日开始。如果WeekOptions::count_from_zero为true，则从当前年份的日期属于前一年的最后一个ISO周的日期将编号为周0，否则为周52或53（如果为false）。如果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年份不同。
时区处理
assume_timezone函数用于在外部系统生成“时区无关”时间戳时，需要将其转换为“时区感知”时间戳（例如，Python文档中的定义）。
假定输入时间戳是相对于AssumeTimezoneOptions::timezone中给定的时区的。它们被转换为相对于UTC的时间戳，并设置时区元数据为上述值。如果时间戳已经具有时区元数据，将返回错误。
local_timestamp函数将UTC相对时间戳转换为本地的“时区无关”时间戳。时区来自输入时间戳的时区元数据。此函数是assume_timezone的逆操作。请注意：所有时间函数已经按照提供的时区元数据中的本地时间操作。只有在外部系统期望本地时间戳时才应使用local_timestamp。
(1) 除了时区值之外，AssumeTimezoneOptions还允许在给定时区中时间戳是模糊的或不存在时的行为。这是因为夏令时转换引起的。
随机数生成
这个函数生成一个处于范围[0, 1)内的均匀分布的双精度浮点数数组。选项提供了输出的长度和生成随机数的算法，使用种子或系统提供的平台特定随机生成器。
数组级别（"矢量"）函数
累积函数
累积函数是一种矢量函数，使用具有标识元素（单半群）的给定二进制关联操作在其输入上执行运行累积，并输出包含相应中间运行值的数组。预期输入是数值类型。默认情况下，这些函数不会检测溢出。它们还提供了一个检查溢出的变体，带有_checked后缀，当检测到溢出时返回Invalid状态。
关联转换
(1) 输出为Dictionary(Int32，输入类型)。
(2) 从输出中删除重复项，同时保持原始顺序。
(3) 输出是一个{"values": 输入类型，"counts": Int64}结构。每个输出元素对应于输入中的唯一值，以及该值出现的次数。
选择
这些函数选择并返回其输入的子集。
(1) 不支持稀疏联合。
(2) 仅当非空时，将每个输入元素追加到输出中。如果输入是记录批处理或表格，列中的任何空值将导致整行丢弃。
(3) 仅当输入类型1（值）的每个元素对应的输入类型2（过滤器）为true时，将输入类型1的每个元素追加到输出中。可以使用FilterOptions配置如何处理过滤器中的空值。
(4) 对于输入类型2（索引）中的每个元素i，将输入类型1（值）中的第i个元素追加到输出中。
包含测试
此函数返回数组元素非空且非零的索引。
排序和分区
默认情况下，在这些函数中，空值被视为大于任何其他值（它们将被排序或分区在数组末尾）。浮点NaN值被视为大于任何其他非空值，但小于空值。可以使用各自选项类中的null_placement设置更改此行为。
注意
对于二进制和类似字符串输入，按字节排序，即使对于字符串类型也是如此。
(1) 输出是输入的索引数组，定义输入的稳定排序。
(2) 输入必须是数组。默认排序顺序是升序。
(3) 输出是一个指向输入数组的索引数组，定义非稳定排序，使得第N个索引指向排序后的第N个元素，并且在N之前的所有索引指向小于等于排序后的第N个元素的元素（类似于std::nth_element()）。N在PartitionNthOptions::pivot中给出。
(4) 输出是基于一的数值排名数组
(5) 输入可以是数组、分块数组、记录批处理或表格。如果输入是记录批处理或表格，则必须指定一个或多个排序键。
(6) 输出是一个指向输入的索引数组，定义输入的非稳定排序。
结构变换
(1) 输出是一个与输入列表数组的长度相同的数组。输出值是每个子列表的指定索引处的值。
(2) 最外层的嵌套被移除：列表子数组中的所有值，包括空值，都附加到输出中。但是，父列表数组中的空值将被丢弃。
(3) 对于列表子数组中的每个值，将其在列表数组中找到的索引附加到输出中。父列表数组中的空值将被丢弃。
(4) 对于每个列表元素，计算该列表元素的切片，然后返回另一个类似列表的数组，其中包含这些切片。可以根据提供的选项返回一个固定大小或可变大小的类似列表的数组。
(5) 从键与通过选项传递的查询键匹配的映射中提取FIRST、LAST或ALL项目。输出类型为FIRST/LAST选项的项目数组和ALL选项的项目列表数组。
(6) 根据通过选项传递的索引序列提取子值。结果的有效位图将是所有中间有效位图的交集。例如，对于具有类型struct<a: int32, b: struct<c: int64, d: float64>>的数组：
对于联合，将基于类型代码合成有效位图。此外，索引始终是子索引，而不是类型代码。因此，对于具有类型sparse_union<2: int32, 7: utf8>的数组：
这些函数创建了第一个输入的副本，并根据剩余的输入替换一些元素。
(1) 有效值向前/向后传递以填充空值。
(2) 对于输入1中的每个元素，如果输入2中相应的布尔值为true，则将其替换为输入3中的下一个值。输入2中的空值会导致输出中的相应空值。
另请参阅：if_else。
成对函数
成对函数是一元向量函数，它在输入数组的一对元素上执行二进制操作，通常在相邻元素上执行。第n个输出通过将二进制操作应用于第n和第(n-p)个输入来计算，其中p是周期。默认周期为1，此时将二进制操作应用于相邻的输入对。周期也可以为负数，在这种情况下，第n个输出通过将二进制操作应用于第n和第(n+abs(p))个输入来计算。
(1) 计算数组的一阶差分，它在内部调用标量函数Subtract（或其检查变体）来计算差异，因此其行为和支持的类型与Subtract相同。可以在PairwiseOptions中指定周期。
(2) 当检测到溢出时，结果会循环。
(3) 当检测到溢出时，返回无效状态。
京公网安备 11010702002337 号