DataPrime fonctions date / heure

Ce guide fournit un glossaire des fonctions disponibles sur IBM® Cloud Logs DataPrime pour le traitement des horodatages, des intervalles et d'autres constructions temporelles.

Unités de temps

De nombreuses fonctions de date et d'heure acceptent un argument d'unité de temps pour modifier leur comportement. DataPrime prend en charge des unités de temps allant de la nanoseconde au jour. Ils sont représentés par des chaînes littérales du nom de l'unité de temps en notation longue ou courte :

notation longue : day, hour, minute, second, milli, micro, nano
notation courte : d, h, m, s, ms, us, ns

Fuseaux horaires

DataPrime les horodatages sont toujours stockés dans le fuseau horaire UTC, mais certaines fonctions date/heure acceptent un argument de fuseau horaire pour modifier leur comportement. Les arguments relatifs au fuseau horaire sont des chaînes de caractères qui spécifient un décalage, une abréviation ou un identifiant de fuseau horaire :

décalage du fuseau horaire en heures (par exemple, "+01" ou "-02")
décalage du fuseau horaire en heures et minutes (par exemple, "+0130" ou "-0230")
décalage du fuseau horaire en heures et minutes avec séparateur (par exemple '+01:30' ou '-02:30')
abréviation du fuseau horaire (par exemple, "UTC", "GMT", "EST", etc.)
l'identifiant du fuseau horaire (par exemple, "Asie/Yerevan", "Europe/Zurich", "Amérique/Winnipeg", etc.)

`addInterval`

Additionne deux intervalles. Fonctionne également avec des intervalles négatifs. Équivalent à left + right.

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

`addTime`

Ajoute un intervalle à un horodatage. Fonctionne également avec des intervalles négatifs. Équivalent à t + i.

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

`diffTime`

Calcule la durée entre deux horodatages. Positif si to > from, négatif si to < from. Équivalent à to - from.

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

`extractTime`

Extrait une date ou une unité de temps d'un horodatage. Renvoie un nombre à virgule flottante pour les unités de temps inférieures à une minute, sinon un nombre entier. Les unités de date telles que month ou week commencent à 1 (et non à 0).

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

Paramètres de la fonction :

timestamp (obligatoire)- l'horodatage à extraire.
unit (obligatoire)- la date ou l'unité de temps à extraire. Doit être une chaîne littérale et l'un des éléments suivants :
- toute unité de temps en notation longue ou courte
- une unité de date en notation longue : year, month, week, day_of_year, day_of_week
- une unité de date en notation courte : Y, M, W, doy, dow
tz (optionnel)- un fuseau horaire pour convertir l'horodatage avant de l'extraire.

Exemple 1 : extraire l'heure à Tokyo

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

Exemple 2 : extraire le nombre de secondes

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

Exemple 3 : extraire le mois de l'horodatage

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

Exemple 4 : extraire le jour de la semaine

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

`formatInterval`

Formate interval en une chaîne de caractères avec une unité de temps optionnelle scale.

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

Paramètres de la fonction :

interval (obligatoire)- l'intervalle à formater.
scale (facultatif)- l'unité de temps maximale de l'intervalle à afficher. La valeur par défaut est nano.

Exemple :

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

`formatTimestamp`

Formate un horodatage en une chaîne de caractères avec une spécification de format optionnelle et un fuseau horaire de destination.

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

Paramètres de la fonction :

timestamp (obligatoire)- l'horodatage à formater.
format (facultatif)- une spécification du format date/heure pour l'analyse des horodatages. La valeur par défaut est ' iso8601 '. Le format peut être n'importe quelle chaîne avec des formateurs de date et d'heure intégrés, ou l'un de plusieurs raccourcis. En voici quelques exemples :
- '%Y-%m- %d ' - imprime uniquement la date, par exemple '2023-04-05'
- '%H:%M:%S' - imprime uniquement l'heure, par exemple '16:07:33'
- '%F %H:%M:%S' - imprime la date et l'heure, par exemple '2023-04-05 16:07:33'
- ' iso8601 ' - imprime un horodatage au format ISO 8601, par exemple '2023-04-05T16:07:33.123Z'
- 'timestamp_milli' - imprime un timestamp en millisecondes (13 chiffres), par exemple '1680710853123'

tz (facultatif)- le fuseau horaire de destination pour convertir l'horodatage avant le formatage.

Exemple 1 : imprimer un horodatage avec le format par défaut et le décalage +5h

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

Exemple 2 : imprimer uniquement l'année et le mois

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

Exemple 3 : imprimer uniquement les heures et les minutes

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

Exemple 4 : imprimer un horodatage en millisecondes (13 chiffres)

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

`fromUnixTime`

Convertit un nombre d'unités de temps spécifiques depuis l'époque UNIX en un horodatage (en UTC). L'époque UNIX commence le 1er janvier 1970 - les dates antérieures sont représentées par des nombres négatifs.

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

Paramètres de la fonction :

unixTime (obligatoire)- le nombre d'unités de temps à convertir. Peut être positif ou négatif et sera arrondi à un nombre entier inférieur.
timeUnit (facultatif)- les unités de temps à convertir. La valeur par défaut est "milli".

Exemple :

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

`multiplyInterval`

Multiplie un intervalle par un facteur numérique. Fonctionne aussi bien avec des nombres entiers qu'avec des nombres fractionnaires. Équivalent à i * factor.

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

`now`

Renvoie l'heure actuelle au moment de l'exécution de la requête. Stabilité sur toutes les lignes et dans l'ensemble de la requête, même en cas d'utilisation répétée. Résolution en nanosecondes si le système d'exécution le prend en charge, sinon résolution en millisecondes.

now(): timestamp

Exemple :

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`

Analyse un intervalle à partir d'une chaîne de caractères au format NdNhNmNsNmsNusNns où N est la quantité de chaque unité de temps. Retourne null si l'entrée ne correspond pas au format attendu :

Il se compose des éléments de l'unité de temps - un nombre entier non négatif suivi du nom court de l'unité de temps. Les unités de temps prises en charge sont les suivantes : 'd', 'h', 'm', 's', 'ms', 'us', 'ns'.
Il doit y avoir au moins un élément d'unité de temps.
La même unité de temps ne peut pas apparaître plus d'une fois.
Les composants doivent être décroissants dans l'ordre des unités de temps - des jours aux nanosecondes.
Il peut commencer par - pour représenter des intervalles négatifs.

parseInterval(string: string): interval

Exemple 1 : analyse d'un intervalle de zéro

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

Exemple 2 : analyser un intervalle positif

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

Exemple 3 : analyse d'un intervalle négatif

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

`parseTimestamp`

Analyse un horodatage à partir d'une chaîne de caractères avec une spécification de format optionnelle et une dérogation de fuseau horaire. Retourne null si l'entrée ne correspond pas au format attendu.

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

Paramètres de la fonction :

string (obligatoire)- l'entrée à partir de laquelle l'horodatage sera extrait.
format (facultatif)- une spécification du format date/heure pour l'analyse des horodatages. La valeur par défaut est "auto". Le format peut être n'importe quelle chaîne avec des extracteurs de date et d'heure intégrés, un raccourci parmi d'autres, ou une cascade de formats à essayer dans l'ordre. En voici quelques exemples :
- '%Y-%m- %d ' - analyse uniquement la date, par exemple '2023-04-05'
- '%F %H:%M:%S' - analyse la date et l'heure, par exemple '2023-04-05 16:07:33'
- ' iso8601 ' - analyse un timestamp au format ISO 8601, par exemple '2023-04-05T16:07:33.123Z'
- timestamp_milli" - analyse un timestamp en millisecondes (13 chiffres), par exemple "1680710853123"
- '%m/ %d /%Y|timestamp_second' - analyse une date ou un timestamp en secondes, dans cet ordre
tz (optionnel)- un fuseau horaire pour convertir l'horodatage lors de l'analyse. Ce paramètre remplace tout fuseau horaire présent dans l'entrée. Un fuseau horaire peut être extrait de la chaîne en utilisant un format approprié et en omettant ce paramètre.

Exemple 1 : analyser une date avec le format par défaut

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

Exemple 2 : analyser une date au format US

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

Exemple 3 : analyser la date et l'heure avec les unités

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

Exemple 4 : analyser un timestamp en secondes (10 chiffres)

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

`roundInterval`

Arrondit un intervalle à une unité de temps scale. Les unités de temps inférieures seront mises à zéro.

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

Paramètres de la fonction :

interval (obligatoire)- l'intervalle à arrondir.
scale (obligatoire)- l'unité de temps maximale de l'intervalle à conserver.

Exemple :

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

`roundTime`

Arrondit un timestamp à l'intervalle donné. Utile pour le regroupement, par exemple en arrondissant à 1h pour les regroupements horaires. Équivalent à date / interval.

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

Exemple :

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`

Soustrait un intervalle d'un autre. Équivalent à addInterval(left, -right) et left - right.

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

`subtractTime`

Soustrait un intervalle d'un horodatage. Équivalent à addTime(t, -i) et t - i.

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

`toInterval`

Convertit un nombre d'unités de temps spécifiques en un intervalle. Fonctionne avec des nombres entiers et des nombres à virgule flottante, positifs et négatifs.

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

Paramètres de la fonction :

number (obligatoire)- le nombre d'unités de temps à convertir.
timeUnit (facultatif)- Unités de temps à convertir. La valeur par défaut est nano.

Exemple 1 : convertir un nombre à virgule flottante

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`

Convertit l'horodatage en un nombre d'unités de temps spécifiques depuis l'époque UNIX (en UTC). L'époque UNIX commence le 1er janvier 1970 - les dates antérieures sont représentées par des nombres négatifs.

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

Paramètres de la fonction :

timestamp (obligatoire)- l'horodatage à convertir.
timeUnit (facultatif)- les unités de temps à convertir. La valeur par défaut est "milli".

Exemple :

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