DataPrime 日期/时间功能

本指南提供了 IBM® Cloud Logs DataPrime 可用函数的术语表，用于处理时间戳、时间间隔和其他时间相关结构体。

时间单位

许多日期/时间函数都接受一个时间单位参数来修改它们的行为。 DataPrime 支持从纳秒到天的时间单位。它们以长符号或短符号的时间单位名称字面字符串表示：

长符号：day, hour, minute, second, milli, micro、nano
简称：d, h, m, s, ms, us、ns

时区

DataPrime 时间戳总是存储在 UTC 时区，但某些日期/时间函数接受一个时区参数来修改其行为。时区参数是指定时区偏移、速记或标识符的字符串：

以小时为单位的时区偏移（例如，"+01 "或"-02）
以小时和分钟为单位的时区偏移（例如，"+0130 "或"-0230）
以小时和分钟为单位的时区偏移量，带分隔符（例如 "+01:30 "或"-02:30）
时区简称（例如，"UTC"、"GMT"、"EST "等）
时区标识符（例如，"亚洲/埃里温"、"欧洲/苏黎世"、"美洲/温尼伯 "等）

`addInterval`

将两个区间相加。也适用于负间隔。相当于 left + right.

addInterval(left: interval, right: interval): interval

`addTime`

为时间戳添加时间间隔。也适用于负间隔。相当于 t + i.

addTime(t: timestamp, i: interval): timestamp

`diffTime`

计算两个时间戳之间的持续时间。如果 to > from 则为正值，如果 to < from 则为负值。等价于 to - from。

diffTime(to: timestamp, from: timestamp): interval

`extractTime`

从时间戳中提取日期或时间单位。如果时间单位小于一分钟，则返回浮点数，否则返回整数。日期单位（如 month 或 week ）从 1 开始（而不是从 0 开始）。

extractTime(timestamp: timestamp, unit: dateunit | timeunit, tz: string?): number

函数参数：

timestamp (必填）- 要从中提取的时间戳。
unit (必填）- 要提取的日期或时间单位。必须是字面字符串，并且必须是以下字符之一：
- 或长或短的时间单位
- 用长符号表示的日期单位：year, month, week, day_of_year、day_of_week
- 用简短符号表示的日期单位：Y, M, W, doy、dow
tz (可选）- 提取前转换时间戳的时区。

例 1：提取东京的小时

limit 1 | choose $m.timestamp.extractTime('h', 'Asia/Tokyo') as h # Result 1: 11pm { "h": 23 }

例 2：提取秒数

limit 1 | choose $m.timestamp.extractTime('second') as s # Result 2: 38.35 seconds { "s": 38.3510265 }

例 3：提取时间戳的月份

limit 1 | choose $m.timestamp.extractTime('month') as m # Result 3: August { "m": 8 }

例 4：提取星期

limit 1 | choose $m.timestamp.extractTime('dow') as d # Result 4: Tuesday { "d": 2 }

`formatInterval`

将 interval 格式化为一个字符串，其中包含一个可选的时间单位 scale。

formatInterval(interval: interval, scale: timeunit?): string

函数参数：

interval (必填）- 要格式化的时间间隔。
scale (可选）- 显示时间间隔的最大时间单位。默认为 nano。

示例：

limit 3 | choose formatInterval(now() - $m.timestamp, 's') as i # Results: { "i": "122s261ms466us27ns" } { "i": "122s359ms197us227ns" } { "i": "122s359ms197us227ns" }

`formatTimestamp`

将时间戳格式化为字符串，格式规范和目标时区可选。

formatTimestamp(timestamp: timestamp, format: string?, tz: string?): string

函数参数：

timestamp (必填）- 要格式化的时间戳。
format (可选）- 用于解析时间戳的日期/时间格式规范。默认为 " iso8601 "。格式可以是任何内嵌日期/时间格式的字符串，也可以是几种速记符号之一。下面是几个样本：
- '%Y-%m- %d ' - 仅打印日期，例如 "2023-04-05
- %H:%M:%S' - 仅打印时间，例如 "16:07:33
- %F %H:%M:%S' - 同时打印日期和时间，例如 "2023-04-05 16:07:33
- ' iso8601 ' - 打印 ISO 8601 格式的时间戳，例如 '2023-04-05T16:07:33.123Z'
- timestamp_milli' - 以毫秒为单位打印时间戳（13 位），例如 "1680710853123

tz (可选）- 在格式化前转换时间戳的目标时区。

例 1：使用默认格式和 +5h 偏移打印时间戳

limit 1 | choose $m.timestamp.formatTimestamp(tz='+05') as ts # Result 1: { "ts": "2023-08-29T19:08:37.405937400+0500" }

例 2：只打印年和月

limit 1 | choose $m.timestamp.formatTimestamp('%Y-%m') as ym # Result 2: { "ym": "2023-08" }

例 3：只打印小时和分钟

limit 1 | choose $m.timestamp.formatTimestamp('%H:%M') as hm # Result 3: { "hm": "14:11" }

例 4：打印以毫秒为单位（13 位）的时间戳

limit 1 | choose $m.timestamp.formatTimestamp('timestamp_milli') as ms # Result 4: { "ms": "1693318678696" }

`fromUnixTime`

将自 UNIX 时间起的特定时间单位转换为时间戳（UTC）。 UNIX 的纪元始于 1970 年 1 月 1 日--较早的时间戳用负数表示。

fromUnixTime(unixTime: number, timeUnit: timeunit?): timestamp

函数参数：

unixTime (必填）- 要转换的时间单位数量。可以是正数或负数，并向下舍入为整数。
timeUnit (可选）- 要转换的时间单位。默认为“毫”。

示例：

limit 1 | choose fromUnixTime(1658958157515, 'ms') as ts # Result: { "ts": 1658958157515000000 }

`multiplyInterval`

将区间乘以一个数字因子。既可处理整数，也可处理小数。相当于 i * factor.

multiplyInterval(i: interval, factor: number): interval

`now`

返回查询执行时的当前时间。即使多次使用，也能在所有行和整个查询中保持稳定。如果运行时支持纳秒分辨率，则为毫秒分辨率。

now(): timestamp

示例：

limit 3 | choose now() as now, now() - $m.timestamp as since # Results: { "now": 1693312549105874700, "since": "14m954ms329us764ns" } { "now": 1693312549105874700, "since": "14m954ms329us764ns" } { "now": 1693312549105874700, "since": "14m960ms519us564ns" }

`parseInterval`

解析格式为 NdNhNmNsNmsNusNns 的字符串中的时间间隔，其中 N 是每个时间单位的数量。当输入不符合预期格式时，返回空值：

它由时间单位部分组成--一个非负整数，后接短时间单位名称。支持的时间单位有d"、"h"、"m"、"s"、"ms"、"us"、"ns"。
必须至少包含一个时间单位。
同一时间单位不能出现多次。
元件必须按时间单位顺序递减--从天到纳秒。
它可以以 - 开始，表示负间隔。

parseInterval(string: string): interval

例 1：解析零间隔

limit 1 | choose '0s'.parseInterval() as i # Result 1: { "i": "0ns" }

例 2：解析正区间

limit 1 | choose '1d48h0m'.parseInterval() as i # Result 2: { "i": "3d" }

例 3：解析负间隔

limit 1 | choose '-5m45s'.parseInterval() as i # Result 3: { "i": "-5m45s" }

`parseTimestamp`

解析字符串中的时间戳，可选择格式规范和时区覆盖。当输入不符合预期格式时，返回空值。

parseTimestamp(string: string, format: string?, tz: string?): timestamp

函数参数：

string (必填）- 提取时间戳的输入。
format (可选）- 用于解析时间戳的日期/时间格式规范。默认为“自动”。格式可以是任何内嵌日期/时间提取器的字符串，也可以是若干速记符号之一，还可以是按顺序尝试的一系列格式。下面是几个样本：
- '%Y-%m- %d ' - 仅解析日期，例如 "2023-04-05
- %F %H:%M:%S' - 解析日期和时间，例如 "2023-04-05 16:07:33
- ' iso8601 ' - 解析 ISO 8601 格式的时间戳，例如 '2023-04-05T16:07:33.123Z'
- timestamp_milli“- 以毫秒（13 位数字）为单位解析时间戳，例如”1680710853123
- %m/ %d /%Y|timestamp_second"--依次解析日期或时间戳（以秒为单位）
tz (可选）- 时区覆盖，用于在解析时转换时间戳。该参数将覆盖输入中存在的任何时区。通过使用适当的格式并省略该参数，可以从字符串中提取时区。

例 1：使用默认格式解析日期

limit 1 | choose '2023-04-05'.parseTimestamp() as ts # Result 1: { "ts": 1680652800000000000 }

例 2：解析 US 格式的日期

limit 1 | choose '04/05/23'.parseTimestamp('%D') as ts # Result 2: { "ts": 1680652800000000000 }

例 3：用单位解析日期和时间

limit 1 | choose '2023-04-05 16h07m'.parseTimestamp('%F %Hh%Mm') as ts # Result 3: { "ts": 1680710820000000000 }

例 4：以秒为单位解析时间戳（10 位数字）

limit 1 | choose '1680710853'.parseTimestamp('timestamp_second') as ts # Result 4: { "ts": 1680710853000000000 }

`roundInterval`

将时间间隔舍入为一个时间单位 scale。较少的时间单位将被清零。

roundInterval(interval: interval, scale: timeunit): interval

函数参数：

interval (必填）--四舍五入的间隔。
scale (必填）- 间隔时间的最大时间单位。

示例：

limit 1 | choose 2h5m45s.roundInterval('m') as i # Result: { "i": "2h5m" }

`roundTime`

将时间戳舍入到给定的时间间隔。例如，四舍五入到 1h。相当于 date / interval.

roundTime(date: timestamp, interval: interval): timestamp

示例：

groupby $m.timestamp.roundTime(1h) as bucket count() as n # Results: { "bucket": "29/08/2023 15:00:00.000 pm", "n": 40653715 } { "bucket": "29/08/2023 14:00:00.000 pm", "n": 1779386 }

`subtractInterval`

从一个区间减去另一个区间。等同于 addInterval(left, -right) 和 left - right.

subtractInterval(left: interval, right: interval): interval

`subtractTime`

从时间戳中减去一个时间间隔。等同于 addTime(t, -i) 和 t - i.

subtractTime(t: timestamp, i: interval): timestamp

`toInterval`

将特定时间单位转换为时间间隔。可处理整数和浮点数以及正数和负数。

toInterval(number: number, timeUnit: timeunit?): interval

函数参数：

number (必填）- 要转换的时间单位数量。
timeUnit (可选）- 要转换的时间单位。默认为 nano。

例 1：转换浮点数

limit 1 | choose 2.5.toInterval('h') as i # Result 1: { "i": "2h30m" } # Example 2: convert an integer number limit 1 | choose -9000.toInterval() as i # Result 2: { "i": "-9us" }

`toUnixTime`

将时间戳转换为自 UNIX 时间（UTC）起的特定时间单位数。 UNIX 的纪元始于 1970 年 1 月 1 日--较早的时间戳用负数表示。

toUnixTime(timestamp: timestamp, timeUnit: timeunit?): number

函数参数：

timestamp (必填）- 要转换的时间戳。
timeUnit (可选）- 要转换成的时间单位。默认为“毫”。

示例：

limit 1 | choose $m.timestamp.toUnixTime('hour') as hr # Result: { "hr": 470363 }