Skip to main content
Version: 2.14.0

时间字面量

综述

时间字面量是一个字符串,可以用来表达一个确定的时间点,炎凰数据平台会将时间字面量解析成为时间戳(一个整数,表示从epoch开始的微秒数)。

时间字面量可以用来设置查询的 earliestlatest 时间,同时时间字面量也可以用来在SQL语句当中设置到WHERE条件过滤中用于设置和时间戳类型字段的比较。

时间字面量的语法构成

时间字面量以 TIMESTAMP 为前缀以标记后续字符串变量作为时间戳类型处理,例如 TIMESTAMP '2022-08-21T18:22:22'

note

如果没有以 TIMESTAMP 作为字符串前缀,在查询运行中,将根据查询内容判断是否将字符串自动转换成时间戳类型。

如果明确需要使用时间字面量,建议在字符串前面添加 TIMESTAMP,以避免自动类型转换导致查询效率下降。

以下说明将省略前缀 TIMESTAMP 而针对后面字符串部分进行讲解。

字符串的内容主要由三部分构成,每个部分之间使用||作为分隔。

  1. 基础时间:一个时间戳字符串字面量,或者是特殊的字面量nownow代表当前时间。
  2. 时间操作表达式:描述如何在“基础时间”之上执行一系列针对时间的计算。时间的计算包括“时间偏移”和“时间取整”。
  3. 时区的名称:最后一部分时区的名称,用来指定当第二部分中需要进行时间取整的时候,参考哪个时区来进行。

第二部分和第三部分是可选的,如果省略第三部分,默认值是偏好设置中的时区。如果第二部分省略,则直接将基础时间作为时间戳。

note

如果基础时间字面量是now,则后续不需要接分隔符||

基础时间语法

基础时间字面量主要有三类

  1. now代表当前时间。
  2. 时间戳字面量,用来描述一个特定的时间点。时间戳字面量必须符合格式YYYY-mm-ddTHH:MM:SS<timezone>
    • 年月日和时分秒之间必须有T作为分隔。秒可以是一个浮点数的小数。最多小数点后可以有6位,精度达到微秒。
    • <timezone>是一个可选的部分,用来描述时区的信息。 如果时区省略了,则使用偏好设置中的时区 。时区的描述可以是以下三种的任意一种。
      1. +HH:SS或者+HHSS表示时间偏移量,例如+08:00,+0800表示北京时间时区。
      2. IANA时区数据库中的合法时区名称。例如: Asia/Shanghai
  3. 一个整数,表示从epoch开始的微秒数。
    • 如果是正整数,表示从epoch开始往时间轴后偏移的微秒数,例如60000000表示的是1970-01-01T00:01:00UTC
    • 如果是负整数,表示从epoch开始往时间轴前偏移的微秒数,,例如-60000000表示的是1969-12-31T23:59:00UTC

合法的时间戳例子

  • 1608003382988385
  • 2020-11-11T14:34:30.876543
  • 2020-11-11T14:34:30.876
  • 2020-11-11T14:34:30
  • 2020-11-11T14:34:30.876543Asia/Shanghai
  • 2020-11-11T14:34:30.876543+0800
  • 2020-11-11T14:34:30.876543+08:00
note
  • 年月日和时分秒之间必须有字母T连接。
  • 如果有时区,时区和秒之间不能有任何字符。" %}

时间操作表达式语法

时间操作表达式,可以有多个部分组成。表达式中的任何空格字符都会被忽略

每一部分的时间操作表达式有两种,分别是时间偏移和时间取整。

  1. 时间偏移的表达式语法为<+/-><int_number>[time_unit]。可以开头包括加号或者减号,紧跟一个整数数字和一个时间单位
    • 加号代表往时间更大的方向移动,减号代表往时间小的方向移动。加减号可以省略,省略时默认是加号。
    • 整数代表时间偏移的多少个时间单位。如果没有加减号,整数也是可省略的,省略是默认值0,即不偏移。如果有加减号,则整数不能省略。
    • 时间单位用来设定计算时间偏移的时候的单位。例如是偏移N小时,N分钟,或者N天等。
  2. 时间取整的表达式语法为/[time_unit]。时间取整表达式以左斜杠/开头,后面必须跟一个时间单位,表示按照什么时间单位向下取整。需要注意,所有的时间取整,都是按照时间减小的方向进行。

时间偏移和时间取整的表达式是可以级联的。

:::

note

时间操作表达式式中的任何空格字符都会被忽略。因此,-7d/w4+30m- 7 d / w 4 + 3 0 m是等价的。

note

在时间取整的时候,如果按照周取整,是对齐到周一,也就是说在时间取整的时候,/w/w1是相同的。

时间单位的字面量

时间单位的字面量可以有缩写和全称。

时间单位缩写全称
yyear
季度qquarter
Mmonth
wweek
dday
hhour
mminute
ssecond
毫秒msmillisecond
微秒mcsmicrosecond
周日w0 或者 w7sunday
周一w1monday
周二w2tuesday
周三w3wednesday
周四w4thursday
周五w5friday
周六w6saturday
note

时间单位名称字面量是大小写敏感的。

时区名称

第三部分的时区名称,必须是IANA时区数据库中支持的时区名称。例如 Asia/Shanghai, America/Los_Angeles等。

note

在进行时间取整的时候,当按照天,周取整的时候,由于所在时区的不同,可能产生不同的取整结果。因此,时间取整的时区是可以设置的。

例如,假设有时间2020-12-04T20:00:00UTC, 如果在UTC时区按照天取整的话,得到的结果是2020-12-04T00:00:00UTC,但是如果在北京时区对时间按照天取整的话,得到的结果是2020-12-04T16:00:00UTC,因为在北京时区2020-12-04T20:00:00UTC的时间对应的是2020-12-05T04:00:00+0800,按照天取整得到2020-12-05T00:00:00+0800,即2020-12-04T16:00:00UTC

通过设置时间字面量,设置查询的起始时间

在SQL中使用时间字面量过滤数据

在SQL中可以在WHERE过滤条件中,将_time字段和时间字面量进行比较。

例子:

SQL说明
SELECT _time, _message FROM main WHERE _time < TIMESTAMP '2020-12-01T00:00:00'查找在2020-12-01之前的数据。
SELECT _time, _message FROM main WHERE _time > TIMESTAMP 'now-6h'查找过去6小时内的数据。

除了_time字段之外,其他时间戳类型的字段也支持时间时间字面量的比较。

时间字面量的例子

时间点时间字面量字符串
三天之前now-3d
昨天的凌晨0点now-1d/d
上个周日now-7d/w
从2020年12月1日往后推5天,再往前推半小时,即2020年12月4日,23时30分2020-12-01T00:00:00||5d-30m