DATEPART (Transact-SQL)

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Analytics Platform System (PDW)

Essa função retorna um inteiro que representa o datepart especificado do argumento date especificado.

Confira Funções e tipos de dados de data e hora (Transact-SQL) para ter uma visão geral de todas as funções e tipos de dados de data e hora do Transact-SQL.

Convenções de sintaxe de Transact-SQL

Sintaxe

DATEPART ( datepart , date )  

Argumentos

datepart
A parte específica do argumento date para o qual DATEPART retornará um inteiro. Esta tabela lista todos os argumentos datepart válidos.

date
Uma expressão que é resolvida para um dos seguintes tipos de dados:

• date
• datetime
• datetimeoffset
• datetime2
• smalldatetime
• time

Para date, DATEPART aceitará uma variável de expressão de coluna, de expressão, de literal de cadeia de caracteres ou definida pelo usuário. Para evitar ambiguidade, use anos de quatro dígitos. Consulte Configurar a opção two digit year cutoff de configuração de servidor para obter informações sobre anos de dois dígitos.

Tipo de retorno

INT

Valor retornado

Cada datepart retorna o mesmo valor das abreviações dela.

O valor retornado depende do ambiente de idioma definido por meio da instrução SET LANGUAGE e por Configurar a opção de configuração do servidor de idioma padrão do logon. O valor retornado depende de SET DATEFORMAT se date é uma literal de cadeia de caracteres de alguns formatos. SET DATEFORMAT não altera o valor retornado quando a data é uma expressão de coluna de um tipo de dados de data ou de hora.

Esta tabela lista todos os argumentos datepart com valores retornados correspondentes para a instrução SELECT DATEPART(datepart,'2007-10-30 12:15:32.1234567 +05:10'). O argumento date tem um tipo de dados datetimeoffset(7) . As duas últimas posições do valor retornado nanosecond datepart são sempre 00 e esse valor tem uma escala de 9:

.123456700

Argumentos week e weekday de datepart

Quando datepart é week (wk, ww) ou weekday (dw), o valor retornado DATEPART depende do valor definido usando SET DATEFIRST.

O dia 1º de janeiro de qualquer ano define o número inicial para week datepart. Por exemplo:

DATEPART (wk, 'Jan 1, xxxx') = 1

em que xxxx é qualquer ano.

Esta tabela lista o valor retornado por week e weekday datepart para '2007-04-21' para cada argumento SET DATEFIRST. 1º de janeiro de 2007 cai em uma segunda-feira. 21 de abril de 2007 cai em um sábado. Para o Inglês (Estados Unidos),

SET DATEFIRST 7 -- ( Sunday )

funciona como o padrão. Depois de definir DATEFIRST, use essa instrução SQL sugerida para os valores da tabela datepart:

SELECT DATEPART(week, '2007-04-21 '), DATEPART(weekday, '2007-04-21 ')

Argumentos year, month e day de datepart

Os valores retornados para DATEPART (year, date), DATEPART (month, date) e DATEPART (day, date) são iguais aos retornados pelas funções YEAR, MONTH e DAY, respectivamente.

iso_week datepart

O ISO 8601 inclui o sistema de data de semana ISO, um sistema de numeração para semanas. Cada semana está associada ao ano em que ocorre a quinta-feira. Por exemplo, a semana 1 de 2004 (2004W01) vai da segunda-feira 29 de dezembro de 2003 ao sábado 4 de janeiro de 2004. Países/regiões da Europa normalmente usam esse estilo de numeração. Países/regiões não europeus normalmente não o usam.

Observação: o maior número de semana em um ano pode ser 52 ou 53.

Os sistemas de numeração em países/regiões diferentes podem não estar em conformidade com o padrão ISO. Esta tabela mostra seis possibilidades:

tzoffset

DATEPART retorna o valor tzoffset (tz) como o número de minutos (com sinal). Esta instrução retorna uma diferença de fuso horário de 310 minutos:

SELECT DATEPART (tzoffset, '2007-05-10  00:00:01.1234567 +05:10');  

DATEPART renderiza o valor de tzoffset da seguinte maneira:

• Para datetimeoffset e datetime2 e, tzoffset retorna a diferença de tempo em minutos, em que a diferença para datetime2 é sempre de 0 minuto.
• Para tipos de dados que podem ser convertidos implicitamente em datetimeoffset ou datetime2, DATEPART retorna a diferença de tempo em minutos. Exceção: outros tipos de dados de data/hora.
• Parâmetros de todos os outros tipos resultam em erro.

Argumento smalldatetime de date

Para um valor smalldatetime date, DATEPART retorna os segundos como 00.

Padrão retornado para um datepart que não está em um argumento de data

Se o tipo de dados do argumento date não tiver a datepart especificada, DATEPART retornará o padrão para essa datepart apenas quando um literal for especificado para date.

Por exemplo, o ano-mês-dia padrão para qualquer tipo de dados de date é 1900-01-01. Esta instrução tem argumentos de parte de data para datepart, um argumento de hora para date e ela retorna 1900, 1, 1, 1, 2.

SELECT DATEPART(year, '12:10:30.123')  
    ,DATEPART(month, '12:10:30.123')  
    ,DATEPART(day, '12:10:30.123')  
    ,DATEPART(dayofyear, '12:10:30.123')  
    ,DATEPART(weekday, '12:10:30.123');  

Se date é especificada como uma variável ou coluna de tabela, e o tipo de dados dessa variável ou coluna não tem a datepart especificada, DATEPART retorna o erro 9810. Neste exemplo, a variável @t tem um tipo de dados time. O exemplo falha porque o ano da parte de data é inválido para o tipo de dados time:

DECLARE @t time = '12:10:30.123';   
SELECT DATEPART(year, @t);  

Frações de segundo

Estas instruções mostram que DATEPART retorna frações de segundos:

SELECT DATEPART(millisecond, '00:00:01.1234567'); -- Returns 123  
SELECT DATEPART(microsecond, '00:00:01.1234567'); -- Returns 123456  
SELECT DATEPART(nanosecond,  '00:00:01.1234567'); -- Returns 123456700  

Comentários

DATEPART pode ser usado na lista de seleção e nas cláusulas WHERE, HAVING, GROUP BY e ORDER BY.

DATEPART converte implicitamente literais de cadeia de caracteres como um tipo datetime2 no SQL Server 2008 (10.0.x) e versões posteriores. Isso significa que DATENAME não oferece suporte ao formato YDM quando a data é transmitida como cadeia de caracteres. É necessário converter explicitamente a cadeia de caracteres em um tipo de datetime ou smalldatetime para usar o formato YDM.

Exemplos

Este exemplo retorna o ano base. O ano base ajuda com cálculos de data. No exemplo, um número especifica a data. Note que o SQL Server interpreta 0 como 1º de janeiro de 1900.

SELECT DATEPART(year, 0), DATEPART(month, 0), DATEPART(day, 0);  

-- Returns: 1900    1    1 

Este exemplo retorna a parte do dia da data 12/20/1974.

-- Uses AdventureWorks  
  
SELECT TOP(1) DATEPART (day,'12/20/1974') FROM dbo.DimCustomer;  

-- Returns: 20

Este exemplo retorna a parte do ano da data 12/20/1974.

-- Uses AdventureWorks  
  
SELECT TOP(1) DATEPART (year,'12/20/1974') FROM dbo.DimCustomer;  

-- Returns: 1974

Confira também

CAST e CONVERT (Transact-SQL)DATETRUNC