addDays, addToTime e datas relativas
Somam ou subtraem tempo de uma data. addDays é a mais usada para vencimentos; addToTime aceita outras unidades (semana, mês, ano) e respeita o calendário.
Sintaxe
addDays(data, dias, [formato]) addToTime(data, quantidade, unidade, [formato])
Exemplos testados
| Expressão | Resultado |
|---|---|
addDays('2026-11-02T00:00:00Z', 7, 'yyyy-MM-dd') | 2026-11-09 |
addDays('2026-11-02T00:00:00Z', -30, 'yyyy-MM-dd')valor negativo subtrai | 2026-10-03 |
addToTime('2026-11-02T00:00:00Z', 2, 'Week', 'yyyy-MM-dd') | 2026-11-16 |
addToTime('2026-01-31T00:00:00Z', 1, 'Month', 'yyyy-MM-dd')31/01 + 1 mês cai no último dia de fevereiro | 2026-02-28 |
subtractFromTime('2026-11-02T00:00:00Z', 1, 'Day', 'yyyy-MM-dd') | 2026-11-01 |
addHours('2026-11-02T00:00:00Z', 5, 'HH:mm') | 05:00 |
startOfMonth('2026-11-15T10:00:00Z', 'yyyy-MM-dd') | 2026-11-01 |
startOfDay('2026-11-02T15:30:00Z', 'HH:mm') | 00:00 |
dayOfWeek('2026-11-02T00:00:00Z')0 = domingo, 1 = segunda | 1 |
dayOfMonth('2026-11-02T00:00:00Z') | 2 |
dateDifference('2026-11-02T00:00:00Z', '2026-11-05T12:00:00Z')3 dias e 12 horas | 3.12:00:00 |
Quando usar
Use addDays para prazos simples (vencimento em 7 dias, lembrete 3 dias antes com valor negativo) e addToTime quando a unidade for semana, mês ou ano e o calendário importar: o mesmo dia do mês seguinte, o fim de um trimestre. Use startOfMonth e startOfDay para zerar a parte que não interessa antes de comparar, e dayOfWeek para decidir o que fazer em fins de semana (0 é domingo e 6 é sábado). Para saber quanto tempo passou entre dois instantes, use dateDifference, que devolve dias, horas, minutos e segundos em um único texto. Lembre que todos trabalham em UTC, a menos que você converta o fuso.
Armadilhas
- Parcelas de 30 em 30 dias derivam do calendário: a partir de 02/11/2026, as datas são 2026-12-02, 2027-01-01 e 2027-01-31. Para o mesmo dia de cada mês, use
addToTimecom'Month'. - Fim de mês: 31/01 + 1 mês devolve 28/02 (e não 03/03).
- Sem o formato, o resultado é um ISO longo. Informe
'yyyy-MM-dd'quando precisar só da data. - Tudo em UTC. Somar dias a uma data de Brasília exige converter o fuso antes.
Perguntas frequentes
Como obter o primeiro dia do mês?
startOfMonth(utcNow(), 'yyyy-MM-dd').
Como contar dias úteis?
Não existe função pronta; use dayOfWeek em um loop ou uma tabela de feriados.