Funções De Data E Hora

Versão:
2023.1
Last modified: April 05, 2023

Uma função de data e hora executa uma ação ou cálculo em um valor de data/hora. Use funções de data e hora para adicionar ou subtrair intervalos, encontrar a data atual, encontrar o primeiro ou o último dia do mês, extrair um componente de um valor de data/hora ou converter um valor em um formato diferente.

Suporte a datas

O Designer não pode processar datas anteriores a 1º de janeiro de 1400.

O Alteryx usa o formato ISO yyyy-mm-dd HH:MM:SS para representar datas e horas. Se um valor de data e hora não estiver nesse formato, ele será lido como uma cadeia de caracteres. Para converter uma coluna para uso e manipulação no formato DateTime, utilize a função DateTimeParse no editor de expressões ou a ferramenta Data e Hora.

Algumas funções de data e hora exigem que você defina qual é o formato da data. As cadeias de formato são compostas por especificadores e separadores.

Especificadores

Os especificadores sempre começam com um sinal de porcentagem (%) seguido por uma letra (há diferenciação entre maiúsculas e minúsculas). Os dados devem incluir pelo menos um ano de dois dígitos.

Especificador Saída de DateTimeFormat Entradas compatíveis com DateTimeParse
%a Nome abreviado do dia da semana (“Seg”) Qualquer abreviação válida de um dia da semana ("seg", "Ter.", "Qui"), gerando um erro somente se o texto fornecido não for um dia da semana. Observe que o Alteryx não verifica se o nome do dia especificado é válido para uma determinada data.
%A Nome completo do dia da semana (“Segunda-feira”) O nome completo de um dia da semana ou qualquer abreviação válida ("seg", "Ter.", "Qui"), gerando um erro somente se o texto fornecido não for um dia da semana. Observe que o Alteryx não verifica se o nome do dia especificado é válido para uma determinada data.
%b Nome abreviado do mês (“Set”) Qualquer abreviação válida do nome de um mês ("Set", "SET."), gerando um erro somente se o texto fornecido não for o nome de um mês.
%B Nome completo do mês (“Setembro”) O nome de um mês ou qualquer abreviação válida ("Set", "SET."), gerando um erro somente se o texto fornecido não for o nome de um mês.
%c A data e a hora da localidade do computador. Sem suporte
%C O número do século (“20”) Sem suporte
%d Dia do mês (“01”) Um ou dois dígitos, ignorando espaços (“1” ou “01”).
%D Equivalente a %m/%d/%y Sem suporte
%e Dia do mês, com o 0 à esquerda substituído por um espaço (“ 1”). Um ou dois dígitos, ignorando espaços (“1” ou “01”).
%h O mesmo que %b (“Set”) Qualquer abreviação válida do nome de um mês ("Set", "SET."), gerando um erro somente se o texto fornecido não for o nome de um mês.
%H Hora no relógio de 24 horas, de 00 a 23. Até dois dígitos para a hora, de 0 a 23. Não é compatível com %p ou %P.
%I
(letra “i” maiúscula)
Hora no relógio de 12 horas, de 01 a 12. Até dois dígitos para a hora, de 1 a 12. Deve ser seguido por %p ou %P.
%j O dia do ano, 001 a 365 (ou 366 em anos bissextos) Dia do ano com 3 dígitos, de 001 a 365 (ou 366 em anos bissextos)
%k 24 horas, o zero à esquerda é um espaço, de “ 0” a “23”. Até dois dígitos para a hora.
%l
(letra “L” minúscula)
12 horas, o zero à esquerda é um espaço, de “ 1” a “12”. Sem suporte
%M Minutos, 00 a 59 Até dois dígitos para os minutos.
%m Número do mês, de 01 a 12. Número do mês com um ou dois dígitos, de 1 ou 01 até 12.
%p "AM" ou "PM" Não diferencia maiúsculas e minúsculas ("aM" ou "Pm"). Deve vir após %I (letra "i" maiúscula, hora no formato de 12 horas).
%P "am" ou "pm" Não diferencia maiúsculas e minúsculas ("aM" ou "Pm"). Deve vir após %I (letra "i" maiúscula, hora no formato de 12 horas).
%S Segundos, 00 a 59 Até dois dígitos para os segundos.
%T Tempo em notação de 24 horas. Equivalente a %H:%M:%S Sem suporte
%u Dia da semana como um decimal de 1 a 7, com a segunda-feira sendo 1. Sem suporte
%U Retorna o número da semana, como 00 a 53, com o início das semanas sendo domingo. Sem suporte
%w Dia da semana como um número de 0 a 6, com o domingo sendo 0. Sem suporte
%W Retorna o número da semana, como 00 a 53, com o início das semanas sendo segunda-feira. Sem suporte
%x A data da localidade do computador. Sem suporte
%X Tempo como no relógio de 12 horas, incluindo AM ou PM (“11:51:02 AM”). Horas:Minutos:Segundos [AM / PM]
%y Os últimos dois dígitos do ano (“16”). Até quatro dígitos são lidos (parando em um separador ou no fim da cadeia de caracteres) e mapeados para um intervalo entre o ano atual menos 66 até o ano atual mais 33. Por exemplo, em 2016, o intervalo vai de 1950 a 2049.

Limitação com datas de seis dígitos
Como até quatro dígitos são lidos para o ano, os formatos que informam apenas dois dígitos sem um separador, como um carimbo de data de seis dígitos (por exemplo, %y%m%d, como 170522 para 22 de maio de 2017), ainda são lidos como quatro dígitos. Para contornar essa limitação, você pode...

  • Usar quatro dígitos para o ano (por exemplo, 2017 em vez de 17), dependendo do seu intervalo de datas.
  • Usar a ferramenta RegEx para inserir um espaço após os dois primeiros dígitos da cadeia de caracteres.
%Y Todos os quatro dígitos do ano (“2016”). Dois ou quatro dígitos são lidos. Dois dígitos são mapeados para um intervalo entre o ano atual menos 66 até o ano atual mais 33. Por exemplo, em 2016, o intervalo vai de 1950 a 2049.
%z Diferença do horário UTC (“-600”). Sem suporte
%Z Nome completo do fuso horário (por exemplo, “Horário Padrão de Brasília"). Sem suporte

Separadores

Os separadores são inseridos entre os especificadores de data/hora para criar uma cadeia de formato.

Separador Saída de DateTimeFormat Entradas compatíveis com DateTimeParse*
/ / / ou -
- - / ou -
espaço Um espaço Qualquer sequência de espaços em branco.
%n Uma nova linha Sem suporte
%t Uma tabulação Sem suporte
outros Outros caracteres, como vírgula, ponto final e dois-pontos. Outros caracteres, como vírgula, ponto final e dois-pontos.

*DateTimeParse aceita barras ( / ) e hífens ( - ) de maneira intercambiável. No entanto, vírgulas, dois-pontos e todos os outros separadores devem corresponder exatamente aos dados recebidos.

Parâmetros de idioma

Estes são os valores compatíveis com o parâmetro "l" (idioma), que pode ser usado com as funções DateTimeFormat e DateTimeParse.

Nome do idioma em inglês Nome do idioma na língua nativa Código do idioma
English English en
Italian Italiano it
French Français fr
German Deutsch de
Japanese 日本語 ja
Spanish Español es
Portuguese Português pt
Chinese 简体中文 zh

Além dos valores acima, valores que tenham pelo menos 2 caracteres de comprimento e que comecem como qualquer dos nomes acima também são aceitáveis. Por exemplo, eng, engl, engli etc. para o idioma inglês, ou esp, espa, sp, spa, span etc. para o espanhol.

DateTimeAdd

DateTimeAdd(dt,i,u): adiciona um intervalo específico a um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

i: número inteiro positivo ou negativo de tempo para adicionar ou subtrair.

u: unidade de data/hora, especificada entre aspas: "years" (anos), "months" (meses), "days" (dias), "hours" (horas), "minutes" (minutos) ou "seconds" (segundos).

Exemplo

DateTimeAdd(DateTimeToday(), -1, "days") retorna a data de ontem.

DateTimeAdd(DateTimeFirstOfMonth(), 1, "months") retorna o primeiro dia do próximo mês.

DateTimeAdd("2016-01-30", 1, "month") retorna 2016-02-29 (porque o mês de fevereiro não tem 30 dias e o último dia de fevereiro naquele ano é 29).

DateTimeAdd("2016-03-30", -1, "month")  retorna 2016-02-29 (porque o mês de fevereiro não tem 30 dias e o último dia de fevereiro naquele ano é 29).

Leia mais

  • Qualquer fração na duração é truncada. Por exemplo, não é possível adicionar 1,5 horas. Em vez disso, adicione 90 minutos.
  • Adicionar uma unidade não altera o valor das unidades menores. Por exemplo, a adição de horas não altera o valor dos minutos ou segundos. Adicionar meses não muda o dia ou a hora, a menos que o mês resultante não tenha esse dia. Nesse caso, vai para o último dia daquele mês.

DateTimeDay

DateTimeDay(dt): retorna o valor numérico para o dia do mês em um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeDay("2017-03-24 11:43:23") retorna 24.

DateTimeDiff

DateTimeDiff(dt1,dt2,u): subtrai o segundo argumento do primeiro e retorna a diferença entre eles como um número inteiro na unidade especificada. A duração é retornada como um número inteiro, não como uma cadeia de caracteres, nas unidades de tempo especificadas.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

u: unidade de data/hora, especificada entre aspas: "years" (anos), "months" (meses), "days" (dias), "hours" (horas), "minutes" (minutos) ou "seconds" (segundos).

Exemplo

DateTimeDiff("2016-02-15 00:00:00", "2016-01-15 00:00:01", "Months") retorna 1 (porque a data inicial e final estão no mesmo dia do mês).

DateTimeDiff("2012-02-29","2011-03-01","years") retorna 0 (porque apesar de 2012-02-29 ser 365 dias depois de 2011-03-01, o dia 29 de fevereiro vem antes do dia 1º de março, ou seja, entre as duas datas não se passa um ano completo).

DateTimeDiff("2016-02-14", "2016-01-15", "Months") retorna 0 (porque o dia em fevereiro é menor que o dia em janeiro, ou seja, entre as duas datas não se passa um mês completo).

DateTimeDiff("2016-02-14 23:59:59", "2016-01-15 00:00:00", "Months") retorna 0 (mesmo que falte só um segundo para atingir o dia que retornaria uma diferença de 1 mês).

DateTimeDiff('2017-02-28', '2016-02-29', 'Months') retorna 11 (mesmo que 28 seja o último dia de fevereiro em 2017, ele ainda é menor que 29).

Leia mais

  • Para diferenças de mês e ano, um mês é contado somente quando o dia final alcança o dia inicial, ignorando a hora do dia.
  • Para diferenças de dia, hora, minuto e segundo, o resultado é calculado com precisão e, em seguida, partes fracionárias são truncadas, não arredondadas. Portanto...
    DateTimeDiff(‘2016-01-01 00:59:59’, ‘2016-01-01 00:00:00’, ‘Hours’) é zero.
    DateTimeDiff(‘2016-01-01 23:59:59’, ‘2016-01-01 00:00:00’, ‘Days’) é zero.
  • Os nomes das precisões podem ser abreviados para os três primeiros caracteres (como "sec" e "min"); não há diferenciação entre maiúsculas e minúsculas.
  • Tenha cuidado ao retornar as diferenças de tempo em segundos. Dados do tipo Int32 só podem armazenar uma diferença de até 68 anos em segundos ou até 4082 anos em minutos. Você pode usar dados do tipo Double ou Int64 para armazenar os intervalos entre todas as datas compatíveis.

DateTimeFirstOfMonth

DateTimeFirstOfMonth(): retorna o primeiro dia do mês, à meia-noite.

DateTimeFormat

DateTimeFormat(dt,f,l): converte dados de data/hora do formato ISO para outro formato especificado (f) em um idioma especificado (l) para uso em outro aplicativo. A saída gerada são dados do tipo cadeia de caracteres.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

f: o formato para o qual converter os dados, expresso como uma cadeia de formato.

l: parâmetro opcional de idioma. O parâmetro de idioma é, por padrão, o idioma que você selecionou para o Designer. Por exemplo, se o Designer estiver definido para o francês, a função exibirá DateTimeParse(dt,f,"Français") por padrão. Consulte Parâmetros de idioma para obter os valores de idioma aceitos.

Exemplos

DateTimeFormat([DateTime_Out],"%d-%m-%Y") retorna 22-04-2008 para o dia 22 de abril de 2008 (formato ISO: 2008-04-22).

DateTimeFormat([DateTime_Out],"%A","Spanish") retorna “martes” para a data ISO 2020-07-14 (em que 14 de julho é terça-feira). 

DateTimeHour

DateTimeHour(dt): retorna a parte das horas de um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeHour("2017-03-24 11:43:23") retorna 11.

DateTimeHour("2017-03-24") retorna 0, porque quando não há um horário especificado nos dados, meia-noite é a hora adotada.

DateTimeLastOfMonth

DateTimeLastOfMonth(): retorna o último dia do mês atual, com o relógio definido para um segundo antes do final do dia (23:59:59).

O Designer usa a data de quando a fórmula é processada pela primeira vez. Em um processo em lotes, essa data é usada com cada novo conjunto de dados. Isso garante consistência caso o processo demore muito tempo.

DateTimeMinutes

DateTimeMinutes(dt): retorna a parte dos minutos de um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeMinutes("2017-03-24 11:43:23") retorna 43.

DateTimeMonth

DateTimeMonth(dt): retorna o valor numérico para o mês em um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeMonth("2017-03-24 11:43:23") retorna 3.

DateTimeMonth("11:43:23") retorna [Null] porque os dados recebidos não são válidos.

DateTimeNow

DateTimeNow(): retorna a data e a hora atuais do sistema.

DateTimeParse

DateTimeParse(dt,f,l): converte uma cadeia de caracteres de data com o formato especificado (f) no idioma especificado (l) para o formato padrão ISO (yyyy-mm-dd HH:MM:SS).

Parâmetros

dt: cadeia de caracteres de data/hora, expressa como um campo selecionado ou como uma cadeia de data/hora entre aspas. Os dados de entrada devem ser do tipo cadeia de caracteres e podem estar em qualquer formato de data/hora desde que esse formato coincida com o que for especificado para o parâmetro f.

f: o formato da data/hora nos dados de cadeia de caracteres que você quer converter, expresso como uma cadeia de formato entre aspas.

l (opcional): o idioma da data/hora nos dados de cadeia de caracteres que você quer converter. O parâmetro de idioma é, por padrão, o idioma que você selecionou para o Designer. Por exemplo, se o Designer estiver definido para o francês, a função exibirá DateTimeParse(dt,f,"Français") por padrão. Consulte Parâmetros de idioma para obter os valores de idioma aceitos.

Exemplos

DateTimeParse("2016/28-03","%Y/%d-%m") retorna 2016-03-28.

DateTimeParse([DateTimeNow],"%A %d %B %Y", "Français") retorna 2020-07-14 para a cadeia de caracteres de entrada “mardi 14 juillet 2020” (terça-feira, 14 de julho de 2020).

DateTimeSeconds

DateTimeSeconds(dt): retorna a parte dos segundos de um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

DateTimeStart

DateTimeStart(): retorna a data e a hora em que a execução do fluxo de trabalho atual começou.

DateTimeToday

DateTimeToday(): retorna a data de hoje.

Comportamento esperado: tipo dos dados com DateTimeToday

Apesar do nome, a função DateTimeToday() não retorna um valor de hora (Time). Em vez disso, ela retorna apenas um valor de data (Date) com a data atual. Você pode encapsular a função DateTimeToday() dentro da função ToDateTime() para retornar um valor de data e hora com o horário definido para a meia-noite do dia atual:

ToDateTime(DateTimeToday())

DateTimeToLocal

DateTimeToLocal(dt): converte uma data/hora UTC para o fuso horário local do sistema.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplos

DateTimeToLocal('2014-08-01 20:01:25') retorna o fuso horário local do sistema como 2014-08-01 14:01:25 (supondo que o sistema esteja na Hora Padrão das Montanhas).

DateTimeToUTC

DateTimeToUTC(dt): converte uma data/hora (no fuso horário local do sistema) para UTC.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeToUTC(DateTimeNow()) retorna o Tempo Universal Coordenado (UTC) na hora da execução do fluxo de trabalho, ou seja, retorna 2014-08-01 20:01:25 caso o fluxo seja executado em 2014-08-01 14:01:25 na Hora Padrão das Montanhas.

DateTimeTrim

DateTimeTrim(dt,t): remove partes indesejadas de uma data/hora e retorna a data/hora modificada.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

t: tipo de corte. As opções incluem:

  • firstofmonth: ajusta para o início do mês (faz o mesmo que “month”).
  • lastofmonth: ajusta para um segundo antes do final do último dia do mês.
  • year: ajusta para a meia-noite de 1º de janeiro.
  • month: ajusta para a meia-noite do primeiro dia do mês.
  • day: ajusta para o dia à meia-noite. Converte uma data/hora para uma data com o horário definido para zero (não somente uma data).
  • hour: ajusta para a hora.
  • minute: ajusta para o minuto.

Ao usar a função trim para cortar uma data/hora, o valor retornado não é arredondado. Por exemplo, o horário 15:59:59 ajustado para a hora (t = "hour") retorna 15:00:00, não 16:00:00.

Exemplo

DateTimeTrim("2016-12-07 16:03:00","year") retorna 2016-01-01 00:00:00.

DateTimeYear

DateTimeYear(dt): retorna o valor numérico para o ano em um valor de data/hora.

Parâmetros

dt: dados do tipo data/hora, expressos como uma coluna selecionada ou como um valor de data/hora especificado entre aspas.

Exemplo

DateTimeYear("2017-03-24 11:43:23") retorna 2017.

ToDate

ToDate(x): converte uma cadeia de caracteres, número ou data/hora em uma data.

  • Uma cadeia de caracteres de entrada deve estar formatada como yyyy-mm-dd. Por exemplo, 2020-10-31.
  • Um número de entrada deve estar formatado como um formato de data do Excel, em que o número representa o número de dias desde 01-01-1900. Por exemplo, 7000, que corresponde a 1º de março de 1919.
  • Uma data/hora de entrada deve estar formatada como yyyy-mm-dd hh:mm:ss. Por exemplo, 2020-10-31 12:00:00.

Exemplos

ToDate(2020-10-31) retorna 2020-10-31 como uma data.

ToDate(7000) retorna 1919-03-01 como uma data.

ToDate(2020-10-31 12:00:00) retorna 2020-10-31 como uma data.

ToDateTime

ToDateTime(x): converte uma cadeia de caracteres, um número ou uma data em uma data/hora.

  • Uma cadeia de caracteres de entrada deve estar formatada como yyyy-mm-dd hh:mm:ss. Por exemplo, 2020-10-31 12:00:00.
  • Um número de entrada deve estar formatado como um formato de data/hora do Excel, em que o número representa o número de dias desde 01-01-1900. Por exemplo, 7000.354167, que corresponde a 1º de março de 1919 às 08:30.
  • Uma data de entrada deve estar formatada como yyyy-mm-dd. Por exemplo, 2020-10-31.

Exemplos

ToDateTime(2020-10-31) retorna 2020-10-31 00:00:00 como uma data/hora.

ToDateTime(7000.354167) retorna 1919-03-01 08:30:00 como uma data/hora.

ToDateTime(2020-10-31 12:00:00) retorna 2020-10-31 12:00:00 como uma data/hora.

Esta página foi útil?

Problemas com seu produto Alteryx? Visite a Comunidade Alteryx ou entre em contato com nossa Equipe de Suporte. Não é possível enviar este formulário? Envie-nos um e-mail.