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 (optional)- 日期/時間格式規格，用於解析時間戳記。預設為 ' 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 (optional)- 要轉換的時間單位。預設為 'milli'。

範例：

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 為每個時間單位的數量。當輸入與預期格式不符時，回傳 null：

它由時間單位元件組成 - 一個非負整數，接著是簡短的時間單位名稱。支援的時間單位有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`

解析字串中的時間戳記，可選擇格式規格和時區覆寫。當輸入與預期格式不符時，回傳 null。

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

功能參數：

string (必填)- 擷取時間戳記的輸入。
format (optional)- 日期/時間格式規格，用於解析時間戳記。預設為「自動」。格式可以是任何內嵌日期/時間擷取器的字串、幾種速記法之一，或是依序嘗試的一串格式。以下是幾個範例：
- '%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 epoch (UTC) 以來的特定時間單位數目。 UNIX 的時代從 1970 年 1 月 1 日開始 - 較早的時間戳以負數表示。

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

功能參數：

timestamp (必填)- 要轉換的時間戳記。
timeUnit (optional)- 要轉換成的時間單位。預設為 'milli'。

範例：

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