Categorias:: Funções de data e hora

DATEDIFF¶

Calcula a diferença entre duas expressões de data, hora ou carimbo de data/hora com base na parte de data ou hora solicitada. A função retorna o resultado da subtração do segundo argumento do terceiro argumento.

Nota

Os cálculos de diferença comparam a parte da data ou hora especificada, não a data ou hora completa. Por exemplo, a diferença de mês entre 28 de novembro de 2024 e 5 de dezembro de 2024 é 1, porque a diferença entre os dois meses de novembro e dezembro, ambos em 2024, é 1. Para refletir o fato de que a diferença entre as duas datas é menor que um mês inteiro, calcule a diferença em dias.

Também é possível usar o sinal de menos (-) para calcular a diferença entre duas datas subtraindo uma data da outra.

Para adicionar unidades de tempo a uma data, hora ou carimbo de data/hora (por exemplo, adicionar dois dias a uma data) ou subtrair unidades de tempo deles, é possível usar a função DATEADD, TIMEADD ou TIMESTAMPADD.

Consulte também:: TIMEDIFF , TIMESTAMPDIFF

Sintaxe¶

Para DATEDIFF:

DATEDIFF( <date_or_time_part>, <date_or_time_expr1>, <date_or_time_expr2> )

Copy

Para sinal de menos:

<date_expr2> - <date_expr1>

Copy

Argumentos¶

Para DATEDIFF:

date_or_time_part: A unidade de tempo. Deve ser um dos valores listados em Partes de data e hora com suporte (por exemplo, month). O valor pode ser uma cadeia de caracteres literal ou pode estar sem aspas (por exemplo, 'month' ou month).
date_or_time_expr1, date_or_time_expr2: Os valores a serem comparados. Deve ser uma data, uma hora, um carimbo de data/hora ou uma expressão que possa ser avaliada como uma data, uma hora ou um carimbo de data/hora. O valor date_or_time_expr1 é subtraído de date_or_time_expr2.

Para sinal de menos:

date_expr1, date_expr2: Os valores a serem comparados. Deve ser uma data ou uma expressão que possa ser avaliada como uma data. O valor date_expr1 é subtraído de date_expr2.

Retornos¶

Para DATEDIFF:

Retorna um inteiro que representa a diferença no número de unidades (segundos, dias e assim por diante) entre date_or_time_expr2 e date_or_time_expr1.

Retorna NULL se algum argumento for NULL.

Para sinal de menos:

Retorna um número inteiro representando o número de dias de diferença entre date_expr2 e date_expr1. (As unidades são sempre dias).

Retorna um erro se date_expr2 ou date_expr1 for NULL.

Notas de uso¶

Para ambos DATEDIFF e sinal de menos:

Os valores de saída podem ser negativos, por exemplo, -12 dias.

Para DATEDIFF:

A função oferece suporte a unidades de anos, trimestres, meses, semanas, dias, horas, minutos, segundos, milissegundos, microssegundos e nanossegundos.
Se date_or_time_part for week (ou qualquer uma de suas variações), a saída é controlada pelo parâmetro de sessão WEEK_START. Para obter mais detalhes, incluindo exemplos, consulte Semanas do ano e dias úteis.
A unidade (por exemplo, month) usada para calcular a diferença determina quais partes do campo DATE, TIME ou TIMESTAMP são avaliadas. Então, a unidade determina a precisão do resultado.

Unidades menores não são utilizadas, portanto, os valores não são arredondados. Por exemplo, mesmo que a diferença entre 1.º de janeiro de 2021 e 28 de fevereiro de 2021 esteja mais próxima de dois meses do que de um mês, o seguinte retorna um mês:
```
DATEDIFF(month, '2021-01-01'::DATE, '2021-02-28'::DATE)
```
Copy
Para um valor DATE:
- year usa apenas o ano e desconsidera todas as outras partes.
- month usa o mês e o ano.
- day usa a data inteira.
Para um valor TIME:
- hour usa apenas a hora e desconsidera todas as outras partes.
- minute usa a hora e o minuto.
- second usa a hora, minuto e segundo, mas não os segundos fracionários.
- millisecond usa a hora, minuto, segundo e os três primeiros dígitos dos segundos fracionários. Os segundos fracionários não são arredondados. Por exemplo, DATEDIFF(milliseconds, '2024-02-20 21:18:41.0000', '2024-02-20 21:18:42.1239') retorna 1.123 segundos, não 1.124 segundos.
- microsecond usa a hora, minuto, segundo e os primeiros seis dígitos dos segundos fracionários. Os segundos fracionários não são arredondados.
- nanosecond usa a hora, minuto, segundo e todos os nove dígitos dos segundos fracionários.
Para um valor TIMESTAMP:

As regras correspondem às regras para tipo de dados DATE e TIME acima. Somente a unidade especificada e unidades maiores são utilizadas.

Para sinal de menos:

date_expr1 e date_expr2 devem ser ambos datas. Não são permitidos carimbos de data/hora e horas.

Exemplos¶

Calcular a diferença em anos entre dois carimbos de data/hora:

SELECT DATEDIFF(year, 
                '2020-04-09 14:39:20'::TIMESTAMP, 
                '2023-05-08 23:39:20'::TIMESTAMP) 
  AS diff_years;

Copy

+------------+
| DIFF_YEARS |
|------------|
|          3 |
+------------+

Calcular a diferença em horas entre dois carimbos de data/hora:

SELECT DATEDIFF(hour, 
               '2023-05-08T23:39:20.123-07:00'::TIMESTAMP, 
               DATEADD(year, 2, ('2023-05-08T23:39:20.123-07:00')::TIMESTAMP)) 
  AS diff_hours;

Copy

+------------+
| DIFF_HOURS |
|------------|
|      17544 |
+------------+

Demonstrar como as partes da data afetam os cálculos de DATEDIFF; também, demonstrar o uso do sinal de menos para subtração de data:

SELECT column1 date_1, column2 date_2,
       DATEDIFF(year, column1, column2) diff_years,
       DATEDIFF(month, column1, column2) diff_months,
       DATEDIFF(day, column1, column2) diff_days,
       column2::DATE - column1::DATE AS diff_days_via_minus
  FROM VALUES
       ('2015-12-30', '2015-12-31'),
       ('2015-12-31', '2016-01-01'),
       ('2016-01-01', '2017-12-31'),
       ('2016-08-23', '2016-09-07');

Copy

+------------+------------+------------+-------------+-----------+---------------------+
| DATE_1     | DATE_2     | DIFF_YEARS | DIFF_MONTHS | DIFF_DAYS | DIFF_DAYS_VIA_MINUS |
|------------+------------+------------+-------------+-----------+---------------------|
| 2015-12-30 | 2015-12-31 |          0 |           0 |         1 |                   1 |
| 2015-12-31 | 2016-01-01 |          1 |           1 |         1 |                   1 |
| 2016-01-01 | 2017-12-31 |          1 |          23 |       730 |                 730 |
| 2016-08-23 | 2016-09-07 |          0 |           1 |        15 |                  15 |
+------------+------------+------------+-------------+-----------+---------------------+

Demonstrar como as partes de tempo afetam os cálculos de DATEDIFF:

ALTER SESSION SET TIMESTAMP_NTZ_OUTPUT_FORMAT = 'DY, DD MON YYYY HH24:MI:SS';

Copy

SELECT column1 timestamp_1, column2 timestamp_2,
       DATEDIFF(hour, column1, column2) diff_hours,
       DATEDIFF(minute, column1, column2) diff_minutes,
       DATEDIFF(second, column1, column2) diff_seconds
  FROM VALUES
       ('2016-01-01 01:59:59'::TIMESTAMP, '2016-01-01 02:00:00'::TIMESTAMP),
       ('2016-01-01 01:00:00'::TIMESTAMP, '2016-01-01 01:59:00'::TIMESTAMP),
       ('2016-01-01 01:00:59'::TIMESTAMP, '2016-01-01 02:00:00'::TIMESTAMP);

Copy

+---------------------------+---------------------------+------------+--------------+--------------+
| TIMESTAMP_1               | TIMESTAMP_2               | DIFF_HOURS | DIFF_MINUTES | DIFF_SECONDS |
|---------------------------+---------------------------+------------+--------------+--------------|
| Fri, 01 Jan 2016 01:59:59 | Fri, 01 Jan 2016 02:00:00 |          1 |            1 |            1 |
| Fri, 01 Jan 2016 01:00:00 | Fri, 01 Jan 2016 01:59:00 |          0 |           59 |         3540 |
| Fri, 01 Jan 2016 01:00:59 | Fri, 01 Jan 2016 02:00:00 |          1 |           60 |         3541 |
+---------------------------+---------------------------+------------+--------------+--------------+

Use a função CURRENT_TIMESTAMP com a função DATEDIFF para calcular a diferença em anos, meses e dias entre um carimbo de data/hora especificado e o carimbo de data/hora atual:

SELECT column1 specified_timestamp,
       column2 timestamp_now,
       DATEDIFF(year, column1, column2) diff_years,
       DATEDIFF(month, column1, column2) diff_months,
       DATEDIFF(day, column1, column2) diff_days,
       column2::DATE - column1::DATE AS diff_days_via_minus
  FROM VALUES
    ('2012-08-23 09:00:00.000 -0700', CURRENT_TIMESTAMP);

Copy

+-------------------------------+-------------------------------+------------+-------------+-----------+---------------------+
| SPECIFIED_TIMESTAMP           | TIMESTAMP_NOW                 | DIFF_YEARS | DIFF_MONTHS | DIFF_DAYS | DIFF_DAYS_VIA_MINUS |
|-------------------------------+-------------------------------+------------+-------------+-----------+---------------------|
| 2012-08-23 09:00:00.000 -0700 | 2024-09-04 17:21:12.189 -0700 |         12 |         145 |      4395 |                4395 |
+-------------------------------+-------------------------------+------------+-------------+-----------+---------------------+