DATEDIFF (Transact-SQL)DATEDIFF (Transact-SQL)

S’APPLIQUE À : ouiSQL Server ouiAzure SQL Database ouiAzure Synapse Analytics (SQL DW) ouiParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) yesParallel Data Warehouse

Cette fonction retourne le nombre (valeur entière signée) de limites datepart spécifiées, traversées entre les valeurs startdate et enddate spécifiées.This function returns the count (as a signed integer value) of the specified datepart boundaries crossed between the specified startdate and enddate.

Consultez DATEDIFF_BIG (Transact-SQL) pour obtenir une fonction qui gère des différences plus importantes entre les valeurs startdate et enddate.See DATEDIFF_BIG (Transact-SQL) for a function that handles larger differences between the startdate and enddate values. Pour obtenir une vue d’ensemble de tous les types de données et fonctions de date et d’heure , consultez Types de données et fonctions de date et d’heure (Transact-SQL)Transact-SQLTransact-SQL.See Date and Time Data Types and Functions (Transact-SQL) for an overview of all Transact-SQLTransact-SQL date and time data types and functions.

Icône Lien de rubrique Conventions de la syntaxe Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SyntaxeSyntax

DATEDIFF ( datepart , startdate , enddate )  

ArgumentsArguments

datepartdatepart
Unités dans lesquelles DATEDIFF signale la différence entre startdate et enddate.The units in which DATEDIFF reports the difference between the startdate and enddate. Parmi les unités datepart couramment utilisées, citons month et second.Commonly used datepart units include month or second.

La valeur datepart ne peut pas être spécifiée dans une variable ni comme chaîne entre guillemets (par exemple, 'month').The datepart value cannot be specified in a variable, nor as a quoted string like 'month'.

Le tableau suivant liste toutes les valeurs datepart valides.The following table lists all the valid datepart values. DATEDIFF accepte le nom complet de datepart ou toute abréviation listée du nom complet.DATEDIFF accepts either the full name of the datepart, or any listed abbreviation of the full name.

Nom datepartdatepart name Abréviation datepartdatepart abbreviation
yearyear yy, yyyyyy, yyyy
quarterquarter qq, qqq, q
monthmonth mm, mmm, m
dayofyeardayofyear dy, ydy, y
dayday dd, ddd, d
weekweek wk, wwwk, ww
hourhour hhhh
minuteminute mi, nmi, n
secondsecond ss, sss, s
millisecondmillisecond msms
microsecondmicrosecond mcsmcs
nanosecondnanosecond nsns
   

Notes

Chaque nom datepart spécifique et les abréviations pour ce nom datepart retournent la même valeur.Each specific datepart name and abbreviations for that datepart name will return the same value.

startdatestartdate
Expression qui peut être résolue en valeur, parmi les suivantes :An expression that can resolve to one of the following values:

  • datedate
  • datetimedatetime
  • datetimeoffsetdatetimeoffset
  • datetime2datetime2
  • smalldatetimesmalldatetime
  • timetime

Pour éviter toute ambiguïté, utilisez des années à quatre chiffres.Use four-digit years to avoid ambiguity. Pour obtenir des informations sur les années à deux chiffres, consultez Configurer l’option de configuration du serveur two digit year cutoff.See Configure the two digit year cutoff Server Configuration Option for information about two-digit year values.

enddateenddate
Consultez startdate.See startdate.

Type de retourReturn Type

intint

Valeur de retourReturn Value

Différence int entre startdate et enddate, exprimée dans le jeu de limites par datepart.The int difference between the startdate and enddate, expressed in the boundary set by datepart.

Par exemple, SELECT DATEDIFF(day, '2036-03-01', '2036-02-28'); retourne -2, ce qui indique que 2036 doit être une année bissextile.For example, SELECT DATEDIFF(day, '2036-03-01', '2036-02-28'); returns -2, hinting that 2036 must be a leap year. Dans ce cas, si nous utilisons « 2036-03-01 » comme startdate et comptons -2 jours, nous obtenons « 2036-02-28 » comme enddate.This case means that if we start at startdate '2036-03-01', and then count -2 days, we reach the enddate of '2036-02-28'.

Si une valeur de retour est hors limites pour int (-2 147 483 648 à +2 147 483 647), DATEDIFF retourne une erreur.For a return value out of range for int (-2,147,483,648 to +2,147,483,647), DATEDIFF returns an error. Pour millisecond, la différence maximale entre startdate et enddate est de 24 jours, 20 heures, 31 minutes et 23,647 secondes.For millisecond, the maximum difference between startdate and enddate is 24 days, 20 hours, 31 minutes and 23.647 seconds. Pour seconde, la différence maximale est de 68 ans, 19 jours, 3 heures, 14 minutes et 7 secondes.For second, the maximum difference is 68 years, 19 days, 3 hours, 14 minutes and 7 seconds.

Si startdate et enddate se voient tous les deux assigner uniquement une valeur d’heure et que datepart n’est pas un datepart d’heure, DATEDIFF retourne 0.If startdate and enddate are both assigned only a time value, and the datepart is not a time datepart, DATEDIFF returns 0.

DATEDIFF utilise le composant de décalage de fuseau horaire de startdate ou enddate pour calculer la valeur de retour.DATEDIFF uses the time zone offset component of startdate or enddate to calculate the return value.

Dans la mesure où smalldatetime n’offre qu’une précision à la minute, les secondes et millisecondes ont toujours la valeur 0 dans la valeur de retour quand vous utilisez une valeur smalldatetime pour startdate ou enddate.Because smalldatetime is accurate only to the minute, seconds and milliseconds are always set to 0 in the return value when startdate or enddate have a smalldatetime value.

Si seule une valeur d’heure est affectée à une variable d’un type de données date, DATEDIFF définit la partie date manquante sur la valeur par défaut :1900-01-01.If only a time value is assigned to a date data type variable, DATEDIFF sets the value of the missing date part to the default value: 1900-01-01. Si seule une valeur de date est affectée à une variable d’un type de données date ou heure, DATEDIFF définit la partie heure manquante sur la valeur par défaut : 00:00:00.If only a date value is assigned to a variable of a time or date data type, DATEDIFF sets the value of the missing time part to the default value: 00:00:00. Si startdate ou enddate a uniquement une partie heure et que l’autre a uniquement une partie date, DATEDIFF affecte aux parties heure et date manquantes les valeurs par défaut.If either startdate or enddate have only a time part and the other only a date part, DATEDIFF sets the missing time and date parts to the default values.

Si startdate et enddate ont des types de données date différents et que l’un a plus de parties heure ou une meilleure précision en fractions de seconde que l’autre, DATEDIFF affecte aux parties manquantes de l’autre la valeur 0.If startdate and enddate have different date data types, and one has more time parts or fractional seconds precision than the other, DATEDIFF sets the missing parts of the other to 0.

Limites de datepartdatepart boundaries

Les instructions suivantes ont les mêmes valeurs startdate et enddate.The following statements have the same startdate and the same enddate values. Ces dates sont adjacentes et ont une différence d’une centaine de nanosecondes (0,0000001 seconde).Those dates are adjacent and they differ in time by a hundred nanoseconds (.0000001 second). La différence entre les startdate et endate dans chaque instruction traverse une limite d’heure ou de calendrier de son datepart.The difference between the startdate and enddate in each statement crosses one calendar or time boundary of its datepart. Chaque instruction retourne 1.Each statement returns 1.

SELECT DATEDIFF(year,        '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(quarter,     '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(month,       '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(dayofyear,   '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(day,         '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(week,        '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(hour,        '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(minute,      '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(second,      '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(millisecond, '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');
SELECT DATEDIFF(microsecond, '2005-12-31 23:59:59.9999999', '2006-01-01 00:00:00.0000000');

Si startdate et enddate ont des valeurs d’année différentes, mais les mêmes valeurs de semaine de calendrier, DATEDIFF retourne 0 pour datepart week.If startdate and enddate have different year values, but they have the same calendar week values, DATEDIFF will return 0 for datepart week.

NotesRemarks

Utilisez DATEDIFF dans les clauses SELECT <list>, WHERE, HAVING, GROUP BY et ORDER BY.Use DATEDIFF in the SELECT <list>, WHERE, HAVING, GROUP BY and ORDER BY clauses.

DATEDIFF caste implicitement les littéraux de chaîne en type datetime2.DATEDIFF implicitly casts string literals as a datetime2 type. Cela signifie que DATEDIFF ne prend pas en charge le format YDM quand la date est passée comme chaîne.This means that DATEDIFF does not support the format YDM when the date is passed as a string. Vous devez caster explicitement la chaîne en type datetime ou smalldatetime pour utiliser le format AJM.You must explicitly cast the string to a datetime or smalldatetime type to use the YDM format.

La spécification de SET DATEFIRST n’a pas d’effet sur DATEDIFF.Specifying SET DATEFIRST has no effect on DATEDIFF. DATEDIFF utilise toujours Dimanche comme premier jour de la semaine pour que la fonction soit déterministe.DATEDIFF always uses Sunday as the first day of the week to ensure the function operates in a deterministic way.

DATEDIFF peut dépasser la capacité avec une précision d’une minute ou plus si la différence entre enddate et startdate retourne une valeur qui est hors limites pour int .DATEDIFF may overflow with a precision of minute or higher if the difference between enddate and startdate returns a value that is out of range for int.

ExemplesExamples

Ces exemples utilisent différents types d’expressions comme arguments pour les paramètres startdate et enddate.These examples use different types of expressions as arguments for the startdate and enddate parameters.

R.A. Spécification de colonnes pour les dates de début et de finSpecifying columns for startdate and enddate

Cet exemple calcule le nombre de limites de jour qui sont traversées entre les dates de deux colonnes dans une table.This example calculates the number of day boundaries crossed between dates in two columns in a table.

CREATE TABLE dbo.Duration  
    (startDate datetime2, endDate datetime2);  
    
INSERT INTO dbo.Duration(startDate, endDate)  
    VALUES ('2007-05-06 12:10:09', '2007-05-07 12:10:09');  
    
SELECT DATEDIFF(day, startDate, endDate) AS 'Duration'  
    FROM dbo.Duration;  
-- Returns: 1  

B.B. Spécification de variables définies par l'utilisateur pour les dates de début et de finSpecifying user-defined variables for startdate and enddate

Dans cet exemple, les variables définies par l’utilisateur font office d’arguments pour startdate et enddate.In this example, user-defined variables serve as arguments for startdate and enddate.

DECLARE @startdate datetime2 = '2007-05-05 12:10:09.3312722';  
DECLARE @enddate   datetime2 = '2007-05-04 12:10:09.3312722';   
SELECT DATEDIFF(day, @startdate, @enddate);  

C.C. Spécification de fonctions système scalaires pour les dates de début et de finSpecifying scalar system functions for startdate and enddate

Cet exemple utilise des fonctions système scalaires comme arguments pour startdate et enddate.This example uses scalar system functions as arguments for startdate and enddate.

SELECT DATEDIFF(millisecond, GETDATE(), SYSDATETIME());  

D.D. Spécification de sous-requêtes scalaires et de fonctions scalaires pour les dates de début et de finSpecifying scalar subqueries and scalar functions for startdate and enddate

Cet exemple utilise des sous-requêtes et des fonctions scalaires comme arguments pour startdate et enddate.This example uses scalar subqueries and scalar functions as arguments for startdate and enddate.

USE AdventureWorks2012;  
GO  
SELECT DATEDIFF(day,
    (SELECT MIN(OrderDate) FROM Sales.SalesOrderHeader),  
    (SELECT MAX(OrderDate) FROM Sales.SalesOrderHeader));  

E.E. Spécification de constantes pour les dates de début et de finSpecifying constants for startdate and enddate

Cet exemple suivant des constantes à caractères comme arguments pour startdate et enddate.This example uses character constants as arguments for startdate and enddate.

SELECT DATEDIFF(day,
   '2007-05-07 09:53:01.0376635',
   '2007-05-08 09:53:01.0376635');  

F.F. Spécification d'expressions numériques et de fonctions système scalaires pour la date de finSpecifying numeric expressions and scalar system functions for enddate

Ce exemple utilise une expression numérique, (GETDATE() + 1) et des fonctions système scalaires, GETDATE et SYSDATETIME, comme arguments pour enddate.This example uses a numeric expression, (GETDATE() + 1), and scalar system functions GETDATE and SYSDATETIME, as arguments for enddate.

USE AdventureWorks2012;  
GO  
SELECT DATEDIFF(day, '2007-05-07 09:53:01.0376635', GETDATE() + 1)
    AS NumberOfDays  
    FROM Sales.SalesOrderHeader;  
GO  
USE AdventureWorks2012;  
GO  
SELECT
    DATEDIFF(
            day,
            '2007-05-07 09:53:01.0376635',
            DATEADD(day, 1, SYSDATETIME())
        ) AS NumberOfDays  
    FROM Sales.SalesOrderHeader;  
GO  

G.G. Spécification de fonctions de classement pour la date de débutSpecifying ranking functions for startdate

Cet exemple utilise une fonction de classement comme argument pour startdate.This example uses a ranking function as an argument for startdate.

USE AdventureWorks2012;  
GO  
SELECT p.FirstName, p.LastName  
    ,DATEDIFF(day, ROW_NUMBER() OVER (ORDER BY   
        a.PostalCode), SYSDATETIME()) AS 'Row Number'  
FROM Sales.SalesPerson s   
    INNER JOIN Person.Person p   
        ON s.BusinessEntityID = p.BusinessEntityID  
    INNER JOIN Person.Address a   
        ON a.AddressID = p.BusinessEntityID  
WHERE TerritoryID IS NOT NULL   
    AND SalesYTD <> 0;  

H.H. Spécification d'une fonction d'agrégation pour la date de débutSpecifying an aggregate window function for startdate

Cet exemple utilise une fonction d’agrégation comme argument pour startdate.This example uses an aggregate window function as an argument for startdate.

USE AdventureWorks2012;  
GO  
SELECT soh.SalesOrderID, sod.ProductID, sod.OrderQty, soh.OrderDate,
    DATEDIFF(day, MIN(soh.OrderDate)   
        OVER(PARTITION BY soh.SalesOrderID), SYSDATETIME()) AS 'Total'  
FROM Sales.SalesOrderDetail sod  
    INNER JOIN Sales.SalesOrderHeader soh  
        ON sod.SalesOrderID = soh.SalesOrderID  
WHERE soh.SalesOrderID IN(43659, 58918);  
GO  

I.I. Recherche de la différence entre des dates startdate et enddate sous forme de chaînes de parties de dateFinding difference between startdate and enddate as date parts strings

-- DOES NOT ACCOUNT FOR LEAP YEARS
DECLARE @date1 DATETIME, @date2 DATETIME, @result VARCHAR(100);
DECLARE @years INT, @months INT, @days INT,
    @hours INT, @minutes INT, @seconds INT, @milliseconds INT;

SET @date1 = '1900-01-01 00:00:00.000'
SET @date2 = '2018-12-12 07:08:01.123'

SELECT @years = DATEDIFF(yy, @date1, @date2)
IF DATEADD(yy, -@years, @date2) < @date1 
SELECT @years = @years-1
SET @date2 = DATEADD(yy, -@years, @date2)

SELECT @months = DATEDIFF(mm, @date1, @date2)
IF DATEADD(mm, -@months, @date2) < @date1 
SELECT @months=@months-1
SET @date2= DATEADD(mm, -@months, @date2)

SELECT @days=DATEDIFF(dd, @date1, @date2)
IF DATEADD(dd, -@days, @date2) < @date1 
SELECT @days=@days-1
SET @date2= DATEADD(dd, -@days, @date2)

SELECT @hours=DATEDIFF(hh, @date1, @date2)
IF DATEADD(hh, -@hours, @date2) < @date1 
SELECT @hours=@hours-1
SET @date2= DATEADD(hh, -@hours, @date2)

SELECT @minutes=DATEDIFF(mi, @date1, @date2)
IF DATEADD(mi, -@minutes, @date2) < @date1 
SELECT @minutes=@minutes-1
SET @date2= DATEADD(mi, -@minutes, @date2)

SELECT @seconds=DATEDIFF(s, @date1, @date2)
IF DATEADD(s, -@seconds, @date2) < @date1 
SELECT @seconds=@seconds-1
SET @date2= DATEADD(s, -@seconds, @date2)

SELECT @milliseconds=DATEDIFF(ms, @date1, @date2)

SELECT @result= ISNULL(CAST(NULLIF(@years,0) AS VARCHAR(10)) + ' years,','')
     + ISNULL(' ' + CAST(NULLIF(@months,0) AS VARCHAR(10)) + ' months,','')    
     + ISNULL(' ' + CAST(NULLIF(@days,0) AS VARCHAR(10)) + ' days,','')
     + ISNULL(' ' + CAST(NULLIF(@hours,0) AS VARCHAR(10)) + ' hours,','')
     + ISNULL(' ' + CAST(@minutes AS VARCHAR(10)) + ' minutes and','')
     + ISNULL(' ' + CAST(@seconds AS VARCHAR(10)) 
     + CASE
            WHEN @milliseconds > 0
                THEN '.' + CAST(@milliseconds AS VARCHAR(10)) 
            ELSE ''
       END 
     + ' seconds','')

SELECT @result

Voici le jeu de résultats obtenu.Here is the result set.

118 years, 11 months, 11 days, 7 hours, 8 minutes and 1.123 seconds

Exemples : Azure Synapse Analytics (SQL DW)Azure Synapse Analytics (SQL DW) et Parallel Data WarehouseParallel Data WarehouseExamples: Azure Synapse Analytics (SQL DW)Azure Synapse Analytics (SQL DW) and Parallel Data WarehouseParallel Data Warehouse

Ces exemples utilisent différents types d’expressions comme arguments pour les paramètres startdate et enddate.These examples use different types of expressions as arguments for the startdate and enddate parameters.

J.J. Spécification de colonnes pour les dates de début et de finSpecifying columns for startdate and enddate

Cet exemple calcule le nombre de limites de jour qui sont traversées entre les dates de deux colonnes dans une table.This example calculates the number of day boundaries crossed between dates in two columns in a table.

CREATE TABLE dbo.Duration 
    (startDate datetime2, endDate datetime2);
    
INSERT INTO dbo.Duration (startDate, endDate)  
    VALUES ('2007-05-06 12:10:09', '2007-05-07 12:10:09');  
    
SELECT TOP(1) DATEDIFF(day, startDate, endDate) AS Duration  
    FROM dbo.Duration;  
-- Returns: 1  

K.K. Spécification de sous-requêtes scalaires et de fonctions scalaires pour les dates de début et de finSpecifying scalar subqueries and scalar functions for startdate and enddate

Cet exemple utilise des sous-requêtes et des fonctions scalaires comme arguments pour startdate et enddate.This example uses scalar subqueries and scalar functions as arguments for startdate and enddate.

-- Uses AdventureWorks  
  
SELECT TOP(1) DATEDIFF(day, (SELECT MIN(HireDate) FROM dbo.DimEmployee),  
    (SELECT MAX(HireDate) FROM dbo.DimEmployee))   
FROM dbo.DimEmployee;  
  

L.L. Spécification de constantes pour les dates de début et de finSpecifying constants for startdate and enddate

Cet exemple suivant des constantes à caractères comme arguments pour startdate et enddate.This example uses character constants as arguments for startdate and enddate.

-- Uses AdventureWorks  
  
SELECT TOP(1) DATEDIFF(day,
    '2007-05-07 09:53:01.0376635',
    '2007-05-08 09:53:01.0376635') FROM DimCustomer;  

M.M. Spécification de fonctions de classement pour la date de débutSpecifying ranking functions for startdate

Cet exemple utilise une fonction de classement comme argument pour startdate.This example uses a ranking function as an argument for startdate.

-- Uses AdventureWorks  
  
SELECT FirstName, LastName,
    DATEDIFF(day, ROW_NUMBER() OVER (ORDER BY   
        DepartmentName), SYSDATETIME()) AS RowNumber  
FROM dbo.DimEmployee;  

N.N. Spécification d'une fonction d'agrégation pour la date de débutSpecifying an aggregate window function for startdate

Cet exemple utilise une fonction d’agrégation comme argument pour startdate.This example uses an aggregate window function as an argument for startdate.

-- Uses AdventureWorks  
  
SELECT FirstName, LastName, DepartmentName,
    DATEDIFF(year, MAX(HireDate)  
        OVER (PARTITION BY DepartmentName), SYSDATETIME()) AS SomeValue  
FROM dbo.DimEmployee  

Voir aussiSee also

DATEDIFF_BIG (Transact-SQL)DATEDIFF_BIG (Transact-SQL)
CAST et CONVERT (Transact-SQL)CAST and CONVERT (Transact-SQL)