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

ESTE TÓPICO APLICA-SE A: simSQL Server (a partir de 2008)simBanco de Dados SQL do Microsoft AzuresimAzure SQL Data Warehouse simParallel Data Warehouse THIS TOPIC APPLIES TO: yesSQL Server (starting with 2008)yesAzure SQL DatabaseyesAzure SQL Data Warehouse yesParallel Data Warehouse

Essa função retorna a contagem (como um valor inteiro com sinal) dos limites de datepart especificados cruzados entre os parâmetros especificados startdate e enddate.This function returns the count (as a signed integer value) of the specified datepart boundaries crossed between the specified startdate and enddate.

Consulte DATEDIFF_BIG (Transact-SQL) para obter uma função que manipula diferenças maiores entre os valores startdate e enddate.See DATEDIFF_BIG (Transact-SQL) for a function that handles larger differences between the startdate and enddate values. 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-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.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

DATEDIFF ( datepart , startdate , enddate )  

ArgumentosArguments

datepartdatepart
A parte de startdate e de enddate que especifica o tipo de limite ultrapassado.The part of startdate and enddate that specifies the type of boundary crossed. DATEDIFF não aceitarão equivalentes de variável definidos pelo usuário.DATEDIFF will not accept user-defined variable equivalents. Esta tabela lista todos os argumentos datepart válidos.This table lists all valid datepart arguments.

datepartdatepart AbreviaçõesAbbreviations
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

startdatestartdate
Uma expressão que pode resolver um dos seguintes valores:An expression that can resolve to one of the following values:

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

Use anos de quatro dígitos para evitar ambiguidade.Use four-digit years to avoid ambiguity. Consulte Configurar a opção two digit year cutoff de configuração de servidor para obter informações sobre valores de anos de dois dígitos.See Configure the two digit year cutoff Server Configuration Option for information about two-digit year values.

enddateenddate
Consulte startdate.See startdate.

Tipo de retornoReturn Type

intint

Valor retornadoReturn Value

  • Cada datepart específico e as abreviações desse datepart retornarão o mesmo valor.Each specific datepart and the abbreviations for that datepart will return the same value.

Para um valor retornado fora do intervalo para int (-2.147.483.648 a +2.147.483.647), DATEDIFF retorna um erro.For a return value out of range for int (-2,147,483,648 to +2,147,483,647), DATEDIFF returns an error. Para millisecond, a diferença máxima entre startdate e enddate é de 24 dias, 20 horas, 31 minutos e 23.647 segundos.For millisecond, the maximum difference between startdate and enddate is 24 days, 20 hours, 31 minutes and 23.647 seconds. Para second, a diferença máxima é de 68 anos.For second, the maximum difference is 68 years.

Se startdate e enddate receberem apenas um valor temporal e datepart não for um datepart de hora, DATEDIFF retornará 0.If startdate and enddate are both assigned only a time value, and the datepart is not a time datepart, DATEDIFF returns 0.

DATEDIFF não usa um componente de deslocamento de fuso horário de startdate ou enddate para calcular o valor retornado.DATEDIFF does not use a time zone offset component of startdate or enddate to calculate the return value.

Como smalldatetime tem precisão apenas quanto ao minuto, segundos e milissegundos são sempre definidos como 0 no valor retornado quando um valor smalldatetime é usado para startdate ou enddate.Because smalldatetime has 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.

Se apenas um valor temporal for atribuído a uma variável de tipo de dados de data, DATEDIFF definirá o valor da parte de data ausente como o valor padrão: 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. Se apenas um valor de data for atribuído a uma variável de um tipo de dados de data ou hora, DATEDIFF definirá o valor da parte de hora ausente como o valor padrão: 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. Se startdate ou enddate tiver apenas uma parte de hora e a outra apenas uma parte de data, DATEDIFF definirá as partes de hora e data ausentes como os valores padrão.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.

Se startdate e enddate tiverem diferentes tipos de dados de data e um tiver mais partes de hora ou precisão de segundos fracionários do que o outro, DATEDIFF definirá as partes ausentes do outro como 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

As instruções a seguir têm os mesmos valores de startdate e de enddate.The following statements have the same startdate and the same enddate values. Essas datas são adjacentes e diferem, quanto à hora, em 0,0000001 segundo.Those dates are adjacent and they differ in time by .0000001 second. A diferença entre startdate e enddate em cada instrução cruza um calendário ou limite de hora de sua datepart.The difference between the startdate and enddate in each statement crosses one calendar or time boundary of its datepart. Cada instrução retorna 1.Each statement returns 1. Se startdate e enddate tiverem diferentes valores de ano, mas os mesmos valores semanais de calendário, DATEDIFF retornará 0 para 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.

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');

RemarksRemarks

Use DATEDIFF nas cláusulas SELECT , WHERE, HAVING, GROUP BY e ORDER BY.Use DATEDIFF in the SELECT , WHERE, HAVING, GROUP BY and ORDER BY clauses.

DATEDIFF converte implicitamente literais de cadeias de caracteres como um tipo datetime2.DATEDIFF implicitly casts string literals as a datetime2 type. Isso significa que DATEDIFF não é compatível com o formato YDM quando a data é transmitida como cadeia de caracteres.This means that DATEDIFF does not support the format YDM when the date is passed as a string. É necessário converter explicitamente a cadeia de caracteres em um tipo de datetime ou smalldatetime para usar o formato YDM.You must explicitly cast the string to a datetime or smalldatetime type to use the YDM format.

A especificação SET DATEFIRST não tem efeito sobre DATEDIFF.Specifying SET DATEFIRST has no effect on DATEDIFF. DATEDIFF sempre usa domingo como o primeiro dia da semana para garantir que a função opere de maneira determinística.DATEDIFF always uses Sunday as the first day of the week to ensure the function operates in a deterministic way.

ExemplosExamples

Esses exemplos usam diferentes tipos de expressões como argumentos para os parâmetros startdate e enddate.These examples use different types of expressions as arguments for the startdate and enddate parameters.

A.A. Especificando colunas para startdate e enddateSpecifying columns for startdate and enddate

Este exemplo calcula o número de limites de dia cruzados entre datas em duas colunas de uma tabela.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. Especificando variáveis definidas pelo usuário para startdate e enddateSpecifying user-defined variables for startdate and enddate

Nesse exemplo, variáveis definidas pelo usuário funcionam como argumentos para startdate e 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. Especificando funções de sistema escalares para startdate e enddateSpecifying scalar system functions for startdate and enddate

Esse exemplo usa funções do sistema escalares como argumentos para startdate e enddate.This example uses scalar system functions as arguments for startdate and enddate.

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

D.D. Especificando subconsultas e funções escalares para startdate e enddateSpecifying scalar subqueries and scalar functions for startdate and enddate

Este exemplo usa subconsultas e funções escalares como argumentos para startdate e 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. Especificando constantes para startdate e enddateSpecifying constants for startdate and enddate

Este exemplo usa constantes de caractere como argumentos para startdate e 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. Especificando expressões numéricas e funções de sistema escalares para enddateSpecifying numeric expressions and scalar system functions for enddate

Esse exemplo usa uma expressão numérica, (GETDATE() + 1), e as funções do sistema escalares, GETDATE e SYSDATETIME, como argumentos para 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. Especificando funções de classificação para startdateSpecifying ranking functions for startdate

Este exemplo usa uma função de classificação como um argumento para 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. Especificando uma função de janela de agregação para startdateSpecifying an aggregate window function for startdate

Este exemplo usa uma função de janela de agregação como um argumento para 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  

Exemplos: Azure SQL Data WarehouseAzure SQL Data Warehouse e Parallel Data WarehouseParallel Data WarehouseExamples: Azure SQL Data WarehouseAzure SQL Data Warehouse and Parallel Data WarehouseParallel Data Warehouse

Esses exemplos usam diferentes tipos de expressões como argumentos para os parâmetros startdate e enddate.These examples use different types of expressions as arguments for the startdate and enddate parameters.

I.I. Especificando colunas para startdate e enddateSpecifying columns for startdate and enddate

Este exemplo calcula o número de limites de dia cruzados entre datas em duas colunas de uma tabela.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  

J.J. Especificando subconsultas e funções escalares para startdate e enddateSpecifying scalar subqueries and scalar functions for startdate and enddate

Este exemplo usa subconsultas e funções escalares como argumentos para startdate e 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;  

K.K. Especificando constantes para startdate e enddateSpecifying constants for startdate and enddate

Este exemplo usa constantes de caractere como argumentos para startdate e 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;  

L.L. Especificando funções de classificação para startdateSpecifying ranking functions for startdate

Este exemplo usa uma função de classificação como um argumento para 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;  

M.M. Especificando uma função de janela de agregação para startdateSpecifying an aggregate window function for startdate

Este exemplo usa uma função de janela de agregação como um argumento para 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  

Confira tambémSee also

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