TRUNC_TIME - MaxCompute: Central de Documentação do Alibaba Cloud

Sintaxe

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

-- Returns 2025-06.
SELECT TRUNC_TIME(DATETIME '2025-06-10 14:20:30', 'month');

Parâmetros

date

Obrigatório. A data ou timestamp a truncar. Tipos aceitos: DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ.

No Data type version 1.0, date também aceita um valor STRING no formato DATETIME (yyyy-mm-dd hh:mi:ss, por exemplo, 2025-07-21 00:00:00). O valor é convertido implicitamente para DATETIME antes do cálculo.

date_part

Obrigatório. A unidade de tempo para truncamento. Deve ser uma constante STRING sem distinção entre maiúsculas e minúsculas.

Valor	Trunca para	Formato de saída
`year`	O limite do ano — descarta mês, dia e hora	`yyyy`
`month`	O limite do mês — descarta dia e hora	`yyyy-mm`
`day`	O limite do dia — descarta o componente de hora	`yyyy-mm-dd`
`hour`	O limite da hora — descarta minutos e segundos	`yyyy-mm-dd hh:mm:ss`

Valor de retorno

Sempre retorna uma STRING. O formato de saída depende de date_part, conforme indicado na tabela acima.

Diferentemente de funções que preservam o tipo de entrada, a TRUNC_TIME sempre retorna uma STRING, independentemente de a entrada ser DATE, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ.

Observações de uso

Conversão de fuso horário para tipos relacionados a fuso horário

Para tipos de dados relacionados a fuso horário, como DATETIME e TIMESTAMP, a TRUNC_TIME primeiro converte a hora local para UTC, depois trunca com base em date_part e retorna o resultado como STRING. Por isso, a data de saída pode diferir da data local.

Por exemplo, DATETIME '2025-06-03 07:15:08' em UTC+8 equivale a 2025-06-02 23:15:08 em UTC. Ao truncar para day, o resultado é 2025-06-02, e não 2025-06-03.

Truncamento vs. extração

Truncamento não é o mesmo que extração. A TRUNC_TIME arredonda um timestamp para baixo até um limite de tempo e retorna uma STRING. Para extrair um componente (como o número do ano ou do mês) na forma de inteiro, utilize uma função de extração de data. Para mais informações, consulte Funções de data.

Casos de erro

Se date não for um dos tipos compatíveis (DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ), a função retorna um erro.
Se date_part for NULL, a função retorna um erro.

Exemplos

Entrada DATETIME

O fuso horário da sessão é UTC+8 (Asia/Shanghai). A entrada DATETIME '2025-06-03 07:15:08' é convertida para UTC como 2025-06-02 23:15:08 antes do truncamento.

SET odps.sql.timezone=Asia/Shanghai;

SELECT
    TRUNC_TIME(DATETIME '2025-06-03 07:15:08', 'year')  AS truncated_to_year,
    TRUNC_TIME(DATETIME '2025-06-03 07:15:08', 'month') AS truncated_to_month,
    TRUNC_TIME(DATETIME '2025-06-03 07:15:08', 'day')   AS truncated_to_day,
    TRUNC_TIME(DATETIME '2025-06-03 07:15:08', 'hour')  AS truncated_to_hour;

-- Result:
+--------------------+--------------------+--------------------+---------------------+
| truncated_to_year  | truncated_to_month | truncated_to_day   | truncated_to_hour   |
+--------------------+--------------------+--------------------+---------------------+
| 2025               | 2025-06            | 2025-06-02         | 2025-06-02 23:00:00 |
+--------------------+--------------------+--------------------+---------------------+

Entrada DATE

SELECT
    TRUNC_TIME(DATE '2025-06-10', 'year')  AS truncated_to_year,
    TRUNC_TIME(DATE '2025-06-10', 'month') AS truncated_to_month,
    TRUNC_TIME(DATE '2025-06-10', 'day')   AS truncated_to_day;

-- Result:
+--------------------+--------------------+------------------+
| truncated_to_year  | truncated_to_month | truncated_to_day |
+--------------------+--------------------+------------------+
| 2025               | 2025-06            | 2025-06-10       |
+--------------------+--------------------+------------------+

Entrada STRING (somente na edição de tipos de dados V1.0 do MaxCompute)

Para usar um valor STRING como entrada, defina a edição de tipos de dados como V1.0. A string é convertida implicitamente para DATETIME e, em seguida, convertida para UTC antes do truncamento.

-- Set the time zone to UTC+8.
SET odps.sql.timezone=Asia/Shanghai;
-- Set the data type edition to V1.0 to allow implicit STRING-to-DATETIME conversion.
SET odps.sql.type.system.odps2=false;

SELECT TRUNC_TIME('2025-06-03 15:30:30', 'hour');

-- Result (local time 15:30 UTC+8 converts to 07:00 UTC, then truncated to hour):
+---------------------+
| _c0                 |
+---------------------+
| 2025-06-03 07:00:00 |
+---------------------+

Tópicos relacionados

Para funções relacionadas de cálculo e conversão de datas, consulte Funções de data.