MaxCompute:TRUNC_TIME

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. Data ou timestamp a truncar. Tipos aceitos: DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ.

Na edição de tipos de dados do MaxCompute V1.0, o parâmetro date também aceita um valor STRING no formato DATETIME (por exemplo, yyyy-mm-dd hh:mi:ss, como 2025-07-21 00:00:00). O sistema converte esse valor implicitamente para DATETIME antes do cálculo.

date_part

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

Valor de retorno

Sempre retorna uma STRING. O formato de saída depende de date_part, conforme a 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.

Notas de uso

Conversão de fuso horário para tipos sensíveis a fuso

Para tipos de dados sensíveis a fuso horário, como DATETIME e TIMESTAMP, a TRUNC_TIME primeiro converte a hora local para UTC. Em seguida, 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 corresponde 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 versus extração

Truncamento difere de 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) como inteiro, use 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 suportados (DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ), a função retornará um erro.

• Caso date_part seja NULL, a função retornará um erro.

Exemplos

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 |
+--------------------+--------------------+--------------------+---------------------+

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       |
+--------------------+--------------------+------------------+

-- 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.