A função ISOYEAR extrai o ano conforme a norma ISO 8601 de uma data especificada.
Introdução à ISO 8601
O ano ISO segue o sistema de data por semana da ISO, que difere do ano do calendário gregoriano. O primeiro dia de um ano ISO é a segunda-feira da semana que contém 4 de janeiro — ou seja, a segunda-feira da semana que inclui a primeira quinta-feira daquele ano.
Caso 1º de janeiro caia em uma sexta-feira, sábado ou domingo, essa semana pertence à última semana do ano ISO anterior.
Quando 1º de janeiro ocorre em uma segunda, terça, quarta ou quinta-feira, a semana integra a primeira semana do novo ano ISO.
Por isso, um ano ISO sempre abrange exatamente 52 ou 53 semanas completas, mas seus limites podem se estender ao ano adjacente do calendário gregoriano.
Para garantir consistência em relatórios semanais, utilize ISOYEAR em conjunto com funções de semana ISO. O uso isolado de ISOYEAR com uma função de semana gregoriana pode gerar valores incompatíveis de ano e semana nas transições entre anos.
Sintaxe
INT ISOYEAR(STRING|DATE|DATETIME|TIMESTAMP|TIMESTAMP_NTZ|INTERVAL <date>)
-- Returns 2025.
SELECT ISOYEAR(DATE '2025-03-12');Parâmetros
date: Obrigatório. A data da qual se deseja extrair o ano ISO. Tipos de dados suportados: DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ, STRING e INTERVAL.
STRING: O valor deve estar no formato
yyyy-mm-ddouyyyy-mm-dd hh:mi:ss.INTERVAL: Apenas INTERVAL_YEAR_MONTH é suportado. INTERVAL_DAY_TIME não é aceito. Para mais detalhes, consulte Tipo de dado INTERVAL.
Valor de retorno
Retorna um valor INT.
Se
datefor NULL, o resultado será NULL.Quando
datepossui um tipo não suportado ou formato inválido, a função retorna NULL ou gera um erro.
Exemplos
Exemplo 1: Extrair o ano ISO de diferentes tipos de data
-- Enable MaxCompute V2.0 data types.
SET odps.sql.type.system.odps2 = true;
-- STRING input. Strings in standard date formats are supported.
-- Returns 2025.
SELECT ISOYEAR('2025-03-12 12:22:00.123');
-- TIMESTAMP input.
-- Returns 2025.
SELECT ISOYEAR(TIMESTAMP '2025-03-31 12:43:00');
-- DATE input.
-- Returns 2025.
SELECT ISOYEAR(DATE '2025-01-01');
-- DATETIME input.
-- Returns 2024.
SELECT ISOYEAR(DATETIME '2024-01-01 12:30:00');
-- TIMESTAMP_NTZ (timestamp without time zone) input. Microsecond precision is supported.
-- Returns 2025.
SELECT ISOYEAR(TIMESTAMP_NTZ '2025-06-06 12:43:00.123');Exemplo 2: Usar INTERVAL_YEAR_MONTH como entrada
-- Enable MaxCompute V2.0 data types.
SET odps.sql.type.system.odps2 = true;
-- An interval of 1 year and 2 months. The year component is 1.
-- Returns 1.
SELECT ISOYEAR(INTERVAL '1-2' YEAR TO MONTH);
-- INTERVAL '14' MONTH is equivalent to INTERVAL '1-2' YEAR TO MONTH.
-- Returns 1.
SELECT ISOYEAR(INTERVAL '14' MONTH);Exemplo 3: Extrair o ano ISO do resultado de uma operação aritmética de datas
Cada exemplo adiciona um INTERVAL a uma data base e extrai o ano ISO do resultado obtido.
-- Enable MaxCompute V2.0 data types.
SET odps.sql.type.system.odps2 = true;
-- 2023-01-01 + 1 year 2 months = 2024-03-01, which is in ISO year 2024.
-- Returns 2024.
SELECT ISOYEAR(DATE '2023-01-01' + INTERVAL '1-2' YEAR TO MONTH);
-- 2023-01-01 - 9 years = 2014-01-01, a Wednesday in the first week of ISO year 2014.
-- Returns 2014.
SELECT ISOYEAR(DATE '2023-01-01' + INTERVAL '-9' YEAR);
-- 2023-01-01 + 11 months = 2023-12-01, which is in ISO year 2023.
-- Returns 2023.
SELECT ISOYEAR(DATE '2023-01-01' + INTERVAL '11' MONTH);Exemplo 4: Ano ISO nos limites de fim de ano
Os exemplos a seguir demonstram como os limites do ano civil se mapeiam para anos ISO. Duas datas separadas por apenas um dia podem pertencer a anos ISO distintos.
-- Enable MaxCompute V2.0 data types.
SET odps.sql.type.system.odps2 = true;
-- January 1, 2023 is a Sunday — it belongs to the last week of ISO year 2022.
-- Returns 2022.
SELECT ISOYEAR(DATETIME '2023-01-01 12:30:00');
-- December 30, 2024 is a Monday — it belongs to the first week of ISO year 2025.
-- Returns 2025.
SELECT ISOYEAR('2024-12-30');
-- January 1, 2025 is a Wednesday — it belongs to the first week of ISO year 2025.
-- Returns 2025.
SELECT ISOYEAR('2025-01-01 00:00:00');Contraste de limites: 2006-01-01 (domingo) retorna o ano ISO 2005, enquanto 2006-01-02 (segunda-feira) resulta no ano ISO 2006. A diferença de um único dia cruza o limite do ano ISO.
Exemplo 5: Tratar entrada NULL
-- Returns NULL.
SELECT ISOYEAR(NULL);Funções relacionadas
ISOYEAR é uma função de data. Para outras funções de cálculo e conversão de datas, consulte Funções de data.