diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md index 4f8ccc418b..851ef86b67 100644 --- a/docs/en/12-taos-sql/10-function.md +++ b/docs/en/12-taos-sql/10-function.md @@ -626,9 +626,9 @@ TIMEDIFF(expr1, expr2 [, time_unit]) #### TIMETRUNCATE ```sql -TIMETRUNCATE(expr, time_unit [, ignore_timezone]) +TIMETRUNCATE(expr, time_unit [, use_current_timezone]) -ignore_timezone: { +use_current_timezone: { 0 | 1 } @@ -647,10 +647,11 @@ ignore_timezone: { 1b (nanoseconds), 1u (microseconds), 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), or 1w (weeks) - The precision of the returned timestamp is same as the precision set for the current data base in use - If the input data is not formatted as a timestamp, the returned value is null. -- If `1d` is used as `time_unit` to truncate the timestamp, `ignore_timezone` option can be set to indicate if the returned result is affected by client timezone or not. - For example, if client timezone is set to UTC+0800, TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) will return '2020-01-01 08:00:00'. - Otherwise, TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) will return '2020-01-01 00:00:00'. - If `ignore_timezone` option is omitted, the default value is set to 1. +- When using 1d/1w as the time unit to truncate timestamp, you can specify whether to truncate based on the current time zone by setting the use_current_timezone parameter. + Value 0 indicates truncation using the UTC time zone, value 1 indicates truncation using the current time zone. + For example, if the time zone configured by the Client is UTC + 0800, TIMETRUNCATE ('2020-01-01 23:00:00', 1d, 0) returns the result of '2020-01-01 08:00:00'. + When using TIMETRUNCATE ('2020-01-01 23:00:00', 1d, 1), the result is 2020-01-01 00:00:00 '. + When use_current_timezone is not specified, use_current_timezone defaults to 1. #### TIMEZONE diff --git a/docs/zh/12-taos-sql/10-function.md b/docs/zh/12-taos-sql/10-function.md index 26313390a6..66322d55f1 100644 --- a/docs/zh/12-taos-sql/10-function.md +++ b/docs/zh/12-taos-sql/10-function.md @@ -1,1499 +1,1500 @@ ---- -sidebar_label: 函数 -title: 函数 -description: TDengine 支持的函数列表 -toc_max_heading_level: 4 ---- - -## 单行函数 - -单行函数为查询结果中的每一行返回一个结果行。 - -### 数学函数 - -#### ABS - -```sql -ABS(expr) -``` - -**功能说明**：获得指定字段的绝对值。 - -**返回结果类型**：与指定字段的原始数据类型一致。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### ACOS - -```sql -ACOS(expr) -``` - -**功能说明**：获得指定字段的反余弦结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### ASIN - -```sql -ASIN(expr) -``` - -**功能说明**：获得指定字段的反正弦结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - - -#### ATAN - -```sql -ATAN(expr) -``` - -**功能说明**：获得指定字段的反正切结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - - -#### CEIL - -```sql -CEIL(expr) -``` - -**功能说明**：获得指定字段的向上取整数的结果。 - -**返回结果类型**：与指定字段的原始数据类型一致。 - -**适用数据类型**：数值类型。 - -**适用于**: 表和超级表。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**: 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### COS - -```sql -COS(expr) -``` - -**功能说明**：获得指定字段的余弦结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### FLOOR - -```sql -FLOOR(expr) -``` - -**功能说明**：获得指定字段的向下取整数的结果。 - 其他使用说明参见 CEIL 函数描述。 - -#### LOG - -```sql -LOG(expr1[, expr2]) -``` - -**功能说明**：获得 expr1 对于底数 expr2 的对数。如果 expr2 参数省略，则返回指定字段的自然对数值。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - - -#### POW - -```sql -POW(expr1, expr2) -``` - -**功能说明**：获得 expr1 的指数为 expr2 的幂。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - - -#### ROUND - -```sql -ROUND(expr) -``` - -**功能说明**：获得指定字段的四舍五入的结果。 - 其他使用说明参见 CEIL 函数描述。 - - -#### SIN - -```sql -SIN(expr) -``` - -**功能说明**：获得指定字段的正弦结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### SQRT - -```sql -SQRT(expr) -``` - -**功能说明**：获得指定字段的平方根。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -#### TAN - -```sql -TAN(expr) -``` - -**功能说明**：获得指定字段的正切结果。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - -### 字符串函数 - -字符串函数的输入参数为字符串类型，返回结果为数值类型或字符串类型。 - -#### CHAR_LENGTH - -```sql -CHAR_LENGTH(expr) -``` - -**功能说明**：以字符计数的字符串长度。 - -**返回结果类型**：BIGINT。 - -**适用数据类型**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -#### CONCAT - -```sql -CONCAT(expr1, expr2 [, expr] ... ) -``` - -**功能说明**：字符串连接函数。 - -**返回结果类型**：如果所有参数均为 VARCHAR 类型，则结果类型为 VARCHAR。如果参数包含NCHAR类型，则结果类型为NCHAR。如果参数包含NULL值，则输出值为NULL。 - -**适用数据类型**：VARCHAR, NCHAR。 该函数最小参数个数为2个，最大参数个数为8个。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### CONCAT_WS - -```sql -CONCAT_WS(separator_expr, expr1, expr2 [, expr] ...) -``` - -**功能说明**：带分隔符的字符串连接函数。 - -**返回结果类型**：如果所有参数均为VARCHAR类型，则结果类型为VARCHAR。如果参数包含NCHAR类型，则结果类型为NCHAR。如果参数包含NULL值，则输出值为NULL。 - -**适用数据类型**：VARCHAR, NCHAR。 该函数最小参数个数为3个，最大参数个数为9个。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### LENGTH - -```sql -LENGTH(expr) -``` - -**功能说明**：以字节计数的长度。 - -**返回结果类型**：BIGINT。 - -**适用数据类型**：VARCHAR, NCHAR, VARBINARY。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### LOWER - -```sql -LOWER(expr) -``` - -**功能说明**：将字符串参数值转换为全小写字母。 - -**返回结果类型**：与输入字段的原始类型相同。 - -**适用数据类型**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### LTRIM - -```sql -LTRIM(expr) -``` - -**功能说明**：返回清除左边空格后的字符串。 - -**返回结果类型**：与输入字段的原始类型相同。 - -**适用数据类型**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### RTRIM - -```sql -RTRIM(expr) -``` - -**功能说明**：返回清除右边空格后的字符串。 - -**返回结果类型**：与输入字段的原始类型相同。 - -**适用数据类型**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### SUBSTR - -```sql -SUBSTR(expr, pos [,len]) -``` - -**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。如果输入参数 len 被忽略，返回的子串包含从 pos 开始的整个字串。 - -**返回结果类型**：与输入字段的原始类型相同。 - -**适用数据类型**：VARCHAR, NCHAR。输入参数 pos 可以为正数，也可以为负数。如果 pos 是正数，表示开始位置从字符串开头正数计算。如果 pos 为负数，表示开始位置从字符串结尾倒数计算。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### UPPER - -```sql -UPPER(expr) -``` - -**功能说明**：将字符串参数值转换为全大写字母。 - -**返回结果类型**：与输入字段的原始类型相同。 - -**适用数据类型**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -### 转换函数 - -转换函数将值从一种数据类型转换为另一种数据类型。 - -#### CAST - -```sql -CAST(expr AS type_name) -``` - -**功能说明**：数据类型转换函数，返回 expr 转换为 type_name 指定的类型后的结果。只适用于 select 子句中。 - -**返回结果类型**：CAST 中指定的类型（type_name)。 - -**适用数据类型**：输入参数 expr 的类型可以是除JSON和VARBINARY外的所有类型。如果 type_name 为 VARBINARY，则 expr 只能是 VARCHAR 类型。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**： - -- 对于不能支持的类型转换会直接报错。 -- 对于类型支持但某些值无法正确转换的情况，对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： - 1）字符串类型转换数值类型时可能出现的无效字符情况，例如"a"可能转为0，但不会报错。 - 2）转换到数值类型时，数值大于type_name可表示的范围时，则会溢出，但不会报错。 - 3）转换到字符串类型时，如果转换后长度超过type_name中指定的长度，则会截断，但不会报错。 - -#### TO_ISO8601 - -```sql -TO_ISO8601(expr [, timezone]) -``` - -**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加时区信息。timezone 参数允许用户为输出结果指定附带任意时区信息。如果 timezone 参数省略，输出结果则附带当前客户端的系统时区信息。 - -**返回结果数据类型**：VARCHAR 类型。 - -**适用数据类型**：INTEGER, TIMESTAMP。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - -**使用说明**： - -- timezone 参数允许输入的时区格式为: [z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如，TO_ISO8601(1, "+00:00")。 -- 如果输入是表示 UNIX 时间戳的整形，返回格式精度由时间戳的位数决定; -- 如果输入是 TIMESTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 - - -#### TO_JSON - -```sql -TO_JSON(str_literal) -``` - -**功能说明**: 将字符串常量转换为 JSON 类型。 - -**返回结果数据类型**: JSON。 - -**适用数据类型**: JSON 字符串，形如 '{ "literal" : literal }'。'{}'表示空值。键必须为字符串字面量，值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal中不支持转义符。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**: 表和超级表。 - - -#### TO_UNIXTIMESTAMP - -```sql -TO_UNIXTIMESTAMP(expr [, return_timestamp]) - -return_timestamp: { - 0 - | 1 -} -``` - -**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 - -**返回结果数据类型**：BIGINT, TIMESTAMP。 - -**应用字段**：VARCHAR, NCHAR。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 NULL。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 -- return_timestamp 指定函数返回值是否为时间戳类型，设置为1时返回 TIMESTAMP 类型，设置为0时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 - -#### TO_CHAR - -```sql -TO_CHAR(ts, format_str_literal) -``` - -**功能说明**: 将timestamp类型按照指定格式转换为字符串 - -**返回结果数据类型**: VARCHAR - -**应用字段**: TIMESTAMP - -**嵌套子查询支持**: 适用于内层查询和外层查询 - -**适用于**: 表和超级表 - -**支持的格式** - -| **格式** | **说明**| **例子** | -| --- | --- | --- | -|AM,am,PM,pm| 无点分隔的上午下午 | 07:00:00am| -|A.M.,a.m.,P.M.,p.m.| 有点分隔的上午下午| 07:00:00a.m.| -|YYYY,yyyy|年, 4个及以上数字| 2023-10-10| -|YYY,yyy| 年, 最后3位数字| 023-10-10| -|YY,yy| 年, 最后2位数字| 23-10-10| -|Y,y|年, 最后一位数字| 3-10-10| -|MONTH|月, 全大写| 2023-JANUARY-01| -|Month|月, 首字母大写| 2023-January-01| -|month|月, 全小写| 2023-january-01| -|MON| 月, 缩写, 全大写(三个字符)| JAN, SEP| -|Mon| 月, 缩写, 首字母大写| Jan, Sep| -|mon|月, 缩写, 全小写| jan, sep| -|MM,mm|月, 数字 01-12|2023-01-01| -|DD,dd|月日, 01-31|| -|DAY|周日, 全大写|MONDAY| -|Day|周日, 首字符大写|Monday| -|day|周日, 全小写|monday| -|DY|周日, 缩写, 全大写|MON| -|Dy|周日, 缩写, 首字符大写|Mon| -|dy|周日, 缩写, 全小写|mon| -|DDD|年日, 001-366|| -|D,d|周日, 数字, 1-7, Sunday(1) to Saturday(7)|| -|HH24,hh24|小时, 00-23|2023-01-30 23:59:59| -|hh12,HH12, hh, HH| 小时, 01-12|2023-01-30 12:59:59PM| -|MI,mi|分钟, 00-59|| -|SS,ss|秒, 00-59|| -|MS,ms|毫秒, 000-999|| -|US,us|微秒, 000000-999999|| -|NS,ns|纳秒, 000000000-999999999|| -|TZH,tzh|时区小时|2023-01-30 11:59:59PM +08| - -**使用说明**: -- `Month`, `Day`等的输出格式是左对齐的, 右侧添加空格, 如`2023-OCTOBER -01`, `2023-SEPTEMBER-01`, 9月是月份中英文字母数最长的, 因此9月没有空格. 星期类似. -- 使用`ms`, `us`, `ns`时, 以上三种格式的输出只在精度上不同, 比如ts为 `1697182085123`, `ms` 的输出为 `123`, `us` 的输出为 `123000`, `ns` 的输出为 `123000000`. -- 时间格式中无法匹配规则的内容会直接输出. 如果想要在格式串中指定某些能够匹配规则的部分不做转换, 可以使用双引号, 如`to_char(ts, 'yyyy-mm-dd "is formated by yyyy-mm-dd"')`. 如果想要输出双引号, 那么在双引号之前加一个反斜杠, 如 `to_char(ts, '\"yyyy-mm-dd\"')` 将会输出 `"2023-10-10"`. -- 那些输出是数字的格式, 如`YYYY`, `DD`, 大写与小写意义相同, 即`yyyy` 和 `YYYY` 可以互换. -- 推荐在时间格式中带时区信息，如果不带则默认输出的时区为服务端或客户端所配置的时区. -- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. - -#### TO_TIMESTAMP - -```sql -TO_TIMESTAMP(ts_str_literal, format_str_literal) -``` - -**功能说明**: 将字符串按照指定格式转化为时间戳. - -**返回结果数据类型**: TIMESTAMP - -**应用字段**: VARCHAR - -**嵌套子查询支持**: 适用于内层查询和外层查询 - -**适用于**: 表和超级表 - -**支持的格式**: 与`to_char`相同 - -**使用说明**: -- 若`ms`, `us`, `ns`同时指定, 那么结果时间戳包含上述三个字段的和. 如 `to_timestamp('2023-10-10 10:10:10.123.000456.000000789', 'yyyy-mm-dd hh:mi:ss.ms.us.ns')` 输出为 `2023-10-10 10:10:10.123456789`对应的时间戳. -- `MONTH`, `MON`, `DAY`, `DY` 以及其他输出为数字的格式的大小写意义相同, 如 `to_timestamp('2023-JANUARY-01', 'YYYY-month-dd')`, `month`可以被替换为`MONTH` 或者`Month`. -- 如果同一字段被指定了多次, 那么前面的指定将会被覆盖. 如 `to_timestamp('2023-22-10-10', 'yyyy-yy-MM-dd')`, 输出年份是`2022`. -- 为避免转换时使用了非预期的时区，推荐在时间中携带时区信息，例如'2023-10-10 10:10:10+08'，如果未指定时区则默认时区为服务端或客户端指定的时区。 -- 如果没有指定完整的时间，那么默认时间值为指定或默认时区的 `1970-01-01 00:00:00`, 未指定部分使用该默认值中的对应部分. 暂不支持只指定年日而不指定月日的格式, 如'yyyy-mm-DDD', 支持'yyyy-mm-DD'. -- 如果格式串中有`AM`, `PM`等, 那么小时必须是12小时制, 范围必须是01-12. -- `to_timestamp`转换具有一定的容错机制, 在格式串和时间戳串不完全对应时, 有时也可转换, 如: `to_timestamp('200101/2', 'yyyyMM1/dd')`, 格式串中多出来的1会被丢弃. 格式串与时间戳串中多余的空格字符(空格, tab等)也会被 自动忽略. 如`to_timestamp(' 23 年 - 1 月 - 01 日 ', 'yy 年-MM月-dd日')` 可以被成功转换. 虽然`MM`等字段需要两个数字对应(只有一位时前面补0), 在`to_timestamp`时, 一个数字也可以成功转换. -- 输出时间戳的精度与查询表的精度相同, 若查询未指定表, 则输出精度为毫秒. 如`select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns')`的输出将会把微妙和纳秒进行截断. 如果指定一张纳秒表, 那么就不会发生截断, 如`select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns') from db_ns.table_ns limit 1`. - - -### 时间和日期函数 - -时间和日期函数对时间戳类型进行操作。 - -所有返回当前时间的函数，如NOW、TODAY和TIMEZONE，在一条SQL语句中不论出现多少次都只会被计算一次。 - -#### NOW - -```sql -NOW() -``` - -**功能说明**：返回客户端当前系统时间。 - -**返回结果数据类型**：TIMESTAMP。 - -**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 - -**适用于**：表和超级表。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： - b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - - -#### TIMEDIFF - -```sql -TIMEDIFF(expr1, expr2 [, time_unit]) -``` - -**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 - -**返回结果数据类型**：BIGINT。 - -**应用字段**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。 - -**适用于**：表和超级表。 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： -- 支持的时间单位 time_unit 如下： - 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 -- 如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 -- 输入包含不符合时间日期格式的字符串则返回 NULL。 - - -#### TIMETRUNCATE - -```sql -TIMETRUNCATE(expr, time_unit [, ignore_timezone]) - -ignore_timezone: { - 0 - | 1 -} -``` - -**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 - -**返回结果数据类型**：TIMESTAMP。 - -**应用字段**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。 - -**适用于**：表和超级表。 - -**使用说明**： -- 支持的时间单位 time_unit 如下： - 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 -- 输入包含不符合时间日期格式的字符串则返回 NULL。 -- 当使用 1d 作为时间单位对时间戳进行截断时， 可通过设置 ignore_timezone 参数指定返回结果的显示是否忽略客户端时区的影响。 - 例如客户端所配置时区为 UTC+0800, 则 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) 返回结果为 '2020-01-01 08:00:00'。 - 而使用 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) 设置忽略时区时，返回结果为 '2020-01-01 00:00:00' - ignore_timezone 如果忽略的话，则默认值为 1 。 - - - -#### TIMEZONE - -```sql -TIMEZONE() -``` - -**功能说明**：返回客户端当前时区信息。 - -**返回结果数据类型**：VARCHAR。 - -**应用字段**：无 - -**适用于**：表和超级表。 - - -#### TODAY - -```sql -TODAY() -``` - -**功能说明**：返回客户端当日零时的系统时间。 - -**返回结果数据类型**：TIMESTAMP。 - -**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： - b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - - -## 聚合函数 - -聚合函数为查询结果集的每一个分组返回单个结果行。可以由 GROUP BY 或窗口切分子句指定分组，如果没有，则整个查询结果集视为一个分组。 - -TDengine 支持针对数据的聚合查询。提供如下聚合函数。 - -### APERCENTILE - -```sql -APERCENTILE(expr, p [, algo_type]) - -algo_type: { - "default" - | "t-digest" -} -``` - -**功能说明**：统计表/超级表中指定列的值的近似百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。 - -**返回数据类型**： DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**说明**： -- p值范围是[0,100]，当为0时等同于MIN，为100时等同于MAX。 -- algo_type 取值为 "default" 或 "t-digest"。 输入为 "default" 时函数使用基于直方图算法进行计算。输入为 "t-digest" 时使用t-digest算法计算分位数的近似结果。如果不指定 algo_type 则使用 "default" 算法。 -- "t-digest"算法的近似结果对于输入数据顺序敏感，对超级表查询时不同的输入排序结果可能会有微小的误差。 - -### AVG - -```sql -AVG(expr) -``` - -**功能说明**：统计指定字段的平均值。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### COUNT - -```sql -COUNT({* | expr}) -``` - -**功能说明**：统计指定字段的记录行数。 - -**返回数据类型**：BIGINT。 - -**适用数据类型**：全部类型字段。 - -**适用于**：表和超级表。 - -**使用说明**: - -- 可以使用星号(\*)来替代具体的字段，使用星号(\*)返回全部记录数量。 -- 如果统计字段是具体的列，则返回该列中非 NULL 值的记录数量。 - - -### ELAPSED - -```sql -ELAPSED(ts_primary_key [, time_unit]) -``` - -**功能说明**：elapsed函数表达了统计周期内连续的时间长度，和twa函数配合使用可以计算统计曲线下的面积。在通过INTERVAL子句指定窗口的情况下，统计在给定时间范围内的每个窗口内有数据覆盖的时间范围；如果没有INTERVAL子句，则返回整个给定时间范围内的有数据覆盖的时间范围。注意，ELAPSED返回的并不是时间范围的绝对值，而是绝对值除以time_unit所得到的单位个数。 - -**返回结果类型**：DOUBLE。 - -**适用数据类型**：TIMESTAMP。 - -**适用于**: 表，超级表，嵌套查询的外层查询 - -**说明**： -- ts_primary_key参数只能是表的第一列，即 TIMESTAMP 类型的主键列。 -- 按time_unit参数指定的时间单位返回，最小是数据库的时间分辨率。time_unit 参数未指定时，以数据库的时间分辨率为时间单位。支持的时间单位 time_unit 如下： - 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 -- 可以和interval组合使用，返回每个时间窗口的时间戳差值。需要特别注意的是，除第一个时间窗口和最后一个时间窗口外，中间窗口的时间戳差值均为窗口长度。 -- order by asc/desc不影响差值的计算结果。 -- 对于超级表，需要和group by tbname子句组合使用，不可以直接使用。 -- 对于普通表，不支持和group by子句组合使用。 -- 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。 -- 不支持与leastsquares、diff、derivative、top、bottom、last_row、interp等函数混合使用。 - - -### LEASTSQUARES - -```sql -LEASTSQUARES(expr, start_val, step_val) -``` - -**功能说明**：统计表中某列的值的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。 - -**返回数据类型**：字符串表达式（斜率, 截距）。 - -**适用数据类型**：expr 必须是数值类型。 - -**适用于**：表。 - - -### SPREAD - -```sql -SPREAD(expr) -``` - -**功能说明**：统计表中某列的最大值和最小值之差。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：INTEGER, TIMESTAMP。 - -**适用于**：表和超级表。 - - -### STDDEV - -```sql -STDDEV(expr) -``` - -**功能说明**：统计表中某列的均方差。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### SUM - -```sql -SUM(expr) -``` - -**功能说明**：统计表/超级表中某列的和。 - -**返回数据类型**：DOUBLE, BIGINT。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### HYPERLOGLOG - -```sql -HYPERLOGLOG(expr) -``` - -**功能说明**： - - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 - - 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。 - -**返回结果类型**：INTEGER。 - -**适用数据类型**：任何类型。 - -**适用于**：表和超级表。 - - -### HISTOGRAM - -```sql -HISTOGRAM(expr，bin_type, bin_description, normalized) -``` - -**功能说明**：统计数据按照用户指定区间的分布。 - -**返回结果类型**：如归一化参数 normalized 设置为 1，返回结果为 DOUBLE 类型，否则为 BIGINT 类型。 - -**适用数据类型**：数值型字段。 - -**适用于**: 表和超级表。 - -**详细说明**： -- bin_type 用户指定的分桶类型, 有效输入类型为"user_input“, ”linear_bin", "log_bin"。 -- bin_description 描述如何生成分桶区间，针对三种桶类型，分别为以下描述格式(均为 JSON 格式字符串)： - - "user_input": "[1, 3, 5, 7]" - 用户指定 bin 的具体数值。 - - - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" - "start" 表示数据起始点，"width" 表示每次 bin 偏移量, "count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点和终点， - 生成区间为[-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]。 - - - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" - "start" 表示数据起始点，"factor" 表示按指数递增的因子，"count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点和终点， - 生成区间为[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]。 -- normalized 是否将返回结果归一化到 0~1 之间 。有效输入为 0 和 1。 - - -### PERCENTILE - -```sql -PERCENTILE(expr, p [, p1] ... ) -``` - -**功能说明**：统计表中某列的值百分比分位数。 - -**返回数据类型**： 该函数最小参数个数为 2 个，最大参数个数为 11 个。可以最多同时返回 10 个百分比分位数。当参数个数为 2 时， 返回一个分位数， 类型为DOUBLE，当参数个数大于 2 时，返回类型为VARCHAR, 格式为包含多个返回值的JSON数组。 - -**应用字段**：数值类型。 - -**适用于**：表。 - -**使用说明**： - -- *P*值取值范围 0≤*P*≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX; -- 同时计算针对同一列的多个分位数时，建议使用一个PERCENTILE函数和多个参数的方式，能很大程度上降低查询的响应时间。 - 比如，使用查询SELECT percentile(col, 90, 95, 99) FROM table, 性能会优于SELECT percentile(col, 90), percentile(col, 95), percentile(col, 99) from table。 - - -## 选择函数 - -选择函数根据语义在查询结果集中选择一行或多行结果返回。用户可以同时指定输出 ts 列或其他列（包括 tbname 和标签列），这样就可以方便地知道被选出的值是源于哪个数据行的。 - -### BOTTOM - -```sql -BOTTOM(expr, k) -``` - -**功能说明**：统计表/超级表中某列的值最小 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**使用说明**: - -- *k*值取值范围 1≤*k*≤100； -- 系统同时返回该记录关联的时间戳列； -- 限制：BOTTOM 函数不支持 FILL 子句。 - -### FIRST - -```sql -FIRST(expr) -``` - -**功能说明**：统计表/超级表中某列的值最先写入的非 NULL 值。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：所有字段。 - -**适用于**：表和超级表。 - -**使用说明**: - -- 如果要返回各个列的首个（时间戳最小）非 NULL 值，可以使用 FIRST(\*)； -- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL； -- 如果结果集中所有列全部为 NULL 值，则不返回结果。 - -### INTERP - -```sql -INTERP(expr [, ignore_null_values]) - -ignore_null_values: { - 0 - | 1 -} -``` - -**功能说明**：返回指定时间截面指定列的记录值或插值。ignore_null_values 参数的值可以是 0 或 1，为 1 时表示忽略 NULL 值, 缺省值为0。 - -**返回数据类型**：同字段类型。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**使用说明** - -- INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。 -- INTERP 的输入数据为指定列的数据，可以通过条件语句（where 子句）来对原始列数据进行过滤，如果没有指定过滤条件则输入为全部数据。 -- INTERP 需要同时与 RANGE，EVERY 和 FILL 关键字一起使用。 -- INTERP 的输出时间范围根据 RANGE(timestamp1, timestamp2)字段来指定，需满足 timestamp1 <= timestamp2。其中 timestamp1 为输出时间范围的起始值，即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录，timestamp2 为输出时间范围的结束值，即输出的最后一条记录的 timestamp 不能大于 timestamp2。 -- INTERP 根据 EVERY(time_unit) 字段来确定输出时间范围内的结果条数，即从 timestamp1 开始每隔固定长度的时间（time_unit 值）进行插值，time_unit 可取值时间单位：1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)，1w(周)。例如 EVERY(500a) 将对于指定数据每500毫秒间隔进行一次插值. -- INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值。关于 FILL 子句如何使用请参考 [FILL 子句](../distinguished/#fill-子句) -- INTERP 可以在 RANGE 字段中只指定唯一的时间戳对单个时间点进行插值，在这种情况下，EVERY 字段可以省略。例如：SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00') FILL(linear). -- INTERP 作用于超级表时, 会将该超级表下的所有子表数据按照主键列排序后进行插值计算，也可以搭配 PARTITION BY tbname 使用，将结果强制规约到单个时间线。 -- INTERP 可以与伪列 _irowts 一起使用，返回插值点所对应的时间戳(3.0.2.0版本以后支持)。 -- INTERP 可以与伪列 _isfilled 一起使用，显示返回结果是否为原始记录或插值算法产生的数据(3.0.3.0版本以后支持)。 - -### LAST - -```sql -LAST(expr) -``` - -**功能说明**：统计表/超级表中某列的值最后写入的非 NULL 值。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：所有字段。 - -**适用于**：表和超级表。 - -**使用说明**: - -- 如果要返回各个列的最后（时间戳最大）一个非 NULL 值，可以使用 LAST(\*)； -- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL；如果结果集中所有列全部为 NULL 值，则不返回结果。 -- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 - - -### LAST_ROW - -```sql -LAST_ROW(expr) -``` - -**功能说明**：返回表/超级表的最后一条记录。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：所有字段。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 -- 不能与 INTERVAL 一起使用。 - -### MAX - -```sql -MAX(expr) -``` - -**功能说明**：统计表/超级表中某列的值最大值。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### MIN - -```sql -MIN(expr) -``` - -**功能说明**：统计表/超级表中某列的值最小值。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### MODE - -```sql -MODE(expr) -``` - -**功能说明**：返回出现频率最高的值，若存在多个频率相同的最高值，则随机输出其中某个值。 - -**返回数据类型**：与输入数据类型一致。 - -**适用数据类型**：全部类型字段。 - -**适用于**：表和超级表。 - - -### SAMPLE - -```sql -SAMPLE(expr, k) -``` - -**功能说明**： 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 - -**返回结果类型**： 同原始数据类型。 - -**适用数据类型**： 全部类型字段。 - -**嵌套子查询支持**： 适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - - -### TAIL - -```sql -TAIL(expr, k [, offset_rows]) -``` - -**功能说明**：返回跳过最后 offset_val 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `order by ts desc LIMIT k OFFSET offset_val`。 - -**参数范围**：k: [1,100] offset_val: [0,100]。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：适合于除时间主键列外的任何类型。 - -**适用于**：表、超级表。 - - -### TOP - -```sql -TOP(expr, k) -``` - -**功能说明**： 统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**使用说明**: - -- *k*值取值范围 1≤*k*≤100； -- 系统同时返回该记录关联的时间戳列； -- 限制：TOP 函数不支持 FILL 子句。 - -### UNIQUE - -```sql -UNIQUE(expr) -``` - -**功能说明**：返回该列数据首次出现的值。该函数功能与 distinct 相似。 - -**返回数据类型**：同应用的字段。 - -**适用数据类型**：全部类型字段。 - -**适用于**: 表和超级表。 - - -## 时序数据特有函数 - -时序数据特有函数是 TDengine 为了满足时序数据的查询场景而量身定做出来的。在通用数据库中，实现类似功能通常需要复杂的查询语法，且效率很低。TDengine 以函数的方式内置了这些功能，最大程度的减轻了用户的使用成本。 - -### CSUM - -```sql -CSUM(expr) -``` - -**功能说明**：累加和（Cumulative sum），输出行与输入行数相同。 - -**返回结果类型**： 输入列如果是整数类型返回值为长整型 （int64_t），浮点数返回值为双精度浮点数（Double）。无符号整数类型返回值为无符号长整型（uint64_t）。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**： 适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。 -- 只能与聚合（Aggregation）函数一起使用。 该函数可以应用在普通表和超级表上。 - - -### DERIVATIVE - -```sql -DERIVATIVE(expr, time_interval, ignore_negative) - -ignore_negative: { - 0 - | 1 -} -``` - -**功能说明**：统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**使用说明**: - -- 可以与选择相关联的列一起使用。 例如: select \_rowts, DERIVATIVE() from。 - -### DIFF - -```sql -DIFF(expr [, ignore_negative]) - -ignore_negative: { - 0 - | 1 -} -``` - -**功能说明**：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。 - -**返回数据类型**：同应用字段。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - -**使用说明**: - -- 输出结果行数是范围内总行数减一，第一行没有结果输出。 -- 可以与选择相关联的列一起使用。 例如: select \_rowts, DIFF() from。 - - -### IRATE - -```sql -IRATE(expr) -``` - -**功能说明**：计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率；如果这两个值呈递减关系，那么只取最后一个数用于计算，而不是使用二者差值。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -### MAVG - -```sql -MAVG(expr, k) -``` - -**功能说明**： 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 - -**返回结果类型**： DOUBLE。 - -**适用数据类型**： 数值类型。 - -**嵌套子查询支持**： 适用于内层查询和外层查询。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用； - - -### STATECOUNT - -```sql -STATECOUNT(expr, oper, val) -``` - -**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 - -**参数范围**： - -- oper : "LT" (小于)、"GT"（大于）、"LE"（小于等于）、"GE"（大于等于）、"NE"（不等于）、"EQ"（等于），不区分大小写。 -- val : 数值型 - -**返回结果类型**：INTEGER。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：不支持应用在子查询上。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 - - -### STATEDURATION - -```sql -STATEDURATION(expr, oper, val, unit) -``` - -**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 - -**参数范围**： - -- oper : `'LT'` (小于)、`'GT'`（大于）、`'LE'`（小于等于）、`'GE'`（大于等于）、`'NE'`（不等于）、`'EQ'`（等于），不区分大小写，但需要用`''`包括。 -- val : 数值型 -- unit : 时间长度的单位，可取值时间单位： 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。如果省略，默认为当前数据库精度。 - -**返回结果类型**：INTEGER。 - -**适用数据类型**：数值类型。 - -**嵌套子查询支持**：不支持应用在子查询上。 - -**适用于**：表和超级表。 - -**使用说明**： - -- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 - - -### TWA - -```sql -TWA(expr) -``` - -**功能说明**：时间加权平均函数。统计表中某列在一段时间内的时间加权平均。 - -**返回数据类型**：DOUBLE。 - -**适用数据类型**：数值类型。 - -**适用于**：表和超级表。 - - -## 系统信息函数 - -### DATABASE - -```sql -SELECT DATABASE(); -``` - -**说明**：返回当前登录的数据库。如果登录的时候没有指定默认数据库，且没有使用USE命令切换数据库，则返回NULL。 - - -### CLIENT_VERSION - -```sql -SELECT CLIENT_VERSION(); -``` - -**说明**：返回客户端版本。 - -### SERVER_VERSION - -```sql -SELECT SERVER_VERSION(); -``` - -**说明**：返回服务端版本。 - -### SERVER_STATUS - -```sql -SELECT SERVER_STATUS(); -``` - -**说明**：检测服务端是否所有 dnode 都在线，如果是则返回成功，否则返回无法建立连接的错误。 - -### CURRENT_USER - -```sql -SELECT CURRENT_USER(); -``` - -**说明**：获取当前用户。 - - -## Geometry 函数 - -### Geometry 输入函数： - -#### ST_GeomFromText - -```sql -ST_GeomFromText(VARCHAR WKT expr) -``` - -**功能说明**：根据 Well-Known Text (WKT) 表示从指定的几何值创建几何数据。 - -**返回值类型**：GEOMETRY - -**适用数据类型**：VARCHAR - -**适用表类型**：标准表和超表 - -**使用说明**：输入可以是 WKT 字符串之一，例如点（POINT）、线串（LINESTRING）、多边形（POLYGON）、多点集（MULTIPOINT）、多线串（MULTILINESTRING）、多多边形（MULTIPOLYGON）、几何集合（GEOMETRYCOLLECTION）。输出是以二进制字符串形式定义的 GEOMETRY 数据类型。 - -### Geometry 输出函数： - -#### ST_AsText - -```sql -ST_AsText(GEOMETRY geom) -``` - -**功能说明**：从几何数据中返回指定的 Well-Known Text (WKT) 表示。 - -**返回值类型**：VARCHAR - -**适用数据类型**：GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：输出可以是 WKT 字符串之一，例如点（POINT）、线串（LINESTRING）、多边形（POLYGON）、多点集（MULTIPOINT）、多线串（MULTILINESTRING）、多多边形（MULTIPOLYGON）、几何集合（GEOMETRYCOLLECTION）。 - -### Geometry 关系函数： - -#### ST_Intersects - -```sql -ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) -``` - -##功能说明**：比较两个几何对象，并在它们相交时返回 true。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：如果两个几何对象有任何一个共享点，则它们相交。 - -#### ST_Equals - -```sql -ST_Equals(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果给定的几何对象是"空间相等"的，则返回 TRUE。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**："空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true，并且点的顺序可能不同，但表示相同的几何结构。 - -#### ST_Touches - -```sql -ST_Touches(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 A 和 B 相交，但它们的内部不相交，则返回 TRUE。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：A 和 B 至少有一个公共点，并且这些公共点位于至少一个边界中。对于点/点输入，关系始终为 FALSE，因为点没有边界。 - -#### ST_Covers - -```sql -ST_Covers(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 B 中的每个点都位于几何形状 A 内部（与内部或边界相交），则返回 TRUE。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：A 包含 B 意味着 B 中的没有点位于 A 的外部（在外部）。 - -#### ST_Contains - -```sql -ST_Contains(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 A 包含 B，描述：如果几何形状 A 包含几何形状 B，则返回 TRUE。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：A 包含 B 当且仅当 B 的所有点位于 A 的内部（即位于内部或边界上）（或等效地，B 的没有点位于 A 的外部），并且 A 和 B 的内部至少有一个公共点。 - -#### ST_ContainsProperly - -```sql -ST_ContainsProperly(GEOMETRY geomA, GEOMETRY geomB) -``` - -**功能说明**：如果 B 的每个点都位于 A 内部，则返回 TRUE。 - -**返回值类型**：BOOL - -**适用数据类型**：GEOMETRY，GEOMETRY - -**适用表类型**：标准表和超表 - -**使用说明**：B 的没有点位于 A 的边界或外部。 +--- +sidebar_label: 函数 +title: 函数 +description: TDengine 支持的函数列表 +toc_max_heading_level: 4 +--- + +## 单行函数 + +单行函数为查询结果中的每一行返回一个结果行。 + +### 数学函数 + +#### ABS + +```sql +ABS(expr) +``` + +**功能说明**：获得指定字段的绝对值。 + +**返回结果类型**：与指定字段的原始数据类型一致。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### ACOS + +```sql +ACOS(expr) +``` + +**功能说明**：获得指定字段的反余弦结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### ASIN + +```sql +ASIN(expr) +``` + +**功能说明**：获得指定字段的反正弦结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + +#### ATAN + +```sql +ATAN(expr) +``` + +**功能说明**：获得指定字段的反正切结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + +#### CEIL + +```sql +CEIL(expr) +``` + +**功能说明**：获得指定字段的向上取整数的结果。 + +**返回结果类型**：与指定字段的原始数据类型一致。 + +**适用数据类型**：数值类型。 + +**适用于**: 表和超级表。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**: 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### COS + +```sql +COS(expr) +``` + +**功能说明**：获得指定字段的余弦结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### FLOOR + +```sql +FLOOR(expr) +``` + +**功能说明**：获得指定字段的向下取整数的结果。 + 其他使用说明参见 CEIL 函数描述。 + +#### LOG + +```sql +LOG(expr1[, expr2]) +``` + +**功能说明**：获得 expr1 对于底数 expr2 的对数。如果 expr2 参数省略，则返回指定字段的自然对数值。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + +#### POW + +```sql +POW(expr1, expr2) +``` + +**功能说明**：获得 expr1 的指数为 expr2 的幂。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + +#### ROUND + +```sql +ROUND(expr) +``` + +**功能说明**：获得指定字段的四舍五入的结果。 + 其他使用说明参见 CEIL 函数描述。 + + +#### SIN + +```sql +SIN(expr) +``` + +**功能说明**：获得指定字段的正弦结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### SQRT + +```sql +SQRT(expr) +``` + +**功能说明**：获得指定字段的平方根。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +#### TAN + +```sql +TAN(expr) +``` + +**功能说明**：获得指定字段的正切结果。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**：只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +### 字符串函数 + +字符串函数的输入参数为字符串类型，返回结果为数值类型或字符串类型。 + +#### CHAR_LENGTH + +```sql +CHAR_LENGTH(expr) +``` + +**功能说明**：以字符计数的字符串长度。 + +**返回结果类型**：BIGINT。 + +**适用数据类型**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +#### CONCAT + +```sql +CONCAT(expr1, expr2 [, expr] ... ) +``` + +**功能说明**：字符串连接函数。 + +**返回结果类型**：如果所有参数均为 VARCHAR 类型，则结果类型为 VARCHAR。如果参数包含NCHAR类型，则结果类型为NCHAR。如果参数包含NULL值，则输出值为NULL。 + +**适用数据类型**：VARCHAR, NCHAR。 该函数最小参数个数为2个，最大参数个数为8个。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### CONCAT_WS + +```sql +CONCAT_WS(separator_expr, expr1, expr2 [, expr] ...) +``` + +**功能说明**：带分隔符的字符串连接函数。 + +**返回结果类型**：如果所有参数均为VARCHAR类型，则结果类型为VARCHAR。如果参数包含NCHAR类型，则结果类型为NCHAR。如果参数包含NULL值，则输出值为NULL。 + +**适用数据类型**：VARCHAR, NCHAR。 该函数最小参数个数为3个，最大参数个数为9个。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### LENGTH + +```sql +LENGTH(expr) +``` + +**功能说明**：以字节计数的长度。 + +**返回结果类型**：BIGINT。 + +**适用数据类型**：VARCHAR, NCHAR, VARBINARY。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### LOWER + +```sql +LOWER(expr) +``` + +**功能说明**：将字符串参数值转换为全小写字母。 + +**返回结果类型**：与输入字段的原始类型相同。 + +**适用数据类型**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### LTRIM + +```sql +LTRIM(expr) +``` + +**功能说明**：返回清除左边空格后的字符串。 + +**返回结果类型**：与输入字段的原始类型相同。 + +**适用数据类型**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### RTRIM + +```sql +RTRIM(expr) +``` + +**功能说明**：返回清除右边空格后的字符串。 + +**返回结果类型**：与输入字段的原始类型相同。 + +**适用数据类型**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### SUBSTR + +```sql +SUBSTR(expr, pos [,len]) +``` + +**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。如果输入参数 len 被忽略，返回的子串包含从 pos 开始的整个字串。 + +**返回结果类型**：与输入字段的原始类型相同。 + +**适用数据类型**：VARCHAR, NCHAR。输入参数 pos 可以为正数，也可以为负数。如果 pos 是正数，表示开始位置从字符串开头正数计算。如果 pos 为负数，表示开始位置从字符串结尾倒数计算。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### UPPER + +```sql +UPPER(expr) +``` + +**功能说明**：将字符串参数值转换为全大写字母。 + +**返回结果类型**：与输入字段的原始类型相同。 + +**适用数据类型**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +### 转换函数 + +转换函数将值从一种数据类型转换为另一种数据类型。 + +#### CAST + +```sql +CAST(expr AS type_name) +``` + +**功能说明**：数据类型转换函数，返回 expr 转换为 type_name 指定的类型后的结果。只适用于 select 子句中。 + +**返回结果类型**：CAST 中指定的类型（type_name)。 + +**适用数据类型**：输入参数 expr 的类型可以是除JSON和VARBINARY外的所有类型。如果 type_name 为 VARBINARY，则 expr 只能是 VARCHAR 类型。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**： + +- 对于不能支持的类型转换会直接报错。 +- 对于类型支持但某些值无法正确转换的情况，对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： + 1）字符串类型转换数值类型时可能出现的无效字符情况，例如"a"可能转为0，但不会报错。 + 2）转换到数值类型时，数值大于type_name可表示的范围时，则会溢出，但不会报错。 + 3）转换到字符串类型时，如果转换后长度超过type_name中指定的长度，则会截断，但不会报错。 + +#### TO_ISO8601 + +```sql +TO_ISO8601(expr [, timezone]) +``` + +**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加时区信息。timezone 参数允许用户为输出结果指定附带任意时区信息。如果 timezone 参数省略，输出结果则附带当前客户端的系统时区信息。 + +**返回结果数据类型**：VARCHAR 类型。 + +**适用数据类型**：INTEGER, TIMESTAMP。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + +**使用说明**： + +- timezone 参数允许输入的时区格式为: [z/Z, +/-hhmm, +/-hh, +/-hh:mm]。例如，TO_ISO8601(1, "+00:00")。 +- 如果输入是表示 UNIX 时间戳的整形，返回格式精度由时间戳的位数决定; +- 如果输入是 TIMESTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 + + +#### TO_JSON + +```sql +TO_JSON(str_literal) +``` + +**功能说明**: 将字符串常量转换为 JSON 类型。 + +**返回结果数据类型**: JSON。 + +**适用数据类型**: JSON 字符串，形如 '{ "literal" : literal }'。'{}'表示空值。键必须为字符串字面量，值可以为数值字面量、字符串字面量、布尔字面量或空值字面量。str_literal中不支持转义符。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**: 表和超级表。 + + +#### TO_UNIXTIMESTAMP + +```sql +TO_UNIXTIMESTAMP(expr [, return_timestamp]) + +return_timestamp: { + 0 + | 1 +} +``` + +**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 + +**返回结果数据类型**：BIGINT, TIMESTAMP。 + +**应用字段**：VARCHAR, NCHAR。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 NULL。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 +- return_timestamp 指定函数返回值是否为时间戳类型，设置为1时返回 TIMESTAMP 类型，设置为0时返回 BIGINT 类型。如不指定缺省返回 BIGINT 类型。 + +#### TO_CHAR + +```sql +TO_CHAR(ts, format_str_literal) +``` + +**功能说明**: 将timestamp类型按照指定格式转换为字符串 + +**返回结果数据类型**: VARCHAR + +**应用字段**: TIMESTAMP + +**嵌套子查询支持**: 适用于内层查询和外层查询 + +**适用于**: 表和超级表 + +**支持的格式** + +| **格式** | **说明**| **例子** | +| --- | --- | --- | +|AM,am,PM,pm| 无点分隔的上午下午 | 07:00:00am| +|A.M.,a.m.,P.M.,p.m.| 有点分隔的上午下午| 07:00:00a.m.| +|YYYY,yyyy|年, 4个及以上数字| 2023-10-10| +|YYY,yyy| 年, 最后3位数字| 023-10-10| +|YY,yy| 年, 最后2位数字| 23-10-10| +|Y,y|年, 最后一位数字| 3-10-10| +|MONTH|月, 全大写| 2023-JANUARY-01| +|Month|月, 首字母大写| 2023-January-01| +|month|月, 全小写| 2023-january-01| +|MON| 月, 缩写, 全大写(三个字符)| JAN, SEP| +|Mon| 月, 缩写, 首字母大写| Jan, Sep| +|mon|月, 缩写, 全小写| jan, sep| +|MM,mm|月, 数字 01-12|2023-01-01| +|DD,dd|月日, 01-31|| +|DAY|周日, 全大写|MONDAY| +|Day|周日, 首字符大写|Monday| +|day|周日, 全小写|monday| +|DY|周日, 缩写, 全大写|MON| +|Dy|周日, 缩写, 首字符大写|Mon| +|dy|周日, 缩写, 全小写|mon| +|DDD|年日, 001-366|| +|D,d|周日, 数字, 1-7, Sunday(1) to Saturday(7)|| +|HH24,hh24|小时, 00-23|2023-01-30 23:59:59| +|hh12,HH12, hh, HH| 小时, 01-12|2023-01-30 12:59:59PM| +|MI,mi|分钟, 00-59|| +|SS,ss|秒, 00-59|| +|MS,ms|毫秒, 000-999|| +|US,us|微秒, 000000-999999|| +|NS,ns|纳秒, 000000000-999999999|| +|TZH,tzh|时区小时|2023-01-30 11:59:59PM +08| + +**使用说明**: +- `Month`, `Day`等的输出格式是左对齐的, 右侧添加空格, 如`2023-OCTOBER -01`, `2023-SEPTEMBER-01`, 9月是月份中英文字母数最长的, 因此9月没有空格. 星期类似. +- 使用`ms`, `us`, `ns`时, 以上三种格式的输出只在精度上不同, 比如ts为 `1697182085123`, `ms` 的输出为 `123`, `us` 的输出为 `123000`, `ns` 的输出为 `123000000`. +- 时间格式中无法匹配规则的内容会直接输出. 如果想要在格式串中指定某些能够匹配规则的部分不做转换, 可以使用双引号, 如`to_char(ts, 'yyyy-mm-dd "is formated by yyyy-mm-dd"')`. 如果想要输出双引号, 那么在双引号之前加一个反斜杠, 如 `to_char(ts, '\"yyyy-mm-dd\"')` 将会输出 `"2023-10-10"`. +- 那些输出是数字的格式, 如`YYYY`, `DD`, 大写与小写意义相同, 即`yyyy` 和 `YYYY` 可以互换. +- 推荐在时间格式中带时区信息，如果不带则默认输出的时区为服务端或客户端所配置的时区. +- 输入时间戳的精度由所查询表的精度确定, 若未指定表, 则精度为毫秒. + +#### TO_TIMESTAMP + +```sql +TO_TIMESTAMP(ts_str_literal, format_str_literal) +``` + +**功能说明**: 将字符串按照指定格式转化为时间戳. + +**返回结果数据类型**: TIMESTAMP + +**应用字段**: VARCHAR + +**嵌套子查询支持**: 适用于内层查询和外层查询 + +**适用于**: 表和超级表 + +**支持的格式**: 与`to_char`相同 + +**使用说明**: +- 若`ms`, `us`, `ns`同时指定, 那么结果时间戳包含上述三个字段的和. 如 `to_timestamp('2023-10-10 10:10:10.123.000456.000000789', 'yyyy-mm-dd hh:mi:ss.ms.us.ns')` 输出为 `2023-10-10 10:10:10.123456789`对应的时间戳. +- `MONTH`, `MON`, `DAY`, `DY` 以及其他输出为数字的格式的大小写意义相同, 如 `to_timestamp('2023-JANUARY-01', 'YYYY-month-dd')`, `month`可以被替换为`MONTH` 或者`Month`. +- 如果同一字段被指定了多次, 那么前面的指定将会被覆盖. 如 `to_timestamp('2023-22-10-10', 'yyyy-yy-MM-dd')`, 输出年份是`2022`. +- 为避免转换时使用了非预期的时区，推荐在时间中携带时区信息，例如'2023-10-10 10:10:10+08'，如果未指定时区则默认时区为服务端或客户端指定的时区。 +- 如果没有指定完整的时间，那么默认时间值为指定或默认时区的 `1970-01-01 00:00:00`, 未指定部分使用该默认值中的对应部分. 暂不支持只指定年日而不指定月日的格式, 如'yyyy-mm-DDD', 支持'yyyy-mm-DD'. +- 如果格式串中有`AM`, `PM`等, 那么小时必须是12小时制, 范围必须是01-12. +- `to_timestamp`转换具有一定的容错机制, 在格式串和时间戳串不完全对应时, 有时也可转换, 如: `to_timestamp('200101/2', 'yyyyMM1/dd')`, 格式串中多出来的1会被丢弃. 格式串与时间戳串中多余的空格字符(空格, tab等)也会被 自动忽略. 如`to_timestamp(' 23 年 - 1 月 - 01 日 ', 'yy 年-MM月-dd日')` 可以被成功转换. 虽然`MM`等字段需要两个数字对应(只有一位时前面补0), 在`to_timestamp`时, 一个数字也可以成功转换. +- 输出时间戳的精度与查询表的精度相同, 若查询未指定表, 则输出精度为毫秒. 如`select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns')`的输出将会把微妙和纳秒进行截断. 如果指定一张纳秒表, 那么就不会发生截断, 如`select to_timestamp('2023-08-1 10:10:10.123456789', 'yyyy-mm-dd hh:mi:ss.ns') from db_ns.table_ns limit 1`. + + +### 时间和日期函数 + +时间和日期函数对时间戳类型进行操作。 + +所有返回当前时间的函数，如NOW、TODAY和TIMEZONE，在一条SQL语句中不论出现多少次都只会被计算一次。 + +#### NOW + +```sql +NOW() +``` + +**功能说明**：返回客户端当前系统时间。 + +**返回结果数据类型**：TIMESTAMP。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表和超级表。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： + b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + + +#### TIMEDIFF + +```sql +TIMEDIFF(expr1, expr2 [, time_unit]) +``` + +**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 + +**返回结果数据类型**：BIGINT。 + +**应用字段**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。 + +**适用于**：表和超级表。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： +- 支持的时间单位 time_unit 如下： + 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 +- 如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 +- 输入包含不符合时间日期格式的字符串则返回 NULL。 + + +#### TIMETRUNCATE + +```sql +TIMETRUNCATE(expr, time_unit [, use_current_timezone]) + +use_current_timezone: { + 0 + | 1 +} +``` + +**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 + +**返回结果数据类型**：TIMESTAMP。 + +**应用字段**：表示 UNIX 时间戳的 BIGINT, TIMESTAMP 类型，或符合日期时间格式的 VARCHAR, NCHAR 类型。 + +**适用于**：表和超级表。 + +**使用说明**： +- 支持的时间单位 time_unit 如下： + 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 +- 输入包含不符合时间日期格式的字符串则返回 NULL。 +- 当使用 1d/1w 作为时间单位对时间戳进行截断时， 可通过设置 use_current_timezone 参数指定是否根据当前时区进行截断处理。 + 值 0 表示使用 UTC 时区进行截断，值 1 表示使用当前时区进行截断。 + 例如客户端所配置时区为 UTC+0800, 则 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) 返回结果为东八区时间 '2020-01-01 08:00:00'。 + 而使用 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) 时，返回结果为东八区时间 '2020-01-01 00:00:00'。 + 当不指定 use_current_timezone 时，use_current_timezone 默认值为 1 。 + + + +#### TIMEZONE + +```sql +TIMEZONE() +``` + +**功能说明**：返回客户端当前时区信息。 + +**返回结果数据类型**：VARCHAR。 + +**应用字段**：无 + +**适用于**：表和超级表。 + + +#### TODAY + +```sql +TODAY() +``` + +**功能说明**：返回客户端当日零时的系统时间。 + +**返回结果数据类型**：TIMESTAMP。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： + b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + + +## 聚合函数 + +聚合函数为查询结果集的每一个分组返回单个结果行。可以由 GROUP BY 或窗口切分子句指定分组，如果没有，则整个查询结果集视为一个分组。 + +TDengine 支持针对数据的聚合查询。提供如下聚合函数。 + +### APERCENTILE + +```sql +APERCENTILE(expr, p [, algo_type]) + +algo_type: { + "default" + | "t-digest" +} +``` + +**功能说明**：统计表/超级表中指定列的值的近似百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。 + +**返回数据类型**： DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**说明**： +- p值范围是[0,100]，当为0时等同于MIN，为100时等同于MAX。 +- algo_type 取值为 "default" 或 "t-digest"。 输入为 "default" 时函数使用基于直方图算法进行计算。输入为 "t-digest" 时使用t-digest算法计算分位数的近似结果。如果不指定 algo_type 则使用 "default" 算法。 +- "t-digest"算法的近似结果对于输入数据顺序敏感，对超级表查询时不同的输入排序结果可能会有微小的误差。 + +### AVG + +```sql +AVG(expr) +``` + +**功能说明**：统计指定字段的平均值。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### COUNT + +```sql +COUNT({* | expr}) +``` + +**功能说明**：统计指定字段的记录行数。 + +**返回数据类型**：BIGINT。 + +**适用数据类型**：全部类型字段。 + +**适用于**：表和超级表。 + +**使用说明**: + +- 可以使用星号(\*)来替代具体的字段，使用星号(\*)返回全部记录数量。 +- 如果统计字段是具体的列，则返回该列中非 NULL 值的记录数量。 + + +### ELAPSED + +```sql +ELAPSED(ts_primary_key [, time_unit]) +``` + +**功能说明**：elapsed函数表达了统计周期内连续的时间长度，和twa函数配合使用可以计算统计曲线下的面积。在通过INTERVAL子句指定窗口的情况下，统计在给定时间范围内的每个窗口内有数据覆盖的时间范围；如果没有INTERVAL子句，则返回整个给定时间范围内的有数据覆盖的时间范围。注意，ELAPSED返回的并不是时间范围的绝对值，而是绝对值除以time_unit所得到的单位个数。 + +**返回结果类型**：DOUBLE。 + +**适用数据类型**：TIMESTAMP。 + +**适用于**: 表，超级表，嵌套查询的外层查询 + +**说明**： +- ts_primary_key参数只能是表的第一列，即 TIMESTAMP 类型的主键列。 +- 按time_unit参数指定的时间单位返回，最小是数据库的时间分辨率。time_unit 参数未指定时，以数据库的时间分辨率为时间单位。支持的时间单位 time_unit 如下： + 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。 +- 可以和interval组合使用，返回每个时间窗口的时间戳差值。需要特别注意的是，除第一个时间窗口和最后一个时间窗口外，中间窗口的时间戳差值均为窗口长度。 +- order by asc/desc不影响差值的计算结果。 +- 对于超级表，需要和group by tbname子句组合使用，不可以直接使用。 +- 对于普通表，不支持和group by子句组合使用。 +- 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。 +- 不支持与leastsquares、diff、derivative、top、bottom、last_row、interp等函数混合使用。 + + +### LEASTSQUARES + +```sql +LEASTSQUARES(expr, start_val, step_val) +``` + +**功能说明**：统计表中某列的值的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。 + +**返回数据类型**：字符串表达式（斜率, 截距）。 + +**适用数据类型**：expr 必须是数值类型。 + +**适用于**：表。 + + +### SPREAD + +```sql +SPREAD(expr) +``` + +**功能说明**：统计表中某列的最大值和最小值之差。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：INTEGER, TIMESTAMP。 + +**适用于**：表和超级表。 + + +### STDDEV + +```sql +STDDEV(expr) +``` + +**功能说明**：统计表中某列的均方差。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### SUM + +```sql +SUM(expr) +``` + +**功能说明**：统计表/超级表中某列的和。 + +**返回数据类型**：DOUBLE, BIGINT。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### HYPERLOGLOG + +```sql +HYPERLOGLOG(expr) +``` + +**功能说明**： + - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 + - 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。 + +**返回结果类型**：INTEGER。 + +**适用数据类型**：任何类型。 + +**适用于**：表和超级表。 + + +### HISTOGRAM + +```sql +HISTOGRAM(expr，bin_type, bin_description, normalized) +``` + +**功能说明**：统计数据按照用户指定区间的分布。 + +**返回结果类型**：如归一化参数 normalized 设置为 1，返回结果为 DOUBLE 类型，否则为 BIGINT 类型。 + +**适用数据类型**：数值型字段。 + +**适用于**: 表和超级表。 + +**详细说明**： +- bin_type 用户指定的分桶类型, 有效输入类型为"user_input“, ”linear_bin", "log_bin"。 +- bin_description 描述如何生成分桶区间，针对三种桶类型，分别为以下描述格式(均为 JSON 格式字符串)： + - "user_input": "[1, 3, 5, 7]" + 用户指定 bin 的具体数值。 + + - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" + "start" 表示数据起始点，"width" 表示每次 bin 偏移量, "count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点和终点， + 生成区间为[-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]。 + + - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" + "start" 表示数据起始点，"factor" 表示按指数递增的因子，"count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点和终点， + 生成区间为[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]。 +- normalized 是否将返回结果归一化到 0~1 之间 。有效输入为 0 和 1。 + + +### PERCENTILE + +```sql +PERCENTILE(expr, p [, p1] ... ) +``` + +**功能说明**：统计表中某列的值百分比分位数。 + +**返回数据类型**： 该函数最小参数个数为 2 个，最大参数个数为 11 个。可以最多同时返回 10 个百分比分位数。当参数个数为 2 时， 返回一个分位数， 类型为DOUBLE，当参数个数大于 2 时，返回类型为VARCHAR, 格式为包含多个返回值的JSON数组。 + +**应用字段**：数值类型。 + +**适用于**：表。 + +**使用说明**： + +- *P*值取值范围 0≤*P*≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX; +- 同时计算针对同一列的多个分位数时，建议使用一个PERCENTILE函数和多个参数的方式，能很大程度上降低查询的响应时间。 + 比如，使用查询SELECT percentile(col, 90, 95, 99) FROM table, 性能会优于SELECT percentile(col, 90), percentile(col, 95), percentile(col, 99) from table。 + + +## 选择函数 + +选择函数根据语义在查询结果集中选择一行或多行结果返回。用户可以同时指定输出 ts 列或其他列（包括 tbname 和标签列），这样就可以方便地知道被选出的值是源于哪个数据行的。 + +### BOTTOM + +```sql +BOTTOM(expr, k) +``` + +**功能说明**：统计表/超级表中某列的值最小 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**使用说明**: + +- *k*值取值范围 1≤*k*≤100； +- 系统同时返回该记录关联的时间戳列； +- 限制：BOTTOM 函数不支持 FILL 子句。 + +### FIRST + +```sql +FIRST(expr) +``` + +**功能说明**：统计表/超级表中某列的值最先写入的非 NULL 值。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：所有字段。 + +**适用于**：表和超级表。 + +**使用说明**: + +- 如果要返回各个列的首个（时间戳最小）非 NULL 值，可以使用 FIRST(\*)； +- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL； +- 如果结果集中所有列全部为 NULL 值，则不返回结果。 + +### INTERP + +```sql +INTERP(expr [, ignore_null_values]) + +ignore_null_values: { + 0 + | 1 +} +``` + +**功能说明**：返回指定时间截面指定列的记录值或插值。ignore_null_values 参数的值可以是 0 或 1，为 1 时表示忽略 NULL 值, 缺省值为0。 + +**返回数据类型**：同字段类型。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**使用说明** + +- INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。 +- INTERP 的输入数据为指定列的数据，可以通过条件语句（where 子句）来对原始列数据进行过滤，如果没有指定过滤条件则输入为全部数据。 +- INTERP 需要同时与 RANGE，EVERY 和 FILL 关键字一起使用。 +- INTERP 的输出时间范围根据 RANGE(timestamp1, timestamp2)字段来指定，需满足 timestamp1 <= timestamp2。其中 timestamp1 为输出时间范围的起始值，即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录，timestamp2 为输出时间范围的结束值，即输出的最后一条记录的 timestamp 不能大于 timestamp2。 +- INTERP 根据 EVERY(time_unit) 字段来确定输出时间范围内的结果条数，即从 timestamp1 开始每隔固定长度的时间（time_unit 值）进行插值，time_unit 可取值时间单位：1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)，1w(周)。例如 EVERY(500a) 将对于指定数据每500毫秒间隔进行一次插值. +- INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值。关于 FILL 子句如何使用请参考 [FILL 子句](../distinguished/#fill-子句) +- INTERP 可以在 RANGE 字段中只指定唯一的时间戳对单个时间点进行插值，在这种情况下，EVERY 字段可以省略。例如：SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00') FILL(linear). +- INTERP 作用于超级表时, 会将该超级表下的所有子表数据按照主键列排序后进行插值计算，也可以搭配 PARTITION BY tbname 使用，将结果强制规约到单个时间线。 +- INTERP 可以与伪列 _irowts 一起使用，返回插值点所对应的时间戳(3.0.2.0版本以后支持)。 +- INTERP 可以与伪列 _isfilled 一起使用，显示返回结果是否为原始记录或插值算法产生的数据(3.0.3.0版本以后支持)。 + +### LAST + +```sql +LAST(expr) +``` + +**功能说明**：统计表/超级表中某列的值最后写入的非 NULL 值。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：所有字段。 + +**适用于**：表和超级表。 + +**使用说明**: + +- 如果要返回各个列的最后（时间戳最大）一个非 NULL 值，可以使用 LAST(\*)； +- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL；如果结果集中所有列全部为 NULL 值，则不返回结果。 +- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 + + +### LAST_ROW + +```sql +LAST_ROW(expr) +``` + +**功能说明**：返回表/超级表的最后一条记录。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：所有字段。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 +- 不能与 INTERVAL 一起使用。 + +### MAX + +```sql +MAX(expr) +``` + +**功能说明**：统计表/超级表中某列的值最大值。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### MIN + +```sql +MIN(expr) +``` + +**功能说明**：统计表/超级表中某列的值最小值。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### MODE + +```sql +MODE(expr) +``` + +**功能说明**：返回出现频率最高的值，若存在多个频率相同的最高值，则随机输出其中某个值。 + +**返回数据类型**：与输入数据类型一致。 + +**适用数据类型**：全部类型字段。 + +**适用于**：表和超级表。 + + +### SAMPLE + +```sql +SAMPLE(expr, k) +``` + +**功能说明**： 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + +**返回结果类型**： 同原始数据类型。 + +**适用数据类型**： 全部类型字段。 + +**嵌套子查询支持**： 适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + + +### TAIL + +```sql +TAIL(expr, k [, offset_rows]) +``` + +**功能说明**：返回跳过最后 offset_val 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `order by ts desc LIMIT k OFFSET offset_val`。 + +**参数范围**：k: [1,100] offset_val: [0,100]。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：适合于除时间主键列外的任何类型。 + +**适用于**：表、超级表。 + + +### TOP + +```sql +TOP(expr, k) +``` + +**功能说明**： 统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**使用说明**: + +- *k*值取值范围 1≤*k*≤100； +- 系统同时返回该记录关联的时间戳列； +- 限制：TOP 函数不支持 FILL 子句。 + +### UNIQUE + +```sql +UNIQUE(expr) +``` + +**功能说明**：返回该列数据首次出现的值。该函数功能与 distinct 相似。 + +**返回数据类型**：同应用的字段。 + +**适用数据类型**：全部类型字段。 + +**适用于**: 表和超级表。 + + +## 时序数据特有函数 + +时序数据特有函数是 TDengine 为了满足时序数据的查询场景而量身定做出来的。在通用数据库中，实现类似功能通常需要复杂的查询语法，且效率很低。TDengine 以函数的方式内置了这些功能，最大程度的减轻了用户的使用成本。 + +### CSUM + +```sql +CSUM(expr) +``` + +**功能说明**：累加和（Cumulative sum），输出行与输入行数相同。 + +**返回结果类型**： 输入列如果是整数类型返回值为长整型 （int64_t），浮点数返回值为双精度浮点数（Double）。无符号整数类型返回值为无符号长整型（uint64_t）。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**： 适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。 +- 只能与聚合（Aggregation）函数一起使用。 该函数可以应用在普通表和超级表上。 + + +### DERIVATIVE + +```sql +DERIVATIVE(expr, time_interval, ignore_negative) + +ignore_negative: { + 0 + | 1 +} +``` + +**功能说明**：统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**使用说明**: + +- 可以与选择相关联的列一起使用。 例如: select \_rowts, DERIVATIVE() from。 + +### DIFF + +```sql +DIFF(expr [, ignore_negative]) + +ignore_negative: { + 0 + | 1 +} +``` + +**功能说明**：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。 + +**返回数据类型**：同应用字段。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + +**使用说明**: + +- 输出结果行数是范围内总行数减一，第一行没有结果输出。 +- 可以与选择相关联的列一起使用。 例如: select \_rowts, DIFF() from。 + + +### IRATE + +```sql +IRATE(expr) +``` + +**功能说明**：计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率；如果这两个值呈递减关系，那么只取最后一个数用于计算，而不是使用二者差值。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +### MAVG + +```sql +MAVG(expr, k) +``` + +**功能说明**： 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + +**返回结果类型**： DOUBLE。 + +**适用数据类型**： 数值类型。 + +**嵌套子查询支持**： 适用于内层查询和外层查询。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用； + + +### STATECOUNT + +```sql +STATECOUNT(expr, oper, val) +``` + +**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : "LT" (小于)、"GT"（大于）、"LE"（小于等于）、"GE"（大于等于）、"NE"（不等于）、"EQ"（等于），不区分大小写。 +- val : 数值型 + +**返回结果类型**：INTEGER。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + + +### STATEDURATION + +```sql +STATEDURATION(expr, oper, val, unit) +``` + +**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : `'LT'` (小于)、`'GT'`（大于）、`'LE'`（小于等于）、`'GE'`（大于等于）、`'NE'`（不等于）、`'EQ'`（等于），不区分大小写，但需要用`''`包括。 +- val : 数值型 +- unit : 时间长度的单位，可取值时间单位： 1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。如果省略，默认为当前数据库精度。 + +**返回结果类型**：INTEGER。 + +**适用数据类型**：数值类型。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**适用于**：表和超级表。 + +**使用说明**： + +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + + +### TWA + +```sql +TWA(expr) +``` + +**功能说明**：时间加权平均函数。统计表中某列在一段时间内的时间加权平均。 + +**返回数据类型**：DOUBLE。 + +**适用数据类型**：数值类型。 + +**适用于**：表和超级表。 + + +## 系统信息函数 + +### DATABASE + +```sql +SELECT DATABASE(); +``` + +**说明**：返回当前登录的数据库。如果登录的时候没有指定默认数据库，且没有使用USE命令切换数据库，则返回NULL。 + + +### CLIENT_VERSION + +```sql +SELECT CLIENT_VERSION(); +``` + +**说明**：返回客户端版本。 + +### SERVER_VERSION + +```sql +SELECT SERVER_VERSION(); +``` + +**说明**：返回服务端版本。 + +### SERVER_STATUS + +```sql +SELECT SERVER_STATUS(); +``` + +**说明**：检测服务端是否所有 dnode 都在线，如果是则返回成功，否则返回无法建立连接的错误。 + +### CURRENT_USER + +```sql +SELECT CURRENT_USER(); +``` + +**说明**：获取当前用户。 + + +## Geometry 函数 + +### Geometry 输入函数： + +#### ST_GeomFromText + +```sql +ST_GeomFromText(VARCHAR WKT expr) +``` + +**功能说明**：根据 Well-Known Text (WKT) 表示从指定的几何值创建几何数据。 + +**返回值类型**：GEOMETRY + +**适用数据类型**：VARCHAR + +**适用表类型**：标准表和超表 + +**使用说明**：输入可以是 WKT 字符串之一，例如点（POINT）、线串（LINESTRING）、多边形（POLYGON）、多点集（MULTIPOINT）、多线串（MULTILINESTRING）、多多边形（MULTIPOLYGON）、几何集合（GEOMETRYCOLLECTION）。输出是以二进制字符串形式定义的 GEOMETRY 数据类型。 + +### Geometry 输出函数： + +#### ST_AsText + +```sql +ST_AsText(GEOMETRY geom) +``` + +**功能说明**：从几何数据中返回指定的 Well-Known Text (WKT) 表示。 + +**返回值类型**：VARCHAR + +**适用数据类型**：GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：输出可以是 WKT 字符串之一，例如点（POINT）、线串（LINESTRING）、多边形（POLYGON）、多点集（MULTIPOINT）、多线串（MULTILINESTRING）、多多边形（MULTIPOLYGON）、几何集合（GEOMETRYCOLLECTION）。 + +### Geometry 关系函数： + +#### ST_Intersects + +```sql +ST_Intersects(GEOMETRY geomA, GEOMETRY geomB) +``` + +##功能说明**：比较两个几何对象，并在它们相交时返回 true。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：如果两个几何对象有任何一个共享点，则它们相交。 + +#### ST_Equals + +```sql +ST_Equals(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果给定的几何对象是"空间相等"的，则返回 TRUE。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**："空间相等"意味着 ST_Contains(A,B) = true 和 ST_Contains(B,A) = true，并且点的顺序可能不同，但表示相同的几何结构。 + +#### ST_Touches + +```sql +ST_Touches(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 A 和 B 相交，但它们的内部不相交，则返回 TRUE。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：A 和 B 至少有一个公共点，并且这些公共点位于至少一个边界中。对于点/点输入，关系始终为 FALSE，因为点没有边界。 + +#### ST_Covers + +```sql +ST_Covers(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 B 中的每个点都位于几何形状 A 内部（与内部或边界相交），则返回 TRUE。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：A 包含 B 意味着 B 中的没有点位于 A 的外部（在外部）。 + +#### ST_Contains + +```sql +ST_Contains(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 A 包含 B，描述：如果几何形状 A 包含几何形状 B，则返回 TRUE。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：A 包含 B 当且仅当 B 的所有点位于 A 的内部（即位于内部或边界上）（或等效地，B 的没有点位于 A 的外部），并且 A 和 B 的内部至少有一个公共点。 + +#### ST_ContainsProperly + +```sql +ST_ContainsProperly(GEOMETRY geomA, GEOMETRY geomB) +``` + +**功能说明**：如果 B 的每个点都位于 A 内部，则返回 TRUE。 + +**返回值类型**：BOOL + +**适用数据类型**：GEOMETRY，GEOMETRY + +**适用表类型**：标准表和超表 + +**使用说明**：B 的没有点位于 A 的边界或外部。