DATEPART (Transact-SQL)

Retourne un entier qui représente la datepart précisée de la date spécifiée.

Pour obtenir une vue d'ensemble de tous les types de données et fonctions de date et d'heure Transact-SQL, consultez Types de données et fonctions de date et d'heure (Transact-SQL).

Conventions de la syntaxe Transact-SQL

Syntaxe

DATEPART ( datepart , date )

Arguments

• datepart
  Est la partie de date (une valeur de date ou d'heure) pour laquelle un integer sera retourné. Le tableau suivant répertorie tous les arguments datepart valides. Les équivalents de variables définis par l'utilisateur ne sont pas valides.

  datepart	Abréviations
  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
  Expression qui peut être résolue en une valeur time, date, smalldatetime, datetime, datetime2 ou datetimeoffset. date peut être une expression, une expression de colonne, une variable définie par l'utilisateur ou un littéral de chaîne.

  Pour éviter toute ambiguïté, représentez les années à l'aide de quatre chiffres. Pour plus d'informations sur les années à deux chiffres, consultez Configurer l'option de configuration du serveur two digit year cutoff.

Type de retour

int

Valeur de retour

Chaque datepart et ses abréviations retournent la même valeur.

La valeur de retour dépend de l'environnement de langage défini à l'aide de SET LANGUAGE et de Configurer l'option de configuration du serveur Langue par défaut pour la connexion. Si date est un littéral de chaîne pour certains formats, la valeur de retour dépend du format spécifié à l'aide de SET DATEFORMAT. SET DATEFORMAT n'affecte pas la valeur de retour lorsque la date est une expression de colonne d'un type de données de date ou d'heure.

Le tableau suivant répertorie tous les arguments datepart avec les valeurs de retour correspondantes pour l'instruction SELECT DATEPART(datepart,'2007-10-30 12:15:32.1234567 +05:10'). Le type de données de l'argument date est datetimeoffset(7). La valeur de retour nanoseconddatepart a une échelle de 9 (,123456700) et les deux dernières positions sont toujours 00.

Arguments des parties de date semaine et jour ouvrable

Lorsque datepart est week (wk, ww) ou weekday (dw), la valeur de retour dépend de la valeur qui est définie à l'aide de SET DATEFIRST.

Le 1er janvier d'une année définit le numéro de départ de week datepart, par exemple : DATEPART (wk, 'Jan 1, xxxx') = 1, où xxxx représente une année.

Le tableau suivant répertorie la valeur de retour pour week et weekdaydatepart pour '2007-04-21 ' pour chaque argument SET DATEFIRST. Le 1er janvier est un lundi dans l'année 2007. Le 21 avril est un samedi dans l'année 2007. SET DATEFIRST 7, Sunday, est la valeur par défaut pour l'anglais des États-Unis .

Arguments des parties de date année, mois et jour

Les valeurs qui sont retournées pour DATEPART (year, date), DATEPART (month, date) et DATEPART (day, date) sont les mêmes que celles retournées par les fonctions YEAR, MONTH et DAY, respectivement.

Partie de date ISO_WEEK

ISO 8601 inclut le système semaine-date ISO, un système de numérotation pour les semaines. Chaque semaine est associée à l'année dans laquelle jeudi se produit. Par exemple, la semaine 1 de 2004 (2004W01) a eu lieu du lundi 29 décembre 2003 au dimanche 4 janvier 2004. Le numéro de semaine le plus élevé dans une année peut être 52 ou 53. Ce style de numérotation est utilisé en général dans les pays européens, plus rarement ailleurs.

Le système de numérotation des différents pays peut ne pas se conformer à la norme ISO. Il existe au moins six possibilités comme illustré dans le tableau suivant

TZoffset

TZoffset (tz) est retourné comme nombre de minutes (signé). L'instruction suivante retourne un décalage de fuseau horaire de 310 minutes.

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

Si l'argument datepart est de type TZoffset (tz) et que l'argument date n'est pas du type de données datetimeoffset, la valeur NULL est retournée.

Argument date smalldatetime

Lorsque date est de type smalldatetime, les secondes sont retournées sous la forme 00.

Valeur par défaut retournée pour une partie de date qui ne figure pas dans un argument date

Si le type de données de l'argument date n'a pas le datepart spécifié, la valeur par défaut pour ce datepart sera retournée uniquement lors de la spécification d'un littéral pour date.

Par exemple, la combinaison année-mois-jour par défaut pour tout type de données date est 1900-01-01. L'instruction suivante a des arguments de partie date pour datepart, un argument d'heure pour date et retourne 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');

Si date est spécifié comme variable ou colonne de table et que datepart n'est pas spécifié pour le type de données de cette variable ou colonne, l'erreur 9810 est retournée. L'exemple de code suivant échoue car la partie année de la date n'est pas valide pour le type de données time déclaré pour la variable @t.

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

Fractions de seconde

Les fractions de seconde sont retournées comme illustré dans les instructions suivantes :

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

Notes

DATEPART peut être utilisé dans la liste de sélection et les clauses WHERE, HAVING, GROUP BY et ORDER BY.

Dans SQL Server 2012, DATEPART convertit de façon implicite les littéraux de chaîne en type datetime2. Cela signifie que DATEPART ne prend pas en charge le format YDM lorsque la date est transmise en tant que chaîne. Vous devez convertir explicitement la chaîne en type datetime ou smalldatetime pour utiliser le format YDM.

Exemples

L'exemple suivant retourne l'année de base. L'année de base est utile pour les calculs de date. Dans l'exemple, la date est spécifiée comme un nombre. Notez que SQL Server interprète 0 comme représentant le 1er janvier 1900.

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

Voir aussi

Référence

CAST et CONVERT (Transact-SQL)