Skip to main content
Version: 2.13.0

时间字面量

综述​

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

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

时间字面量的语法构成​

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

note

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

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

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

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

  1. 基础时间：一个时间戳字符串字面量，或者是特殊的字面量now。now代表当前时间。
  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