DataPrime funciones fecha / hora

Esta guía proporciona un glosario de las funciones disponibles en IBM® Cloud Logs DataPrime para procesar marcas de tiempo, intervalos y otras construcciones relacionadas con el tiempo.

Unidades de tiempo

Muchas funciones fecha/hora aceptan un argumento de unidad de tiempo para modificar su comportamiento. DataPrime admite unidades de tiempo desde nanosegundos hasta días. Se representan como cadenas literales del nombre de la unidad de tiempo en notación larga o corta:

notación larga: day, hour, minute, second, milli, micro, nano
notación abreviada: d, h, m, s, ms, us, ns

Zonas horarias

DataPrime las marcas de tiempo se almacenan siempre en la zona horaria UTC, pero algunas funciones fecha/hora aceptan un argumento de zona horaria para modificar su comportamiento. Los argumentos de zona horaria son cadenas que especifican un desplazamiento, abreviatura o identificador de zona horaria:

desfase horario en horas (por ejemplo, "+01" o "-02")
desfase horario en horas y minutos (por ejemplo, "+0130" o "-0230")
desfase horario en horas y minutos con separador (por ejemplo "+01:30" o "-02:30")
abreviatura de zona horaria (por ejemplo, "UTC", "GMT", "EST", etc.)
identificador de zona horaria (por ejemplo, "Asia/Yerevan", "Europe/Zurich", "America/Winnipeg", etc.)

`addInterval`

Suma dos intervalos. También funciona con intervalos negativos. Equivalente a left + right.

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

`addTime`

Añade un intervalo a una marca de tiempo. También funciona con intervalos negativos. Equivalente a t + i.

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

`diffTime`

Calcula la duración entre dos marcas de tiempo. Positivo si to > from, negativo si to < from. Equivalente a to - from.

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

`extractTime`

Extrae una fecha o una unidad de tiempo de una marca de tiempo. Devuelve un número de coma flotante para unidades de tiempo inferiores a un minuto; en caso contrario, un número entero. Las unidades de fecha como month o week empiezan desde 1 (no desde 0).

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

Parámetro de la función:

timestamp (obligatorio)- la marca de tiempo de la que extraer.
unit (obligatorio)- la unidad de fecha u hora a extraer. Debe ser un literal de cadena y uno de:
- cualquier unidad de tiempo en notación larga o corta
- una unidad de fecha en notación larga: year, month, week, day_of_year, day_of_week
- una unidad de fecha en notación abreviada: Y, M, W, doy, dow
tz (opcional)- una zona horaria para convertir la marca de tiempo antes de extraerla.

Ejemplo 1: extraer la hora en Tokio

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

Ejemplo 2: extraer el número de segundos

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

Ejemplo 3: extraer el mes de la marca de tiempo

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

Ejemplo 4: extraer el día de la semana

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

`formatInterval`

Formatea interval a una cadena con una unidad de tiempo opcional scale.

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

Parámetro de la función:

interval (requerido)- el intervalo a formatear.
scale (opcional)- la unidad de tiempo máxima del intervalo a mostrar. Por defecto es nano.

Ejemplo:

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

`formatTimestamp`

Formatea una marca de tiempo en una cadena con una especificación de formato opcional y una zona horaria de destino.

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

Parámetro de la función:

timestamp (obligatorio)- la marca de tiempo a formatear.
format (opcional)- una especificación de formato de fecha/hora para analizar marcas de tiempo. Por defecto ' iso8601 '. El formato puede ser cualquier cadena con formateadores de fecha/hora incrustados, o una de varias abreviaturas. He aquí algunos ejemplos:
- '%Y-%m- %d ' - imprime sólo la fecha, por ejemplo '2023-04-05'
- '%H:%M:%S' - imprime sólo la hora, por ejemplo '16:07:33'
- %F %H:%M:%S' - imprime tanto la fecha como la hora, por ejemplo '2023-04-05 16:07:33'
- ' iso8601 ' - imprime una marca de tiempo en formato ISO 8601, por ejemplo '2023-04-05T16:07:33.123Z'
- timestamp_milli' - imprime una marca de tiempo en milisegundos (13 dígitos), por ejemplo '1680710853123'

tz (opcional)- la zona horaria de destino para convertir la marca de tiempo antes de formatearla.

Ejemplo 1: imprimir una marca de tiempo con el formato predeterminado y el desplazamiento +5h

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

Ejemplo 2: imprimir sólo el año y el mes

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

Ejemplo 3: imprimir sólo las horas y los minutos

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

Ejemplo 4: imprimir una marca de tiempo en milisegundos (13 dígitos)

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

`fromUnixTime`

Convierte un número de unidades de tiempo específico desde la época UNIX a una marca de tiempo (en UTC). La época UNIX comienza el 1 de enero de 1970 - las marcas de tiempo anteriores se representan con números negativos.

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

Parámetro de la función:

unixTime (requerido)- la cantidad de unidades de tiempo a convertir. Puede ser positivo o negativo y se redondeará a un número entero.
timeUnit (opcional)- las unidades de tiempo a convertir. Por defecto es 'milli'.

Ejemplo:

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

`multiplyInterval`

Multiplica un intervalo por un factor numérico. Funciona tanto con números enteros como fraccionarios. Equivalente a i * factor.

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

`now`

Devuelve la hora actual en el momento de ejecución de la consulta. Estable en todas las filas y en toda la consulta, incluso cuando se utiliza varias veces. Resolución en nanosegundos si el tiempo de ejecución lo admite; en caso contrario, resolución en milisegundos.

now(): timestamp

Ejemplo:

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`

Analiza un intervalo a partir de una cadena con formato NdNhNmNsNmsNusNns donde N es la cantidad de cada unidad de tiempo. Devuelve null cuando la entrada no coincide con el formato esperado:

Consta de componentes de unidad de tiempo: un número entero no negativo seguido del nombre abreviado de la unidad de tiempo. Las unidades de tiempo admitidas son: 'd', 'h', 'm', 's', 'ms', 'us', 'ns'.
Debe haber al menos un componente de unidad de tiempo.
La misma unidad de tiempo no puede aparecer más de una vez.
Los componentes deben ser decrecientes en orden de unidades de tiempo: de días a nanosegundos.
Puede empezar por - para representar intervalos negativos.

parseInterval(string: string): interval

Ejemplo 1: analizar un intervalo cero

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

Ejemplo 2: analizar un intervalo positivo

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

Ejemplo 3: analizar un intervalo negativo

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

`parseTimestamp`

Analiza una marca de tiempo a partir de una cadena con una especificación de formato opcional y un cambio de zona horaria. Devuelve null cuando la entrada no coincide con el formato esperado.

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

Parámetro de la función:

string (obligatorio)- la entrada de la que se extraerá la marca de tiempo.
format (opcional)- una especificación de formato de fecha/hora para analizar marcas de tiempo. Por defecto es "auto". El formato puede ser cualquier cadena con extractores de fecha/hora incrustados, una de varias abreviaturas o una cascada de formatos que deben intentarse en secuencia. He aquí algunos ejemplos:
- %Y-%m- %d ' - sólo analiza la fecha, por ejemplo "2023-04-05"
- %F %H:%M:%S' - analiza la fecha y la hora, por ejemplo "2023-04-05 16:07:33"
- ' iso8601 ' - analiza una marca de tiempo en formato ISO 8601, por ejemplo '2023-04-05T16:07:33.123Z'
- timestamp_milli' - analiza una marca de tiempo en milisegundos (13 dígitos), por ejemplo "1680710853123"
- %m/ %d /%Y|timestamp_second' - analiza una fecha o una marca de tiempo en segundos, en este orden
tz (opcional)- una zona horaria para convertir la fecha y hora durante el análisis. Este parámetro anulará cualquier zona horaria presente en la entrada. Se puede extraer una zona horaria de la cadena utilizando un formato adecuado y omitiendo este parámetro.

Ejemplo 1: analizar una fecha con el formato por defecto

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

Ejemplo 2: analizar una fecha en formato US

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

Ejemplo 3: analizar fecha y hora con unidades

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

Ejemplo 4: analizar una marca de tiempo en segundos (10 dígitos)

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

`roundInterval`

Redondea un intervalo a una unidad de tiempo scale. Las unidades de tiempo inferiores se pondrán a cero.

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

Parámetro de la función:

interval (obligatorio)- el intervalo a redondear.
scale (requerido)- la unidad de tiempo máxima del intervalo a mantener.

Ejemplo:

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

`roundTime`

Redondea una marca de tiempo al intervalo dado. Útil para el bucketing, por ejemplo, redondeando a 1h para buckets horarios. Equivalente a date / interval.

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

Ejemplo:

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`

Resta un intervalo de otro. Equivalente a addInterval(left, -right) y left - right.

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

`subtractTime`

Resta un intervalo de una marca de tiempo. Equivalente a addTime(t, -i) y t - i.

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

`toInterval`

Convierte un número de unidades de tiempo específicas en un intervalo. Funciona con números enteros y flotantes y con números positivos y negativos.

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

Parámetro de la función:

number (requerido)- la cantidad de unidades de tiempo a convertir.
timeUnit (opcional)- Unidades de tiempo a convertir. Por defecto es nano.

Ejemplo 1: convertir un número en coma flotante

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`

Convierte la marca de tiempo a un número de unidades de tiempo específicas desde la época UNIX (en UTC). La época UNIX comienza el 1 de enero de 1970 - las marcas de tiempo anteriores se representan con números negativos.

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

Parámetro de la función:

timestamp (obligatorio)- la fecha y hora a convertir.
timeUnit (opcional)- las unidades de tiempo a convertir. Por defecto es 'milli'.

Ejemplo:

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