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

A função DATETRUNC trunca um valor de data ou hora para uma unidade de tempo especificada e retorna o valor truncado.

O truncamento difere da extração. Truncar um DATETIME para o trimestre retorna o timestamp do primeiro dia desse trimestre (por exemplo, 2024-10-01 00:00:00 ). Já a extração do trimestre com a função EXTRACT retorna o número do trimestre (por exemplo, 4 ).

Sintaxe

O DATETRUNC aceita duas assinaturas.

Assinatura 1 — para entradas DATE, DATETIME e TIMESTAMP_NTZ:

DATE|DATETIME|TIMESTAMP_NTZ DATETRUNC(DATE|DATETIME|TIMESTAMP_NTZ <date>, STRING <date_part>)

-- Returns 2025-01-01 00:00:00.
SELECT DATETRUNC(DATETIME '2025-12-07 16:28:46', 'yyyy');

Assinatura 2 — para entradas TIMESTAMP, com conversão opcional de fuso horário:

TIMESTAMP DATETRUNC(TIMESTAMP <date>, STRING <date_part>[, STRING <time_zone>])

-- The session time zone is Asia/Shanghai.
-- Returns 2025-01-01 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

A Assinatura 2 converte o TIMESTAMP para o time_zone especificado, trunca o valor e retorna o resultado no fuso horário da sessão ou do projeto.

Parâmetros

date

Obrigatório. Data ou timestamp a ser truncado. Tipos suportados: DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ.

Se o projeto MaxCompute usar a edição de tipos de dados V1.0, também será aceita uma STRING no formato DATETIME yyyy-mm-dd hh:mi:ss. A função converte implicitamente esse valor para DATETIME antes de truncá-lo.

date_part

Obrigatório. Unidade de tempo para o truncamento. Deve ser uma constante STRING.

Unidade de tempo	Valor	Comportamento do truncamento
Ano	`year` ou `yyyy`	Retorna o primeiro dia do ano; a hora é definida como `00:00:00`
Trimestre	`quarter` ou `q`	Retorna o primeiro dia do trimestre; a hora é definida como `00:00:00`
Mês	`month`, `mon` ou `mm`	Retorna o primeiro dia do mês; a hora é definida como `00:00:00`
Semana	`week` ou `week(monday)`	Retorna a segunda-feira da semana; a hora é definida como `00:00:00`
Semana (início personalizado)	`week(weekday)`	Retorna o dia da semana especificado; a hora é definida como `00:00:00`. Valores válidos: `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
Semana ISO	`isoweek`	Retorna a segunda-feira da semana ISO 8601; a hora é definida como `00:00:00`
Dia	`day` ou `dd`	Mantém a data; a hora é definida como `00:00:00`
Hora	`hour` ou `hh`	Mantém até a hora; minutos e segundos são definidos como `00:00`
Minuto	`mi`	Mantém até o minuto; os segundos são definidos como `00`
Segundo	`ss`	Mantém até o segundo; as frações de subsegundo são removidas
Milissegundo	`ff3`	Mantém a precisão até milissegundos

time_zone

Opcional. Exclusivo da Assinatura 2. STRING que especifica o fuso horário para o qual o TIMESTAMP é convertido antes do truncamento. Se omitido, usa-se o fuso horário da sessão ou do projeto.

Se o fuso horário do projeto não tiver sido alterado, o padrão será China Standard Time (UTC+08:00).

Valor de retorno

Retorna o mesmo tipo de dados de date. As seguintes condições especiais se aplicam:

Condição	Resultado
`date` não é DATE, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ	Erro
`date` é NULL	Erro
`date_part` é NULL	NULL
`date_part` não é constante, tem formato não suportado ou não é STRING	Erro

Exemplos

Exemplos básicos

Os exemplos a seguir usam a Assinatura 1 com entradas DATE, DATETIME e TIMESTAMP_NTZ.

-- Returns 2024-01-01 00:00:00.
SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'yyyy');

-- Returns 2024-12-01 00:00:00.
SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'MONTH');

-- Returns 2024-12-02.
SELECT DATETRUNC(DATE'2024-12-07', 'week(monday)');

-- Returns 2024-10-01 00:00:00.
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46', 'q');

-- Returns 2024-12-07 16:28:46.
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123', 'ss');

-- Returns 2024-12-07 16:28:46.123.
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123456', 'ff3');

-- Returns NULL.
SELECT DATETRUNC(DATE'2024-12-07', NULL);

Para comparar como diferentes valores de date_part afetam a mesma entrada, execute-os lado a lado:

SELECT
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'yyyy')    AS truncated_to_year,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'quarter')  AS truncated_to_quarter,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'month')    AS truncated_to_month,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'week')     AS truncated_to_week,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'day')      AS truncated_to_day,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'hour')     AS truncated_to_hour;

Saída:

truncated_to_year	truncated_to_quarter	truncated_to_month	truncated_to_week	truncated_to_day	truncated_to_hour
2024-01-01 00:00:00	2024-10-01 00:00:00	2024-12-01 00:00:00	2024-12-02 00:00:00	2024-12-07 00:00:00	2024-12-07 16:00:00

Exemplos com time_zone

Quando date for um TIMESTAMP, use time_zone para especificar o fuso horário em que o truncamento será aplicado. O resultado é retornado no fuso horário da sessão ou do projeto.

-- Set the session time zone to Asia/Shanghai.
SET odps.sql.timezone=Asia/Shanghai;

-- Returns 2024-01-01 00:00:00.
SELECT DATETRUNC(TIMESTAMP '2024-12-07 16:28:46', 'yyyy');

-- Returns 2025-01-01 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

-- Returns 2025-03-21 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'week(friday)', 'Asia/Jakarta');

-- Returns 2025-03-24 08:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'isoweek', 'Etc/GMT');

-- Returns 2025-11-07 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00', 'dd', 'Asia/Jakarta');

-- Returns 2025-11-07 10:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00', 'hour', 'Asia/Jakarta');

-- Returns 2025-11-07 10:30:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00', 'mi', 'Asia/Jakarta');

Entrada STRING (edição de tipos de dados V1.0)

Quando a edição de tipos de dados V1.0 está ativa, uma STRING no formato yyyy-mm-dd hh:mi:ss é convertida implicitamente para DATETIME. Strings com frações de subsegundo não correspondem ao formato e retornam NULL.

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

-- Returns NULL. The string includes milliseconds, which do not match the DATETIME format.
SELECT DATETRUNC('2025-07-27 16:28:46.123', 'mi');

-- Returns 2025-07-27 16:28:00. The string matches the DATETIME format.
SELECT DATETRUNC('2025-07-27 16:28:46', 'mi');

Funções relacionadas

DATETRUNC é uma função de data. Para ver funções de cálculo e conversão de datas, consulte Funções de data.