Categorias:

Funções de data e hora

TIMESTAMPDIFF

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

Alternativa para DATEDIFF.

Sintaxe

TIMESTAMPDIFF( <date_or_time_part> , <date_or_time_expr1> , <date_or_time_expr2> )
Copy

Argumentos

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 não estar entre 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.

Retornos

Retorna um número inteiro representando a diferença de número de unidades (segundos, dias etc.) entre date_or_time_expr2 e date_or_time_expr1.

Notas de uso

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

  • date_or_time_expr1 e date_or_time_expr2 podem ser uma data, hora ou carimbo de data/hora.

  • A função oferece suporte a unidades de anos, trimestres, meses, semanas, dias, horas, minutos, segundos, milissegundos, microssegundos e nanossegundos.

  • date_or_time_part deve ser um dos valores listados em Partes de data e hora com suporte.

    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 de calendário 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 usadas para determinar o resultado e assim determinar 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, '00:00:00', '00:00:01.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.

Exemplos

Para obter um ou mais exemplos, consulte DATEDIFF. (DATEDIFF, TIMEDIFF e TIMESTAMPDIFF todos usam o mesmo formato básico).