Unità di tempo

Molte funzioni di data/ora accettano un argomento relativo all'unità di tempo per modificare il loro comportamento. DataPrime supporta unità di tempo da nanosecondi a giorni. Sono rappresentati come stringhe letterali del nome dell'unità di tempo in notazione lunga o corta:

• notazione lunga: day, hour, minute, second, milli, micro, nano

• notazione breve: d, h, m, s, ms, us, ns

Fusi orari

DataPrime i timestamp sono sempre memorizzati nel fuso orario UTC, ma alcune funzioni data/ora accettano un argomento relativo al fuso orario per modificare il loro comportamento. Gli argomenti dei fusi orari sono stringhe che specificano un offset, un'abbreviazione o un identificatore di fuso orario:

• sfasamento del fuso orario in ore (ad esempio, '+01' o '-02')
• offset del fuso orario in ore e minuti (ad esempio, '+0130' o '-0230')
• offset del fuso orario in ore e minuti con separatore (ad esempio '+01:30' o '-02:30')
• abbreviazione del fuso orario (ad esempio, "UTC", "GMT", "EST" e così via)
• identificatore del fuso orario (ad esempio, "Asia/Yerevan", "Europa/Zurigo", "America/Winnipeg" e così via)

addInterval

Aggiunge due intervalli tra loro. Funziona anche con intervalli negativi. Equivalente a left + right.

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

addTime

Aggiunge un intervallo a un timestamp. Funziona anche con intervalli negativi. Equivalente a t + i.

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

diffTime

Calcola la durata tra due timestamp. Positivo se to > from, negativo se to < from. Equivale a to - from.

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

extractTime

Estrae una data o un'unità di tempo da un timestamp. Restituisce un numero in virgola mobile per unità di tempo inferiori al minuto, altrimenti un numero intero. Le unità di misura della data come month o week partono da 1 (non da 0).

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

Parametri di funzione:

• timestamp (obbligatorio)- il timestamp da cui estrarre.
• unit (obbligatorio)- la data o l'unità di tempo da estrarre. Deve essere un letterale di stringa e uno dei seguenti:
  • qualsiasi unità di tempo in notazione lunga o corta
  • un'unità di data in notazione lunga: year, month, week, day_of_year, day_of_week
  • un'unità di data in notazione breve: Y, M, W, doy, dow
• tz (facoltativo)- un fuso orario da convertire prima di estrarre il timestamp.

Esempio 1: estrarre l'ora a Tokyo

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

Esempio 2: estrarre il numero di secondi

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

Esempio 3: estrarre il mese del timestamp

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

Esempio 4: estrarre il giorno della settimana

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

formatInterval

Formatta interval in una stringa con un'unità di tempo opzionale scale.

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

Parametri di funzione:

• interval (obbligatorio)- l'intervallo da formattare.
• scale (opzionale)- l'unità di tempo massima dell'intervallo da mostrare. L'impostazione predefinita è nano.

Esempio:

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

formatTimestamp

Formatta un timestamp in una stringa con una specifica di formato opzionale e un fuso orario di destinazione.

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

Parametri di funzione:

• timestamp (obbligatorio)- il timestamp da formattare.
• format (opzionale)- una specifica del formato data/ora per l'analisi dei timestamp. Il valore predefinito è ' iso8601 '. Il formato può essere una qualsiasi stringa con formattatori di data/ora incorporati o una delle varie abbreviazioni. Ecco alcuni esempi:
  • '%Y-%m- %d ' - stampa solo la data, ad esempio "2023-04-05"
  • '%H:%M:%S' - stampa solo l'ora, ad esempio '16:07:33'
  • '%F %H:%M:%S' - stampa sia la data che l'ora, ad esempio '2023-04-05 16:07:33'
  • ' iso8601 ' - stampa un timestamp in formato ISO 8601, ad esempio '2023-04-05T16:07:33.123Z'
  • timestamp_milli" - stampa un timestamp in millisecondi (13 cifre), ad esempio "1680710853123"

tz (opzionale)- il fuso orario di destinazione per convertire il timestamp prima della formattazione.

Esempio 1: stampare un timestamp con il formato predefinito e l'offset +5h

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

Esempio 2: stampare solo l'anno e il mese

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

Esempio 3: stampare solo le ore e i minuti

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

Esempio 4: stampare un timestamp in millisecondi (13 cifre)

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

fromUnixTime

Converte un numero di unità di tempo specifiche dall'epoca UNIX in un timestamp (in UTC). L'epoca UNIX inizia il 1° gennaio 1970; i timestamp precedenti sono rappresentati da numeri negativi.

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

Parametri di funzione:

• unixTime (obbligatorio)- la quantità di unità di tempo da convertire. Può essere positivo o negativo e sarà arrotondato per difetto a un numero intero.
• timeUnit (opzionale)- le unità di tempo da convertire. Valore predefinito: "milli".

Esempio:

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

multiplyInterval

Moltiplica un intervallo per un fattore numerico. Funziona sia con i numeri interi che con quelli frazionari. Equivalente a i * factor.

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

now

Restituisce l'ora corrente al momento dell'esecuzione della query. Stabile su tutte le righe e all'interno dell'intera query, anche se utilizzata più volte. Risoluzione in nanosecondi se il runtime la supporta, altrimenti risoluzione in millisecondi.

now(): timestamp

Esempio:

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

Analizza un intervallo da una stringa con il formato NdNhNmNsNmsNusNns dove N è la quantità di ogni unità di tempo. Restituisce null se l'input non corrisponde al formato previsto:

• Si tratta di componenti dell'unità di tempo - un numero intero non negativo seguito dal nome dell'unità di tempo breve. Le unità di tempo supportate sono: 'd', 'h', 'm', 's', 'ms', 'us', 'ns'.
• Deve essere presente almeno una componente di unità di tempo.
• La stessa unità temporale non può comparire più di una volta.
• I componenti devono essere decrescenti in ordine di unità di tempo, da giorni a nanosecondi.
• Può iniziare con - per rappresentare intervalli negativi.

parseInterval(string: string): interval

Esempio 1: analizzare un intervallo zero

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

Esempio 2: analizzare un intervallo positivo

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

Esempio 3: analizzare un intervallo negativo

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

parseTimestamp

Analizza un timestamp da una stringa con una specifica di formato opzionale e un override del fuso orario. Restituisce null se l'input non corrisponde al formato previsto.

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

Parametri di funzione:

• string (obbligatorio)- l'input da cui estrarre il timestamp.
• format (opzionale)- una specifica del formato data/ora per l'analisi dei timestamp. Per impostazione predefinita è "auto". Il formato può essere una qualsiasi stringa con estrattori di data/ora incorporati, uno dei vari stenografici o una cascata di formati da tentare in sequenza. Ecco alcuni esempi:
  • '%Y-%m- %d ' - analizza solo la data, ad esempio "2023-04-05"
  • '%F %H:%M:%S' - analizza data e ora, ad esempio '2023-04-05 16:07:33'
  • ' iso8601 ' - analizza un timestamp nel formato ISO 8601, ad esempio '2023-04-05T16:07:33.123Z'
  • timestamp_milli" - analizza un timestamp in millisecondi (13 cifre), ad esempio "1680710853123"
  • '%m/ %d /%Y|timestamp_second' - analizza una data o un timestamp in secondi, in quest'ordine
• tz (facoltativo)- un fuso orario per convertire il timestamp durante l'analisi. Questo parametro sovrascrive qualsiasi fuso orario presente nell'ingresso. Un fuso orario può essere estratto dalla stringa utilizzando un formato appropriato e omettendo questo parametro.

Esempio 1: analizzare una data con il formato predefinito

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

Esempio 2: analizzare una data in formato USA

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

Esempio 3: analizzare data e ora con unità di misura

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

Esempio 4: analizzare un timestamp in secondi (10 cifre)

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

roundInterval

Arrotonda un intervallo a un'unità di tempo scale. Le unità di tempo inferiori saranno azzerate.

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

Parametri di funzione:

• interval (obbligatorio)- l'intervallo da arrotondare.
• scale (obbligatorio)- l'unità di tempo massima dell'intervallo da mantenere.

Esempio:

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

roundTime

Arrotonda un timestamp all'intervallo dato. Utile per i bucket, ad esempio per arrotondare a 1h per i bucket orari. Equivalente a date / interval.

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

Esempio:

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

Sottrae un intervallo da un altro. Equivalente a addInterval(left, -right) e left - right.

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

subtractTime

Sottrae un intervallo da un timestamp. Equivalente a addTime(t, -i) e t - i.

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

toInterval

Converte un numero di unità di tempo specifiche in un intervallo. Funziona con numeri interi e in virgola mobile, positivi e negativi.

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

Parametri di funzione:

• number (obbligatorio)- la quantità di unità di tempo da convertire.
• timeUnit (opzionale)- Unità di tempo da convertire. L'impostazione predefinita è nano.

Esempio 1: convertire un numero in virgola mobile

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

Converte il timestamp in un numero di unità di tempo specifiche dall'epoca UNIX (in UTC). L'epoca UNIX inizia il 1° gennaio 1970; i timestamp precedenti sono rappresentati da numeri negativi.

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

Parametri di funzione:

• timestamp (obbligatorio)- il timestamp da convertire.
• timeUnit (opzionale)- le unità di misura del tempo da convertire. Valore predefinito: "milli".

Esempio:

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