Documentation
搜索文档
karat

+

K

API 参考 ↗
分析ContourExpressions语法和支持的函数

注意：以下翻译的准确性尚未经过验证。这是使用 AIP ↗ 从原始英文文本进行的机器翻译。

语法和支持的函数

有关表达式面板的介绍，请参阅使用表达式面板的指南。本文档是使用Contour丰富表达式语言的资源，可用作类型、操作和函数的参考。

数据类型

您可以在表达式中使用以下数据类型：

字符串

字符串用单引号表示：

'This is a string'

这是一个字符串

通过添加第二个单引号来转义字符串中的单引号：

'I''m a string'

我是一个字符串

使用||运算符将列连接为字符串：

"Gender" || "MaritalStatus"

您还可以将列与常量连接。

'$' || ("salaryColumn"/1000.0) || 'k'

整数

整数是非浮点数：

5

双精度

双精度是浮点数：

5.7

布尔值

布尔变量可以是true或false。布尔变量不区分大小写。

日期

您可以将格式为YYYY-MM或YYYY-MM-DD的字符串转换为日期：

CAST('2016-12-06' AS DATE)

您也可以将字符串转换为时间戳：

CAST('2016-12-06` `01:12:34' AS TIMESTAMP)

在对时间戳进行操作时，最好先将时间戳转换为长整型，或在需要毫秒精度时转换为双精度。这将为您提供UNIX时间中的秒数。

例如，假设您有两个时间戳列：“start”和“end”。要确定两个时间之间的分钟数，您可以使用以下表达式：

(CAST("end" as LONG) - CAST("start" as LONG)) / 60.

将长整型转换为时间戳假设长整型值以秒为单位。如果您的数据以毫秒为单位，请在转换之前除以1000。

操作

以下部分概述了您可以在表达式中使用的操作及其优先级：

算术

通过其他数值列或常量对数值列（整数或双精度）进行加、减、乘和除操作：+, -, *, /

  • "tipAmount" / "fare"
  • "diameter" * 3.14

比较

使用>（大于）、>=（大于或等于）、<（小于）、<=（小于或等于）将任意类型的列与其他列或常量进行比较。结果为一列布尔值。

  • "age" > "averageAge"
  • "totalDistance" < 5

相等比较

检查某行在两个列中是否具有相同值，使用==，或不同值，使用!=。

  • "cityOfBirth" == "cityOfResidence"

您还可以将列值与常量进行比较。

  • "Gender" == 'M'
字符串比较

在比较两个字符串时，使用字典序排序。注意，这在比较包含数字的字符串时可能会产生反直觉的结果。例如：

  • 'Alligator' < 'Boat' => TRUE，因为'A'的编码小于'B'
  • 'Alliance' < 'Alligator' => TRUE，因为'a'小于'g'
  • 'Zoo' < 'alpha' => TRUE，因为'Z'小于'a'
  • 'Zoo' < 'Zoologist' => TRUE，因为如果一个字符串是另一个字符串的前缀，则较短的字符串被认为较小
  • '1' < '2' => TRUE，因为字符串字符'1'小于字符串字符'2'
  • '10' < '2' => TRUE，因为其第一个字符串字符'1'小于字符串字符'2'；注意这是对字符串'10'和'2'的比较，而不是整数10和2
  • '10' < '20' => TRUE，因为'1'小于'2'
与Spark SQL的行为差异

在Contour表达式语言中，与NULL的相等比较具有以下行为。

  • NULL = 'DATA' => FALSE
  • NULL != 'DATA' => TRUE
  • NULL = NULL => TRUE
  • NULL != NULL => FALSE

然而，在Spark SQL中，所有这些表达式返回NULL。在Contour表达式和Spark SQL之间进行转换时，考虑这种行为差异以产生一致的结果是很重要的。

布尔比较

通过对一个或多个列进行布尔逻辑运算来派生新的布尔列。

  • "Age" >=70 AND "Gender" = 'M'

类型转换

类型转换允许您更改列或表达式的类型。您可以转换为布尔值、整数、双精度、日期和时间戳。

  • CAST("startDate" AS DATE)
  • CAST("startTime" AS TIMESTAMP)
  • CAST("numParticipants" AS INTEGER)

Case/When/End

Case语句允许您在一个表达式中评估多种可能性。每个语句按顺序进行评估，并执行第一个评估为true的THEN语句。

Copied!
1
2
3
4
5
CASE
    WHEN "age" < 13 THEN 'Child' -- 如果年龄小于13岁，则为儿童
    WHEN "age" > 19 THEN 'Adult' -- 如果年龄大于19岁，则为成人
    ELSE 'Teenager'             -- 否则为青少年
END
Copied!
1
2
3
4
5
CASE MaritalStatus
    WHEN 'S' THEN 'Single'   -- 如果婚姻状态是 'S'，则返回 'Single'（单身）
    WHEN 'M' THEN 'Married'  -- 如果婚姻状态是 'M'，则返回 'Married'（已婚）
    ELSE 'Unknown'           -- 如果婚姻状态是其他值，则返回 'Unknown'（未知）
END

Like

在列中搜索指定模式。请参阅有关 SQL LIKE ↗ 的文档以了解更多信息。

Null Checks

检查值是否 IS NULL 或 IS NOT NULL。返回布尔值。

优先级

表达式中操作的优先级按以下列表详细说明，从最高优先级到最低优先级。位于同一行的操作具有相同的优先级。

  1. +, -, NOT (一元)
  2. || (二元)
  3. *, /, % (二元)
  4. +, - (二元)
  5. <, <=, >, >= (二元)
  6. =, ==, !=', <>, IS, IS NOT, LIKE, RLIKE (二元)
  7. IS NULL, NOT NULL (一元)
  8. IN, NOT IN
  9. AND (二元)
  10. OR (二元)

函数

以下是列表达式中可用函数的完整列表。

数学和数值函数

  • ABS: 计算绝对值。
  • CBRT: 计算给定值的立方根。
  • CEIL: 计算给定值的上限。
  • COS: 计算给定值的余弦。
  • EXP: 计算给定值的指数。
  • FACTORIAL: 计算给定值的阶乘。
  • FLOOR: 计算给定值的下限。
  • FORMAT_NUMBER: 将数字列arg0格式化为类似‘#,###,###.##’的格式，四舍五入到arg1位小数，并返回结果为一个字符串列（注意：arg1必须是整数字面量）。
  • ISNAN: 如果且仅当列为NaN时返回true。
  • LN: 计算给定值的自然对数。
  • LOG: 计算以arg0为底的arg1的对数（注意：arg0必须是数字字面量）。
  • POW: 返回arg0的arg1次幂的值。
  • ROUND: 返回四舍五入到arg1位小数的arg0值（注意：arg1必须是整数字面量）。
  • RTRIM: 从指定字符串值的右端去除空格。
  • SIN: 计算给定列的正弦。
  • SQRT: 计算指定浮点值的平方根。
  • TAN: 计算给定值的正切。

字符串函数

  • CONCAT: 将多个输入字符串列连接成一个字符串列。
  • CONCAT_WS: 使用给定的分隔符将多个输入字符串列连接成一个字符串列（注意：arg0必须是字符串字面量）。
  • FORMAT_STRING: 根据 Java Formatter ↗ 格式化参数，并将结果返回为一个字符串列。
  • LENGTH: 计算给定字符串或二进制列的长度。
  • LEVENSHTEIN: 计算两个给定字符串列的Levenshtein距离。
  • LOWER: 将字符串列转换为小写。
  • LPAD: 返回字符串列arg0，左填充到长度arg1，使用字符串arg2（注意：arg1必须是整数字面量，arg2必须是字符串字面量）。
  • LTRIM: 从指定字符串值的左端去除空格。
  • REGEXP_EXTRACT: 根据正则表达式arg1匹配字符串列arg0并提取特定的组arg2（1索引）。如果正则表达式不匹配，或指定的组不匹配，则返回空字符串。（注意：arg1必须是字符串字面量，arg2必须是整数字面量）。
  • REGEXP_REPLACE: 将arg0中匹配arg1的所有子串替换为arg2。
  • REVERSE: 反转字符串列并返回为一个新的字符串列。
  • RPAD: 返回字符串列arg0，右填充到长度arg1，使用字符串arg2（注意：arg1必须是整数字面量，arg2必须是字符串字面量）。
  • SPLIT: 根据正则表达式字符串arg1拆分字符串列arg0（注意：arg1必须是字符串字面量）。
  • SUBSTRING: 从arg0的起始索引arg1（1索引）开始，返回长度为arg2的子字符串（注意：arg1和arg2必须是整数字面量）。
  • TRIM: 从指定字符串列的两端去除空格。
  • UPPER: 将字符串列转换为大写。

日期/时间函数

有关派生相对日期的更多信息和示例，请参阅 派生相对日期的参考文档。

  • ADD_MONTHS: 返回arg0之后arg1个月的日期（注意：arg1必须是整数字面量）
  • CURRENT_DATE: 返回当前日期作为日期列。这些值仅在路径重新计算时更新。为了避免在看板中出现不一致的值，建议每天更新路径。
  • CURRENT_TIMESTAMP: 返回当前时间戳作为时间戳列。这些值仅在路径重新计算时更新。
  • CURRENT_UNIX_TIMESTAMP: 返回当前时间戳为秒数。这些值仅在路径重新计算时更新。
  • DATE_ADD: 返回arg0之后arg1天的日期（注意：arg1必须是整数字面量）。
  • DATE_FORMAT: 将日期/时间戳arg0转换为arg1指定格式的字符串（注意：arg1必须是字符串字面量）。
  • DATE_SUB: 返回arg0之前arg1天的日期，并根据 Java SimpleDateFormat ↗ 格式化（注意：arg1必须是整数字面量）。
  • DATE_TRUNC: 返回按格式arg0指定的单位截断的日期/时间戳arg1。
  • DATE_DIFF: 返回从arg1到arg0的天数。
  • DAY_OF_MONTH: 从给定日期/时间戳/字符串中提取月份的天数为整数。
  • DAY_OF_WEEK: 从给定日期/时间戳/字符串中提取星期几为整数。范围从1到7，1表示星期天，7表示星期六。
  • DAY_OF_YEAR: 从给定日期/时间戳/字符串中提取年份的天数为整数。
  • FROM_UTC_TIMESTAMP: 给定UTC时间的时间戳列arg0，返回对应于给定时区arg1的另一个时间戳。（注意：arg1必须是字符串字面量）。
  • HOUR: 从给定日期/时间戳/字符串中提取小时数为整数。
  • LAST_DAY: 给定日期列，返回给定日期所属月份的最后一天。
  • MINUTE: 从给定日期/时间戳/字符串中提取分钟数为整数。
  • MONTH: 从给定日期/时间戳/字符串中提取月份为整数。
  • MONTHS_BETWEEN: 返回日期arg0和arg1之间的月份数。
  • QUARTER: 从给定日期/时间戳/字符串中提取季度为整数。
  • SECOND: 从给定日期/时间戳/字符串中提取秒数为整数。
  • TO_UNIX_TIMESTAMP: 按给定模式字符串arg1转换时间字符串arg0，如果出错则返回null（注意：arg1必须是字符串字面量）。
  • TO_UTC_TIMESTAMP: 给定时间戳列arg0，返回对应于给定时区arg1的另一个UTC时间戳。（注意：arg1必须是字符串字面量）。
  • WEEK_OF_YEAR: 从给定日期/时间戳/字符串中提取 ISO周 ↗ 数字为整数。
  • YEAR: 从给定日期/时间戳/字符串中提取年份为整数。

数组函数

有关数组函数的更多信息和示例，请参阅 数组函数的参考文档。

  • ARRAY: 创建所有输入列的数组。
  • ARRAY_CONTAINS: 如果数组列arg0包含值arg1则返回true（注意：arg1必须是字面量）。
  • ARRAY_GET_AT_INDEX: 返回数组列arg0中索引arg1（1索引）处的元素（注意：arg1必须是整数字面量）。显式转换此函数的结果以在后续面板中使用列。
  • ARRAY_LENGTH: 返回给定数组的长度。当输入为null时返回-1。
  • ARRAY_JOIN: 返回由分隔符字符串arg1连接的数组列arg0的字符串（注意：arg1必须是字符串字面量）。
  • ARRAY_SORT: 以升序排序输入数组arg0，如果arg1为true，则降序排序，如果arg1为false（注意：arg1必须是布尔字面量）。
警告

当在窗口函数中使用 ROW_NUMBER、FIRST、LAST、ARRAY_AGG 或 ARRAY_AGG_DISTINCT 时，要注意非确定性。想象一下我们按列A分区并按列B排序。如果对于列A的相同值，列B有多个相同值的行，那么这些窗口函数的结果可能是不确定的——它们可能会在给定相同输入数据和逻辑时产生不同的结果。

窗口函数

窗口函数需要一个OVER子句；有关更多信息和示例，请参阅 窗口函数的参考文档。

  • CUME_DIST: 返回窗口分区内值的累积分布，即低于当前行的行的比例。
  • DENSE_RANK: 返回窗口分区内行的排名，没有任何间隙。
  • EXPLODE: 为给定数组列中的每个元素创建一个新行，删除包含null的行。显式转换此函数的结果以在后续面板中使用列。
  • EXPLODE_OUTER: 为给定数组列中的每个元素创建一个新行。显式转换此函数的结果以在后续面板中使用列。
  • FIRST: 返回组中的第一个值。
  • LAG: 返回列arg0中当前行之前arg1行的值，如果在当前行之前的行数少于arg1，则返回null。例如，arg1为1将在窗口分区中的任何点返回前一行（注意：arg1必须是整数字面量）。
  • LAST: 返回组中的最后一个值。
  • LEAD: 返回列arg0中当前行之后arg1行的值，如果在当前行之后的行数少于arg1，则返回null。例如，arg1为1将在窗口分区中的任何点返回下一行（注意：arg1必须是整数字面量）。
  • NTILE: 返回有序窗口分区中的分位组id（从1到arg0包含）。例如，如果arg0为4，第一季度的行将获得值1，第二季度获得2，第三季度获得3，最后一季度获得4（注意：arg0必须是整数字面量）。
  • PERCENT_RANK: 返回窗口分区内行的相对排名（即百分位数）。
  • RANK: 返回窗口分区内行的排名。
  • ROW_NUMBER: 返回窗口分区内从1开始的顺序编号。

聚合函数

聚合函数可以在聚合表达式和窗口函数中使用。

  • ARRAY_AGG: 返回来自输入列的聚合值数组。
  • ARRAY_AGG_DISTINCT: 返回来自输入列的不同聚合值数组。
  • AVG: 返回组中值的平均值。
  • COUNT: 返回组中的项目数。
  • COUNT_DISTINCT: 返回组中的项目数（注意：只能在表达式面板的聚合选项中使用。不能用于添加新列、筛选或替换列）。
  • CORR: 返回两个列的皮尔逊相关系数。
  • MAX: 返回组中表达式的最大值。
  • MEAN: 返回组中值的平均值。
  • MIN: 返回组中表达式的最小值。
  • STDDEV: 返回组中表达式的样本标准差。
  • SUM: 返回表达式中所有值的和。
  • SUM_DISTINCT: 返回表达式中不同值的和（注意：不能在窗口函数中使用）。
  • VARIANCE: 返回组中值的无偏方差。

杂项函数

  • COALESCE: 返回第一个非null的列，或如果所有输入都为null，则返回null。
  • GREATEST: 返回值列表中最大的值，跳过null值。
  • HASH: 计算给定列的哈希值，并将结果返回为一个int列。
  • ISNULL: 如果且仅当列为null时返回true。
  • LEAST: 返回值列表中最小的值，跳过null值。
  • MD5: 计算二进制列的MD5摘要，并将值返回为一个32字符的十六进制字符串。
  • MONOTONICALLY_INCREASING_ID: 返回一个单调递增的ID。这些值可能会在每次路径计算时更改。
  • SHA1: 计算二进制列的SHA-1摘要，并将值返回为一个40字符的十六进制字符串。
  • GET_JSON_OBJECT: 根据指定的 JSON路径 ↗ 从JSON字符串中提取JSON对象，并返回提取的JSON对象的JSON字符串。一些示例：
    • $.field
    • $['field']