Apache DataFusion 标量函数完全指南

Apache DataFusion 标量函数完全指南

datafusion Apache DataFusion SQL Query Engine 项目地址: https://gitcode.com/gh_mirrors/datafu/datafusion

概述

Apache DataFusion 是一个高性能的查询执行框架，它提供了丰富的 SQL 标量函数支持。标量函数是 SQL 中最基础也最常用的函数类型，它们对单个值进行操作并返回单个值。本文将全面介绍 DataFusion 中支持的各种标量函数，包括数学函数、条件函数和字符串函数。

数学函数

基础数学运算

1. 绝对值函数 abs(x)

   • 返回数值的绝对值
   • 示例：abs(-3.5) 返回 3.5

2. 幂函数 power(base, exponent)

   • 计算 base 的 exponent 次幂
   • 别名：pow
   • 示例：power(2, 3) 返回 8

3. 平方根 sqrt(x)

   • 计算数值的平方根
   • 示例：sqrt(9) 返回 3

4. 立方根 cbrt(x)

   • 计算数值的立方根
   • 示例：cbrt(27) 返回 3

三角函数

1. 基本三角函数：

   • sin(x)：正弦函数
   • cos(x)：余弦函数
   • tan(x)：正切函数

2. 反三角函数：

   • asin(x)：反正弦
   • acos(x)：反余弦
   • atan(x)：反正切
   • atan2(y, x)：计算 y/x 的反正切

3. 双曲函数：

   • sinh(x)：双曲正弦
   • cosh(x)：双曲余弦
   • tanh(x)：双曲正切

对数函数

1. 自然对数 ln(x)

   • 计算以 e 为底的对数
   • 示例：ln(7.389) ≈ 2

2. 常用对数 log10(x)

   • 计算以 10 为底的对数
   • 示例：log10(100) 返回 2

3. 二进制对数 log2(x)

   • 计算以 2 为底的对数
   • 示例：log2(8) 返回 3

4. 通用对数 log(base, x)

   • 计算任意基数的对数
   • 示例：log(3, 27) 返回 3

舍入函数

1. 向上取整 ceil(x)

   • 返回不小于 x 的最小整数
   • 示例：ceil(3.2) 返回 4

2. 向下取整 floor(x)

   • 返回不大于 x 的最大整数
   • 示例：floor(3.9) 返回 3

3. 四舍五入 round(x, [decimal_places])

   • 可指定保留小数位数
   • 示例：round(3.14159, 2) 返回 3.14

4. 截断 trunc(x, [decimal_places])

   • 直接截断小数部分
   • 示例：trunc(3.9) 返回 3

其他实用数学函数

1. 最大公约数 gcd(x, y)

   • 计算两个数的最大公约数
   • 示例：gcd(12, 18) 返回 6

2. 最小公倍数 lcm(x, y)

   • 计算两个数的最小公倍数
   • 示例：lcm(4, 6) 返回 12

3. 阶乘 factorial(n)

   • 计算 n 的阶乘
   • 示例：factorial(5) 返回 120

4. 随机数 random()

   • 生成 [0,1) 区间的随机数
   • 每行生成不同的随机数

条件函数

空值处理

1. COALESCE coalesce(expr1, expr2, ...)

   • 返回第一个非 NULL 的表达式
   • 示例：coalesce(NULL, 1, 2) 返回 1

2. NULLIF nullif(expr1, expr2)

   • 当 expr1 = expr2 时返回 NULL，否则返回 expr1
   • 示例：nullif(5, 5) 返回 NULL

3. NVL nvl(expr1, expr2)

   • 如果 expr1 为 NULL 则返回 expr2，否则返回 expr1
   • 示例：nvl(NULL, 10) 返回 10

4. NVL2 nvl2(expr1, expr2, expr3)

   • 如果 expr1 不为 NULL 则返回 expr2，否则返回 expr3
   • 示例：nvl2(NULL, 10, 20) 返回 20

特殊判断

1. ISNAN isnan(x)

   • 判断是否为 NaN
   • 示例：isnan(0.0/0.0) 返回 true

2. ISZERO iszero(x)

   • 判断是否为 +0.0 或 -0.0
   • 示例：iszero(0.0) 返回 true

3. NANVL nanvl(expr1, expr2)

   • 如果 expr1 不是 NaN 则返回 expr1，否则返回 expr2
   • 示例：nanvl(0.0/0.0, 10) 返回 10

字符串函数

字符串基本信息

1. 长度函数：

   • length(str)：字符长度
   • bit_length(str)：位长度
   • octet_length(str)：字节长度

2. ASCII 转换：

   • ascii(str)：获取第一个字符的 ASCII 码
   • chr(code)：根据 ASCII/Unicode 码返回字符

3. 大小写转换：

   • lower(str)：转换为小写
   • upper(str)：转换为大写
   • initcap(str)：首字母大写

字符串操作

1. 连接函数：

   • concat(str1, str2, ...)：简单连接
   • concat_ws(separator, str1, str2, ...)：带分隔符连接

2. 截取函数：

   • left(str, n)：左侧 n 个字符
   • right(str, n)：右侧 n 个字符
   • substr(str, start, [length])：子字符串

3. 填充函数：

   • lpad(str, length, [pad_str])：左侧填充
   • rpad(str, length, [pad_str])：右侧填充

4. 修剪函数：

   • trim(str)：两端去空格
   • ltrim(str)：左侧去空格
   • rtrim(str)：右侧去空格
   • btrim(str, [trim_str])：两端去指定字符

5. 替换函数：

   • replace(str, from_str, to_str)：简单替换
   • translate(str, from_set, to_set)：字符集替换

字符串搜索与比较

1. 位置查找：

   • strpos(str, substr)：子串位置
   • instr(str, substr)：子串位置
   • position(substr IN str)：子串位置

2. 前缀后缀：

   • starts_with(str, prefix)：是否以指定前缀开头
   • ends_with(str, suffix)：是否以指定后缀结尾

3. 包含判断：

   • contains(str, substr)：是否包含子串
   • find_in_set(str, str_list)：在逗号分隔列表中查找

4. 其他高级函数：

   • levenshtein(str1, str2)：计算编辑距离
   • reverse(str)：字符串反转
   • split_part(str, delimiter, field)：分割字符串取部分
   • substr_index(str, delim, count)：按分隔符截取

最佳实践

1. 性能考虑：

   • 复杂的字符串操作可能影响性能，尽量在应用层处理
   • 数学函数通常比字符串函数更高效

2. NULL 处理：

   • 使用条件函数妥善处理 NULL 值
   • 注意 NULL 在数学运算中的传播特性

3. 类型一致性：

   • 确保函数参数类型匹配
   • 注意隐式类型转换可能带来的问题

4. 函数组合：

   • 可以嵌套使用多个函数实现复杂逻辑
   • 例如：upper(substr(name, 1, 1)) 获取首字母并大写

总结

Apache DataFusion 提供了丰富的标量函数集，覆盖了数学运算、条件判断和字符串处理等常见需求。熟练掌握这些函数可以大大提高 SQL 查询的表达能力和效率。在实际使用中，建议根据具体场景选择最合适的函数，并注意性能优化和 NULL 值处理。

datafusion Apache DataFusion SQL Query Engine 项目地址: https://gitcode.com/gh_mirrors/datafu/datafusion