DATEPART (Transact-SQL)

Aplica-se a: simSQL Server (todas as versões compatíveis) SimBanco de Dados SQL do Azure SimInstância Gerenciada do Azure SQL simAzure Synapse Analytics simParallel Data Warehouse

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

Consulte Tipos de dados e funções de data e hora (Transact-SQL) para obter uma visão geral de todos os tipos de dados e funções de data e hora do Transact-SQL.

Ícone de link do tópico Convenções da sintaxe Transact-SQL

Sintaxe

DATEPART ( datepart , date )  

Observação

Para ver a sintaxe do Transact-SQL para o SQL Server 2014 e versões anteriores, confira a Documentação das versões anteriores.

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.

Observação

DATEPART não aceita os equivalentes de variável definidos pelo usuário para os argumentos datepart.

datepart Abreviações
year yy, yyyy
quarter qq, q
month mm, m
dayofyear dy, y
day dd, d
week wk, ww
weekday dw
hour hh
minute mi, n
second ss, s
millisecond ms
microsecond mcs
nanosecond ns
tzoffset tz
iso_week isowk, isoww

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

datepart Valor retornado
year, yyyy, yy 2007
quarter, qq, q 4
month, mm, m 10
dayofyear, dy, y 303
day, dd, d 30
week, wk, ww 44
weekday, dw 3
hour, hh 12
minute, n 15
second, ss, s 32
millisecond, ms 123
microsecond, mcs 123456
nanosecond, ns 123456700
tzoffset, tz 310
iso_week, isowk, isoww 44

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, xxx x') = 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 ')

SET DATEFIRST

argumento
week

retornado
weekday

retornado
1 16 6
2 17 5
3 17 4
4 17 3
5 17 2
6 17 1
7 16 7

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:

Primeiro dia da semana Primeira semana do ano contém Semanas atribuídas duas vezes Usado por/em
Sunday 1º de janeiro,

Primeiro sábado,

1 a 7 dias do ano
Sim Estados Unidos
Monday 1º de janeiro,

Primeiro domingo,

1 a 7 dias do ano
Sim A maior parte da Europa e do Reino Unido
Monday 4 de janeiro,

Primeira quinta-feira,

4 a 7 dias do ano
Não ISO 8601, Noruega e Suécia
Monday 7 de janeiro,

Primeira segunda-feira,

7 dias do ano
Não
Quarta-feira 1º de janeiro,

Primeira terça-feira,

1 a 7 dias do ano
Sim
Sábado 1º de janeiro,

Primeira sexta-feira,

1 a 7 dias do ano
Sim

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 date

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 em SQL Server 2019 (15.x). 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)