Formato do comando DATEDIFF, parâmetros e valor de retorno - MaxCompute: Central de Documentação do Alibaba Cloud

Retorna a diferença entre end_date e start_date (end_date - start_date), expressa na unidade especificada por date_part.

Por padrão, a função DATEDIFF conta o número de limites de date_part cruzados entre os dois timestamps, e não o tempo total decorrido. Por exemplo, DATE '2025-01-01' e DATE '2024-12-31' diferem em 1 ano e 1 mês , pois há cruzamento tanto de um limite de ano quanto de mês. Para medir o tempo decorrido com mais precisão, use uma granularidade menor para date_part , como 'day' ou 'hour' .

Sintaxe

BIGINT | INT DATEDIFF(STRING|DATE|DATETIME|TIMESTAMP|TIMESTAMP_NTZ <end_date>, STRING|DATE|DATETIME|TIMESTAMP|TIMESTAMP_NTZ <start_date>[, STRING <date_part>])

-- Returns 1.
SELECT DATEDIFF(DATE '2025-03-02', DATE '2025-03-01', 'dd');

Parâmetros

end_date, start_date

Obrigatórios. Tipos suportados: STRING, DATE, DATETIME, TIMESTAMP e TIMESTAMP_NTZ.

O cálculo do resultado segue a fórmula end_date - start_date. A função retorna um valor negativo se end_date for anterior a start_date.

Se a entrada for uma STRING, o comportamento dependerá do formato da string e da edição de tipo de dados do MaxCompute:

Formato DATE (yyyy-mm-dd, por exemplo, 2025-07-21): date_part não é suportado nas edições de tipo de dados 1.0 e 2.0.
Formato DATETIME (yyyy-mm-dd hh:mi:ss, por exemplo, 2025-07-21 00:00:00):
- Edição de tipo de dados 1.0: ocorre conversão implícita para DATETIME e há suporte a date_part.
- Edição de tipo de dados 2.0: não há suporte a conversão implícita nem a date_part.

date_part

Opcional. STRING que especifica a unidade de tempo do valor de retorno. O padrão é day quando omitido.

Unidade de tempo	Valor
Ano	`year` ou `yyyy`
Mês	`month`, `mon` ou `mm`
Semana	`week` (inicia na segunda-feira; equivalente a `week(monday)`) ou `week(weekday)`, onde `weekday` assume um dos valores: `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
Semana ISO	`isoweek` — usa limites de semana ISO 8601; inicia na segunda-feira
Dia	`day` ou `dd`
Hora	`hour` ou `hh`
Minuto	`mi`
Segundo	`ss`
Milissegundo	`ff3`
Microssegundo	`ff6`

Valor de retorno

Retorna BIGINT se date_part for especificado; caso contrário, retorna INT.

Aplicam-se os seguintes casos especiais:

Valor negativo se end_date for anterior a start_date.
NULL se end_date, start_date ou date_part for NULL.
Erro se end_date ou start_date não for um valor STRING, DATE, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ.

Comportamento de cálculo e modo de compatibilidade com BigQuery

O método de cálculo varia conforme a ativação do modo de compatibilidade com BigQuery. Essa regra aplica-se apenas quando a entrada não é do tipo TIMESTAMP_NTZ.

date_part	Modo padrão	Modo de compatibilidade com BigQuery (SET odps.sql.bigquery.compatible=true;)
`year`, `month`, `week`, `isoweek`	Trunca ambos os valores para a unidade `date_part` e conta a diferença de limites	Idêntico ao padrão: trunca primeiro e depois conta a diferença de limites
`day`, `hour`, `mi`, `ss`, `ff3`, `ff6`	Trunca ambos os valores para a unidade `date_part` e conta a diferença de limites	Calcula a diferença total decorrida e converte para a unidade `date_part`

Exemplo: Diferença entre TIMESTAMP '2025-01-01 00:00:00' e TIMESTAMP '2024-12-31 23:59:59':

Modo padrão: 0 dias, 0 horas (após truncamento para dia/hora, ambos os timestamps pertencem à mesma unidade).
Modo de compatibilidade com BigQuery: 0 dias, 0 horas (tempo total decorrido de 1 segundo; inferior a 1 dia ou 1 hora).

Para year e month, ambos os modos retornam o mesmo resultado: a comparação entre DATE '2025-01-01' e DATE '2024-12-31' resulta em 1 ano e 1 mês (cruzamento de um limite de ano e de mês).

Exemplos

Exemplos básicos

Calcule a diferença em dias:

-- Returns 1.
SELECT DATEDIFF(DATE '2025-03-02', DATE '2025-03-01', 'dd');

Calcule a diferença em horas:

-- Returns 4.
SELECT DATEDIFF(CAST('2023-10-26 14:00:00' AS DATETIME), CAST('2023-10-26 10:00:00' AS DATETIME), 'hh');

Calcule a diferença em microssegundos quando end_date for anterior a start_date:

-- Returns -86400000000.
SELECT DATEDIFF(DATE '2025-03-01', DATE '2025-03-02', 'ff6');

Calcule a diferença em semanas, com a semana iniciando na sexta-feira:

-- Returns 13.
SELECT DATEDIFF(DATETIME '2025-07-01 00:00:00', DATETIME '2025-03-28 01:30:09', 'week(friday)');

Calcule a diferença em semanas ISO:

-- Returns 20.
SELECT DATEDIFF(TIMESTAMP_NTZ '2025-06-07 10:30:00.123', TIMESTAMP_NTZ '2025-01-15 00:30:45.123456', 'isoweek');

Modo padrão versus modo de compatibilidade com BigQuery

O exemplo a seguir mostra como a mesma consulta retorna resultados diferentes dependendo da ativação do modo de compatibilidade com BigQuery. Os dois valores TIMESTAMP têm uma diferença de 4 minutos e 55 segundos.

-- Default mode: truncates both timestamps to the minute before calculating.
-- 10:05:05 truncates to 10:05; 10:00:10 truncates to 10:00. Difference = 5 minutes.
-- Returns 5.
SELECT DATEDIFF(CAST('2024-11-01 10:05:05' AS TIMESTAMP), CAST('2024-11-01 10:00:10' AS TIMESTAMP), 'mi') AS diff_in_minute1;

-- BigQuery compatibility mode: calculates total elapsed seconds, then converts to minutes.
-- 4 minutes 55 seconds = 295 seconds. Floor(295 / 60) = 4 minutes.
-- Returns 4.
SET odps.sql.bigquery.compatible=true;
SELECT DATEDIFF(CAST('2024-11-01 10:05:05' AS TIMESTAMP), CAST('2024-11-01 10:00:10' AS TIMESTAMP), 'mi') AS diff_in_minute1;

Entrada STRING

Quando end_date e start_date são valores STRING, o comportamento depende do formato da string e da edição de tipo de dados do MaxCompute.

Strings no formato DATE (yyyy-mm-dd)

Não há suporte a date_part independentemente da edição de tipo de dados. Especificar date_part retorna NULL (edição 1.0) ou erro (edição 2.0).

Na edição de tipo de dados 1.0 do MaxCompute:

-- Set the data type edition to 1.0.
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- Incorrect: date_part is specified. NULL is returned.
SELECT DATEDIFF('2025-07-01', '2025-06-28', 'day');

-- Correct: date_part is omitted. Defaults to day.
SELECT DATEDIFF('2025-07-01', '2025-06-28');
-- Result:
+------+
| _c0  |
+------+
| 3    |
+------+

Na edição de tipo de dados 2.0 do MaxCompute:

-- Set the data type edition to 2.0.
SET odps.sql.type.system.odps2=true;

-- Incorrect: date_part is specified. An error is returned.
SELECT DATEDIFF('2025-07-01', '2025-06-28', 'day');

-- Correct: date_part is omitted. Defaults to day.
SELECT DATEDIFF('2025-07-01', '2025-06-28');
-- Result:
+------+
| _c0  |
+------+
| 3    |
+------+

Strings no formato DATETIME (yyyy-mm-dd hh:mi:ss)

Na edição de tipo de dados 1.0 do MaxCompute, a string passa por conversão implícita para DATETIME e há suporte a date_part:

-- Set the data type edition to 1.0.
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- Correct: string in DATETIME format; date_part is supported.
SELECT DATEDIFF('2025-07-01 00:21:00', '2025-03-28 01:30:09', 'hour');
-- Result:
+------------+
| _c0        |
+------------+
| 2279       |
+------------+

Na edição de tipo de dados 2.0 do MaxCompute, não há suporte a conversão implícita nem a date_part. O cálculo da diferença usa dias por padrão:

-- Set the data type edition to 2.0.
SET odps.sql.type.system.odps2=true;
SET odps.sql.hive.compatible=false;

-- Incorrect: date_part is specified. An error is returned.
SELECT DATEDIFF('2025-07-01 00:21:00', '2025-03-28 01:30:09', 'hour');

-- Correct: date_part is omitted. Difference is calculated in days.
SELECT DATEDIFF('2025-07-01 00:21:00', '2025-03-28 01:30:09');
-- Result:
+------------+
| _c0        |
+------------+
| 95         |
+------------+

Funções relacionadas

DATEDIFF é uma função de data. Para mais informações sobre funções de cálculo e conversão de datas, consulte Funções de data.