DataPrime funções de data/hora

Este guia fornece um glossário das funções disponíveis no site IBM® Cloud Logs DataPrime para o processamento de carimbos de data/hora, intervalos e outras construções relacionadas ao tempo.

Unidades de tempo

Muitas funções de data/hora aceitam um argumento de unidade de tempo para modificar seu comportamento. DataPrime suporta unidades de tempo de nanossegundos a dias. Eles são representados como cadeias literais do nome da unidade de tempo em notação longa ou curta:

notação longa: day, hour, minute, second, milli, micro, nano
notação curta: d, h, m, s, ms, us, ns

Fusos horários

DataPrime os carimbos de data/hora são sempre armazenados no fuso horário UTC, mas algumas funções de data/hora aceitam um argumento de fuso horário para modificar seu comportamento. Os argumentos de fuso horário são cadeias de caracteres que especificam um deslocamento, abreviação ou identificador de fuso horário:

deslocamento de fuso horário em horas (por exemplo, '+01' ou '-02')
deslocamento de fuso horário em horas e minutos (por exemplo, '+0130' ou '-0230')
deslocamento de fuso horário em horas e minutos com separador (por exemplo, '+01:30' ou '-02:30')
abreviação de fuso horário (por exemplo, "UTC", "GMT", "EST" e assim por diante)
identificador de fuso horário (por exemplo, "Ásia/Yerevan", "Europa/Zurique", "América/Winnipeg" e assim por diante)

`addInterval`

Adiciona dois intervalos juntos. Também funciona com intervalos negativos. Equivalente a left + right.

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

`addTime`

Adiciona um intervalo a um registro de data e hora. Também funciona com intervalos negativos. Equivalente a t + i.

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

`diffTime`

Calcula a duração entre dois registros de data e hora. Positivo se to > from, negativo se to < from. Equivalente a to - from.

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

`extractTime`

Extrai uma data ou unidade de tempo de um carimbo de data/hora. Retorna um número de ponto flutuante para unidades de tempo inferiores a um minuto; caso contrário, retorna um número inteiro. As unidades de data, como month ou week, começam em 1 (e não em 0).

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

Parâmetros de função:

timestamp (obrigatório)- o registro de data e hora do qual extrair.
unit (obrigatório)- a unidade de data ou hora a ser extraída. Deve ser um literal de string e um de:
- qualquer unidade de tempo em notação longa ou curta
- uma unidade de data em notação longa: year, month, week, day_of_year, day_of_week
- uma unidade de data em notação curta: Y, M, W, doy, dow
tz (opcional)- um fuso horário para converter o registro de data e hora antes da extração.

Exemplo 1: extrair a hora em Tóquio

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

Exemplo 2: extrair o número de segundos

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

Exemplo 3: extrair o mês do registro de data e hora

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

Exemplo 4: extrair o dia da semana

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

`formatInterval`

Formata interval em uma string com uma unidade de tempo opcional scale.

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

Parâmetros de função:

interval (obrigatório)- o intervalo a ser formatado.
scale (opcional)- a unidade de tempo máxima do intervalo a ser exibido. O padrão é nano.

Exemplo:

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

`formatTimestamp`

Formata um carimbo de data/hora em uma cadeia de caracteres com uma especificação de formato opcional e fuso horário de destino.

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

Parâmetros de função:

timestamp (obrigatório)- o registro de data e hora a ser formatado.
format (opcional)- uma especificação de formato de data/hora para análise de carimbos de data/hora. O padrão é ' iso8601 '. O formato pode ser qualquer cadeia de caracteres com formatadores de data/hora incorporados ou uma das várias abreviações. Aqui estão alguns exemplos:
- '%Y-%m- %d ' - imprime somente a data, por exemplo, '2023-04-05'
- '%H:%M:%S' - imprime somente a hora, por exemplo, '16:07:33'
- '%F %H:%M:%S' - imprime a data e a hora, por exemplo, '2023-04-05 16:07:33'
- ' iso8601 ' - imprime um registro de data e hora no formato ISO 8601, por exemplo '2023-04-05T16:07:33.123Z'
- 'timestamp_milli' - imprime um registro de data e hora em milissegundos (13 dígitos), por exemplo, '1680710853123'

tz (opcional)- o fuso horário de destino para converter o registro de data e hora antes da formatação.

Exemplo 1: imprimir um registro de data e hora com o formato padrão e o deslocamento +5h

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

Exemplo 2: imprimir apenas o ano e o mês

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

Exemplo 3: imprimir apenas as horas e os minutos

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

Exemplo 4: imprimir um registro de data e hora em milissegundos (13 dígitos)

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

`fromUnixTime`

Converte um número de unidades de tempo específicas desde a época do UNIX em um registro de data e hora (em UTC). A época do UNIX começa em 1º de janeiro de 1970 - os registros de data e hora anteriores são representados por números negativos.

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

Parâmetros de função:

unixTime (obrigatório)- a quantidade de unidades de tempo a serem convertidas. Pode ser positivo ou negativo e será arredondado para um número inteiro.
timeUnit (opcional)- as unidades de tempo a serem convertidas. O padrão é "milli".

Exemplo:

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

`multiplyInterval`

Multiplica um intervalo por um fator numérico. Funciona com números inteiros e fracionários. Equivalente a i * factor.

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

`now`

Retorna a hora atual no momento da execução da consulta. Estável em todas as linhas e em toda a consulta, mesmo quando usado várias vezes. Resolução de nanossegundos se o tempo de execução for compatível; caso contrário, resolução de milissegundos.

now(): timestamp

Exemplo:

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`

Analisa um intervalo de uma cadeia de caracteres com o formato NdNhNmNsNmsNusNns, em que N é a quantidade de cada unidade de tempo. Retorna nulo quando a entrada não corresponde ao formato esperado:

Ele consiste em componentes de unidade de tempo - um número inteiro não negativo seguido pelo nome curto da unidade de tempo. As unidades de tempo compatíveis são: 'd', 'h', 'm', 's', 'ms', 'us', 'ns'.
Deve haver pelo menos um componente de unidade de tempo.
A mesma unidade de tempo não pode aparecer mais de uma vez.
Os componentes devem ser decrescentes em ordem de unidade de tempo, de dias a nanossegundos.
Ele pode começar com - para representar intervalos negativos.

parseInterval(string: string): interval

Exemplo 1: analisar um intervalo zero

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

Exemplo 2: analisar um intervalo positivo

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

Exemplo 3: analisar um intervalo negativo

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

`parseTimestamp`

Analisa um carimbo de data/hora a partir de uma cadeia de caracteres com uma especificação de formato opcional e substituição de fuso horário. Retorna nulo quando a entrada não corresponde ao formato esperado.

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

Parâmetros de função:

string (obrigatório)- a entrada da qual o registro de data e hora será extraído.
format (opcional)- uma especificação de formato de data/hora para análise de carimbos de data/hora. O padrão é "auto". O formato pode ser qualquer cadeia de caracteres com extratores de data/hora incorporados, uma das várias abreviações ou uma cascata de formatos a serem tentados em sequência. Aqui estão alguns exemplos:
- '%Y-%m- %d ' - analisa somente a data, por exemplo, '2023-04-05'
- '%F %H:%M:%S' - analisa a data e a hora, por exemplo, '2023-04-05 16:07:33'
- ' iso8601 ' - analisa um registro de data e hora no formato ISO 8601, por exemplo '2023-04-05T16:07:33.123Z'
- 'timestamp_milli' - analisa um registro de data e hora em milissegundos (13 dígitos), por exemplo, '1680710853123'
- '%m/ %d /%Y|timestamp_second' - analisa uma data ou um carimbo de data/hora em segundos, nessa ordem
tz (opcional)- uma substituição de fuso horário para converter o registro de data e hora durante a análise. Esse parâmetro substituirá qualquer fuso horário presente na entrada. Um fuso horário pode ser extraído da cadeia de caracteres usando um formato apropriado e omitindo esse parâmetro.

Exemplo 1: analisar uma data com o formato padrão

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

Exemplo 2: analisar uma data no formato americano

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

Exemplo 3: analisar data e hora com unidades

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

Exemplo 4: analisar um registro de data e hora em segundos (10 dígitos)

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

`roundInterval`

Arredonda um intervalo para uma unidade de tempo scale. As unidades de tempo menores serão zeradas.

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

Parâmetros de função:

interval (obrigatório)- o intervalo a ser arredondado.
scale (obrigatório)- a unidade de tempo máxima do intervalo a ser mantido.

Exemplo:

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

`roundTime`

Arredonda um registro de data e hora para o intervalo fornecido. Útil para agrupamento, por exemplo, arredondamento para 1h para agrupamentos por hora. Equivalente a date / interval.

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

Exemplo:

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`

Subtrai um intervalo de outro. Equivalente a addInterval(left, -right) e left - right.

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

`subtractTime`

Subtrai um intervalo de um registro de data e hora. Equivalente a addTime(t, -i) e t - i.

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

`toInterval`

Converte um número de unidades de tempo específicas em um intervalo. Funciona com números inteiros e de ponto flutuante, positivos e negativos.

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

Parâmetros de função:

number (obrigatório)- a quantidade de unidades de tempo a serem convertidas.
timeUnit (opcional)- Unidades de tempo a serem convertidas. O padrão é nano.

Exemplo 1: converter um número de ponto flutuante

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 o registro de data e hora em um número de unidades de tempo específicas desde a época do UNIX (em UTC). A época do UNIX começa em 1º de janeiro de 1970 - os registros de data e hora anteriores são representados por números negativos.

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

Parâmetros de função:

timestamp (obrigatório)- o registro de data e hora a ser convertido.
timeUnit (opcional)- as unidades de tempo para as quais converter. O padrão é "milli".

Exemplo:

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