DATEPART (Transact-SQL)

Retorna um inteiro que representa a datepart especificada da date especificada.

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

Convenções da sintaxe Transact-SQL

Sintaxe

DATEPART ( datepart , date )

Argumentos

• datepart
  É a parte de date (um valor de data ou hora) para a qual um integer será retornado. A tabela a seguir lista todos os argumentos datepart válidos. Equivalentes de variável definidos pelo usuário não são válidos.

  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 pode ser resolvida para um valor de time, date, smalldatetime, datetime, datetime2 ou datetimeoffset. date pode ser uma expressão, expressão de coluna, variável definida pelo usuário ou literal de cadeia de caracteres.

  Para evitar ambiguidade, use anos de quatro dígitos. Para obter informações sobre anos de dois dígitos, consulte Configurar a opção two digit year cutoff de configuração de servidor.

Tipo de retorno

int

Valor de retorno

Cada datepart e suas abreviações retornam o mesmo valor.

O valor do retorno depende do ambiente de idioma definido usando SET LANGUAGE e do Configurar opção default language de configuração de servidor do logon. Se date for uma literal de cadeia de caracteres para alguns formatos, o valor de retorno dependerá do formato especificado usando SET DATEFORMAT. SET DATEFORMAT não afeta o valor de retorno quando a data é uma expressão de coluna de um tipo de dados de data de hora.

A tabela a seguir lista todos os argumentos datepart com valores de retorno correspondentes para a instrução SELECT DATEPART(datepart,'2007-10-30 12:15:32.1234567 +05:10'). O tipo de dados do argumento date é datetimeoffset(7). O valor de retorno nanoseconddatepart tem uma escala de 9 (0,123456700) e as últimas duas posições sempre são 00.

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

Argumentos datepart de week e weekday

Quando datepart for week (wk, ww) ou weekday (dw), o valor de retorno dependerá do valor definido usando SET DATEFIRST.

O dia 1º de janeiro de qualquer ano define o número inicial da week datepart, por exemplo: DATEPART (wk, '1 de janeiro, xxxx') = 1, onde xxxx é qualquer ano.

A tabela a seguir lista o valor de retorno de week e weekday datepart para ‘2007-04-21’ para cada argumento SET DATEFIRST. O dia 1º de Janeiro é uma segunda-feira no ano de 2007. O dia 21 de abril é um sábado do ano de 2007. SET DATEFIRST 7, domingo, é o padrão para inglês norte-americano. Reino Unido.

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 datepart de year, month e day

Os valores que são 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 de segunda-feira, 29 de dezembro de 2003 a sábado, 4 de janeiro de 2004. O número de semana mais alto em um ano pode ser 52 ou 53. Esse estilo de numeração é geralmente usado em países/regiões europeus, mas raramente em outro lugar.

O sistema de numeração em países/regiões diferentes pode não estar em conformidade com o padrão ISO. Há pelo menos seis possibilidades, conforme mostrado na tabela a seguir

Primeiro dia da semana	Primeira semana do ano contém	Semanas atribuídas duas vezes	Usado por/em
Domingo	1º de janeiro, Primeiro sábado, 1 a 7 dias do ano	Sim	Estados Unidos
Segunda-feira	1º de janeiro, Primeiro domingo, 1 a 7 dias do ano	Sim	A maior parte da Europa e do Reino Unido
Segunda-feira	4 de janeiro, Primeira quinta-feira, 4 a 7 dias do ano	Não	ISO 8601, Noruega e Suécia
Segunda-feira	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

O TZoffset (tz) é retornado como o número de minutos (assinado). A instrução a seguir retorna um deslocamento de fuso horário de 310 minutos.

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

Se o argumento for datepart TZoffset (tz) e o argumento date não for do tipo de dados datetimeoffset, NULL será retornado.

Argumento de data smalldatetime

Quando date for smalldatetime, os segundos serão retornados como 00.

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

Se o tipo de dados do argumento date não tiver o datepart especificado, o padrão desse datepart será retornado apenas quando um literal for especificado para date.

Por exemplo, o ano-mês-dia padrão para qualquer tipo de dados date é 1900-01-01. A instrução a seguir tem argumentos de parte de data para datepart, um argumento de hora para date e 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 é especificado como uma variável ou coluna da tabela e o tipo de dados para essa variável ou coluna não tem datepart especificado, o erro 9810 é retornado. O exemplo de código a seguir falha porque a parte de ano da data não é um válida para o tipo de dados time que é declarado para a variável @t.

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

Segundos fracionários

Segundos fracionários são retornados como mostrado nas seguintes instruções:

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, cláusulas WHERE, HAVING, GROUP BY e ORDER BY.

No SQL Server 2012, DATEPART converte cadeias de caracteres literais implicitamente como um tipo datetime2. Isso significa que DATEPART 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 datetime ou smalldatetime para usar o formato YDM.

Exemplos

O exemplo a seguir retorna o ano base: O ano base é útil para cálculos de data. No exemplo, a data é especificada como um número. Observe que SQL Server interpreta 0 como 1º de janeiro de 1900.

SELECT DATEPART(year, 0), DATEPART(month, 0), DATEPART(day, 0);
-- Returns: 1900    1    1 */

Consulte também

Referência

CAST e CONVERT (Transact-SQL)