DataPrime datum/Uhrzeit-Funktionen

Dieser Leitfaden enthält ein Glossar der verfügbaren IBM® Cloud Logs DataPrime Funktionen zur Verarbeitung von Zeitstempeln, Intervallen und anderen zeitbezogenen Konstrukten.

Zeiteinheiten

Viele Datums-/Zeitfunktionen akzeptieren ein Argument für die Zeiteinheit, um ihr Verhalten zu ändern. DataPrime unterstützt Zeiteinheiten von Nanosekunden bis zu Tagen. Sie werden als literale Zeichenketten mit dem Namen der Zeiteinheit in langer oder kurzer Notation dargestellt:

lange Notation: day, hour, minute, second, milli, micro, nano
kurzschreibweise: d, h, m, s, ms, us, ns

Zeitzonen

DataPrime zeitstempel werden immer in der UTC-Zeitzone gespeichert, aber einige Datum/Uhrzeit-Funktionen akzeptieren ein Zeitzonen-Argument, um ihr Verhalten zu ändern. Zeitzonenargumente sind Zeichenketten, die einen Zeitzonen-Offset, ein Kürzel oder einen Bezeichner angeben:

zeitzonen-Offset in Stunden (zum Beispiel '+01' oder '-02')
zeitzonen-Offset in Stunden und Minuten (z. B. '+0130' oder '-0230')
zeitzonen-Offset in Stunden und Minuten mit Trennzeichen (zum Beispiel '+01:30' oder '-02:30')
abkürzungen für Zeitzonen (z. B. 'UTC', 'GMT', 'EST' usw.)
kennung der Zeitzone (z. B. "Asien/Eriwan", "Europa/Zürich", "Amerika/Winnipeg" usw.)

`addInterval`

Addiert zwei Intervalle zusammen. Funktioniert auch mit negativen Intervallen. Äquivalent zu left + right.

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

`addTime`

Fügt ein Intervall zu einem Zeitstempel hinzu. Funktioniert auch mit negativen Intervallen. Äquivalent zu t + i.

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

`diffTime`

Berechnet die Dauer zwischen zwei Zeitstempeln. Positiv, wenn to > from, negativ, wenn to < from. Äquivalent zu to - from.

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

`extractTime`

Extrahiert entweder ein Datum oder eine Zeiteinheit aus einem Zeitstempel. Gibt eine Fließkommazahl für Zeiteinheiten unter einer Minute zurück, ansonsten eine ganze Zahl. Datumseinheiten wie month oder week beginnen bei 1 (nicht bei 0).

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

Funktionsparameter:

timestamp (erforderlich)- der Zeitstempel, aus dem extrahiert werden soll.
unit (erforderlich)- die zu extrahierende Datums- oder Zeiteinheit. Muss ein String-Literal und eines von sein:
- jede Zeiteinheit in langer oder kurzer Schreibweise
- eine Datumseinheit in langer Schreibweise: year, month, week, day_of_year, day_of_week
- eine Datumseinheit in Kurzschreibweise: Y, M, W, doy, dow
tz (optional)- eine Zeitzone, in die der Zeitstempel vor der Extraktion umgerechnet wird.

Beispiel 1: Extraktion der Stunde in Tokio

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

Beispiel 2: Extraktion der Anzahl der Sekunden

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

Beispiel 3: Extraktion des Monats des Zeitstempels

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

Beispiel 4: Extraktion des Wochentags

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

`formatInterval`

Formatiert interval zu einer Zeichenkette mit einer optionalen Zeiteinheit scale.

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

Funktionsparameter:

interval (erforderlich)- das zu formatierende Intervall.
scale (optional)- die maximale Zeiteinheit des anzuzeigenden Intervalls. Die Standardeinstellung ist nano.

Beispiel:

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

`formatTimestamp`

Formatiert einen Zeitstempel in eine Zeichenkette mit einer optionalen Formatspezifikation und einer Zielzeitzone.

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

Funktionsparameter:

timestamp (erforderlich)- der zu formatierende Zeitstempel.
format (optional)- eine Datums-/Zeitformatspezifikation für das Parsen von Zeitstempeln. Der Standardwert ist ' iso8601 '. Das Format kann eine beliebige Zeichenkette mit eingebetteten Datums-/Zeitformaten oder eine von mehreren Kurzformen sein. Hier sind ein paar Beispiele:
- %Y-%m- %d ' - nur das Datum ausgeben, zum Beispiel '2023-04-05'
- %H:%M:%S' - nur die Uhrzeit ausgeben, zum Beispiel '16:07:33'
- %F %H:%M:%S' - sowohl Datum als auch Uhrzeit ausgeben, zum Beispiel '2023-04-05 16:07:33'
- ' iso8601 ' - einen Zeitstempel im ISO 8601-Format ausgeben, zum Beispiel '2023-04-05T16:07:33.123Z'
- timestamp_milli' - gibt einen Zeitstempel in Millisekunden (13 Ziffern) aus, zum Beispiel '1680710853123'

tz (optional)- die Zielzeitzone, in die der Zeitstempel vor der Formatierung konvertiert werden soll.

Beispiel 1: Drucken eines Zeitstempels mit Standardformat und +5h Offset

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

Beispiel 2: nur das Jahr und den Monat drucken

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

Beispiel 3: nur die Stunden und Minuten drucken

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

Beispiel 4: Drucken eines Zeitstempels in Millisekunden (13 Ziffern)

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

`fromUnixTime`

Konvertiert eine bestimmte Anzahl von Zeiteinheiten seit der UNIX-Epoche in einen Zeitstempel (in UTC). Die UNIX-Epoche beginnt am 1. Januar 1970 - frühere Zeitstempel werden durch negative Zahlen dargestellt.

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

Funktionsparameter:

unixTime (erforderlich)- die Anzahl der zu konvertierenden Zeiteinheiten. Kann entweder positiv oder negativ sein und wird auf eine ganze Zahl abgerundet.
timeUnit (optional)- die zu konvertierenden Zeiteinheiten. Der Standardwert ist 'Milli'.

Beispiel:

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

`multiplyInterval`

Multipliziert ein Intervall mit einem numerischen Faktor. Funktioniert sowohl mit ganzen Zahlen als auch mit Bruchzahlen. Äquivalent zu i * factor.

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

`now`

Gibt die aktuelle Zeit zum Zeitpunkt der Abfrageausführung zurück. Stabil über alle Zeilen und innerhalb der gesamten Abfrage, auch bei mehrfacher Verwendung. Nanosekunden-Auflösung, wenn die Laufzeitumgebung dies unterstützt, ansonsten Millisekunden-Auflösung.

now(): timestamp

Beispiel:

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`

Analysiert ein Intervall aus einer Zeichenkette mit dem Format NdNhNmNsNmsNusNns, wobei N die Anzahl der einzelnen Zeiteinheiten ist. Gibt null zurück, wenn die Eingabe nicht dem erwarteten Format entspricht:

Sie besteht aus Zeiteinheits-Komponenten - einer nicht-negativen ganzen Zahl, gefolgt von der Bezeichnung der kurzen Zeiteinheit. Unterstützte Zeiteinheiten sind: 'd', 'h', 'm', 's', 'ms', 'us', 'ns'.
Es muss mindestens eine Zeiteinheit enthalten sein.
Die gleiche Zeiteinheit kann nicht mehrfach vorkommen.
Die Komponenten müssen in der Reihenfolge der Zeiteinheiten abnehmen - von Tagen bis zu Nanosekunden.
Sie kann mit - beginnen, um negative Intervalle darzustellen.

parseInterval(string: string): interval

Beispiel 1: Parsen eines Null-Intervalls

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

Beispiel 2: Parsen eines positiven Intervalls

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

Beispiel 3: Parsen eines negativen Intervalls

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

`parseTimestamp`

Analysiert einen Zeitstempel aus einer Zeichenkette mit einer optionalen Formatspezifikation und Zeitzonenüberschreibung. Gibt null zurück, wenn die Eingabe nicht dem erwarteten Format entspricht.

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

Funktionsparameter:

string (erforderlich)- die Eingabe, aus der der Zeitstempel extrahiert werden soll.
format (optional)- eine Datums-/Zeitformatspezifikation für das Parsen von Zeitstempeln. Der Standardwert ist "auto". Das Format kann eine beliebige Zeichenkette mit eingebetteten Datums- und Zeitextraktoren, eine von mehreren Abkürzungen oder eine Kaskade von Formaten sein, die nacheinander ausprobiert werden. Hier sind ein paar Beispiele:
- %Y-%m- %d ' - nur das Datum analysieren, zum Beispiel '2023-04-05'
- %F %H:%M:%S' - parst Datum und Uhrzeit, zum Beispiel '2023-04-05 16:07:33'
- ' iso8601 ' - analysiert einen Zeitstempel im ISO 8601-Format, zum Beispiel '2023-04-05T16:07:33.123Z'
- timestamp_milli' - Parsen eines Zeitstempels in Millisekunden (13 Stellen), z. B. '1680710853123'
- %m/ %d /%Y|Zeitstempel_Sekunde' - parst entweder ein Datum oder einen Zeitstempel in Sekunden, in dieser Reihenfolge
tz (optional)- ein Zeitzonen-Override zur Konvertierung des Zeitstempels beim Parsen. Dieser Parameter überschreibt jede in der Eingabe vorhandene Zeitzone. Eine Zeitzone kann aus der Zeichenkette extrahiert werden, indem ein geeignetes Format verwendet und dieser Parameter weggelassen wird.

Beispiel 1: Parsen eines Datums mit dem Standardformat

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

Beispiel 2: Parsen eines Datums im US-Format

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

Beispiel 3: Parsen von Datum und Uhrzeit mit Einheiten

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

Beispiel 4: Parsen eines Zeitstempels in Sekunden (10 Ziffern)

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

`roundInterval`

Rundet ein Intervall auf eine Zeiteinheit scale. Geringere Zeiteinheiten werden mit Null angerechnet.

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

Funktionsparameter:

interval (erforderlich)- das zu rundende Intervall.
scale (erforderlich)- die maximale Zeiteinheit des zu haltenden Intervalls.

Beispiel:

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

`roundTime`

Rundet einen Zeitstempel auf das angegebene Intervall. Nützlich für die Aufteilung in Gruppen, z. B. Rundung auf 1h für stündliche Gruppen. Äquivalent zu date / interval.

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

Beispiel:

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`

Subtrahiert ein Intervall von einem anderen. Gleichwertig mit addInterval(left, -right) und left - right.

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

`subtractTime`

Subtrahiert ein Intervall von einem Zeitstempel. Gleichwertig mit addTime(t, -i) und t - i.

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

`toInterval`

Konvertiert eine Anzahl von bestimmten Zeiteinheiten in ein Intervall. Funktioniert sowohl mit Ganzzahl- als auch mit Gleitkommazahlen sowie mit positiven und negativen Zahlen.

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

Funktionsparameter:

number (erforderlich)- die Anzahl der zu konvertierenden Zeiteinheiten.
timeUnit (optional)- Zu konvertierende Zeiteinheiten. Die Standardeinstellung ist nano.

Beispiel 1: Umrechnung einer Fließkommazahl

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`

Konvertiert den Zeitstempel in eine bestimmte Anzahl von Zeiteinheiten seit der UNIX-Epoche (in UTC). Die UNIX-Epoche beginnt am 1. Januar 1970 - frühere Zeitstempel werden durch negative Zahlen dargestellt.

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

Funktionsparameter:

timestamp (erforderlich)- der zu konvertierende Zeitstempel.
timeUnit (optional)- die Zeiteinheiten, in die umgerechnet werden soll. Der Standardwert ist 'Milli'.

Beispiel:

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