DATEADD (Transact-SQL)
Retorna uma date especificada com o intervalo number especificado (inteiro assinado) adicionado à datepart especificada dessa date.
Para obter uma visão geral de todos os tipos de dados e funções de data e hora do Transact-SQL, consulte Funções Date e Time (Transact-SQL). Para obter informações e exemplos comuns dos tipos de dados e funções de data e hora, consulte Usando dados de data e hora.
.gif "Ícone de vínculo de tópico")
Sintaxe
DATEADD (datepart , number , date )
Argumentos
datepart
É a parte de date para a qual um integernumber é adicionado. A tabela a seguir lista todos os argumentos datepart válidos. Equivalentes de variáveis definidas pelo usuário não são válidas.datepart
Abreviações
year
yy, yyyy
quarter
qq, q
month
mm, m
dayofyear
dy, y
day
dd, d
week
wk, ww
weekday
dw, w
hour
hh
minute
mi, n
second
ss, s
millisecond
ms
microsecond
mcs
nanosecond
ns
number
É uma expressão que pode ser resolvida para um int que é adicionado à datepart da date. Variáveis definidas pelo usuário são válidas.Se você especificar um valor com uma fração decimal, a fração será truncada e não arredondada.
date
É uma expressão que pode ser resolvida para um valor time, date, smalldatetime, datetime, datetime2 ou valor datetimeoffset. date pode ser uma expressão, uma expressão de coluna, uma variável definida pelo usuário ou um literal de cadeia de caracteres. Se a expressão for uma cadeia de caracteres literal, deverá ser resolvido como um datetime. Para evitar ambiguidade, quatro dígitos para o ano. Para obter informações sobre anos de dois dígitos, consulte Opção two digit year cutoff.
Tipos de retorno
O tipo de dados de retorno é o tipo de dados do argumento date, com exceção de literais de cadeia de caracteres.
O tipo de dados de retorno para um literal de cadeia de caracteres é datetime. Um erro será gerado se a escala de segundos da cadeia de caracteres literal tiver mais de três posições (.nnn) ou contiver a parte de deslocamento de fuso horário.
.gif "Observação") Observação |
|---|
Se cadeias de caracteres literais não forem convertidas explicitamente para o parâmetro date os locais que usam um formato de data dma (dia-mês-ano) poderão obter resultados incorretos quando DATEADD for usado junto com outras funções de data/hora. |
Retornando um tipo datetime2
DATEADD retorna um tipo datetime2 quando o parâmetro date é um tipo datetime2. Ao usar cadeias de caracteres literais para o parâmetro date, você as deve converter explicitamente em um tipo datetime2 para que DATEADD retorne um tipo datetime2.
Argumento datepart
dayofyear, day e weekday retornam o mesmo valor.
Cada datepart e suas abreviações retornam o mesmo valor.
Se datepart for month e o mês date tiver mais dias que o mês de retorno e o dia date não existir no mês de retorno, o último dia do mês de retorno será retornado. Por exemplo, setembro tem 30 dias; então, as duas instruções a seguir retornam 2006-09-30 00:00:00.000:
SELECT DATEADD(month, 1, '2006-08-30')
SELECT DATEADD(month, 1, '2006-08-31')
O argumento number não pode exceder o intervalo de int. Nas instruções a seguir, o argumento para number excede o intervalo de int em 1. A mensagem de erro a seguir é retornada: “Erro de estouro aritmético na conversão da expressão em dados tipo int”.
SELECT DATEADD(year,2147483648, '2006-07-31');
SELECT DATEADD(year,-2147483649, '2006-07-31');
O argumento date não pode ser incrementado a um valor fora do intervalo de seu tipo de dados. Nas instruções a seguir, o valor number que é adicionado ao valor date excede o intervalo do tipo de dados date. A mensagem de erro a seguir é retornada: "Adicionar um valor a uma coluna 'datetime' causou o estouro".
SELECT DATEADD(year,2147483647, '2006-07-31');
SELECT DATEADD(year,-2147483647, '2006-07-31');
A segunda parte de um valor smalldatetime é sempre 00. Se date for smalldatetime, o seguinte se aplicará:
Se datepart for second e number estiver entre -30 e +29, nenhum acréscimo será executado.
Se datepart for second e number for inferior a -30 ou superior a +29, o acréscimo será executado iniciando em um minuto.
Se datepart for millisecond e number estiver entre -30001 e +29998, nenhum acréscimo será executado.
Se datepart for millisecond e number for inferior a -30001 ou superior a +29998, o acréscimo será executado iniciando em um minuto.
Comentários
DATEADD pode ser usado na <lista> SELECT, cláusulas WHERE, HAVING, GROUP BY e ORDER BY.
Precisão de frações de segundo
O acréscimo de datepart de microsecond ou nanosecond para os tipos de dados datesmalldatetime, date e datetime não é permitido.
Os milissegundos têm uma escala de 3 (0,123). Os microssegundos têm uma escala de 6 (0,123456). Os nanossegundos têm uma escala de 9 (0,123456789). Os tipos de dados time, datetime2 e datetimeoffset têm uma escala máxima de 7 (0,1234567). Se datepart for nanosecond, number deve ser 100 antes das frações de segundo de aumento de date. Um number entre 1 e 49 será arredondado para 0 e um número de 50 a 99 será arredondado para 100.
As instruções a seguir adicionam um datepart de millisecond, microsecondou nanosecond.
DECLARE @datetime2 datetime2 = '2007-01-01 13:10:10.1111111'
SELECT '1 millisecond' ,DATEADD(millisecond,1,@datetime2)
UNION ALL
SELECT '2 milliseconds', DATEADD(millisecond,2,@datetime2)
UNION ALL
SELECT '1 microsecond', DATEADD(microsecond,1,@datetime2)
UNION ALL
SELECT '2 microseconds', DATEADD(microsecond,2,@datetime2)
UNION ALL
SELECT '49 nanoseconds', DATEADD(nanosecond,49,@datetime2)
UNION ALL
SELECT '50 nanoseconds', DATEADD(nanosecond,50,@datetime2)
UNION ALL
SELECT '150 nanoseconds', DATEADD(nanosecond,150,@datetime2);
/*
Returns:
1 millisecond 2007-01-01 13:10:10.1121111
2 milliseconds 2007-01-01 13:10:10.1131111
1 microsecond 2007-01-01 13:10:10.1111121
2 microseconds 2007-01-01 13:10:10.1111131
49 nanoseconds 2007-01-01 13:10:10.1111111
50 nanoseconds 2007-01-01 13:10:10.1111112
150 nanoseconds 2007-01-01 13:10:10.1111113
*/
Deslocamento de fuso horário
Não é permitido acréscimo ao deslocamento de fuso horário.
Exemplos
A. Incrementando datepart em um intervalo de 1
Cada uma das instruções a seguir incrementa datepart por um intervalo de 1.
DECLARE @datetime2 datetime2 = '2007-01-01 13:10:10.1111111'
SELECT 'year', DATEADD(year,1,@datetime2)
UNION ALL
SELECT 'quarter',DATEADD(quarter,1,@datetime2)
UNION ALL
SELECT 'month',DATEADD(month,1,@datetime2)
UNION ALL
SELECT 'dayofyear',DATEADD(dayofyear,1,@datetime2)
UNION ALL
SELECT 'day',DATEADD(day,1,@datetime2)
UNION ALL
SELECT 'week',DATEADD(week,1,@datetime2)
UNION ALL
SELECT 'weekday',DATEADD(weekday,1,@datetime2)
UNION ALL
SELECT 'hour',DATEADD(hour,1,@datetime2)
UNION ALL
SELECT 'minute',DATEADD(minute,1,@datetime2)
UNION ALL
SELECT 'second',DATEADD(second,1,@datetime2)
UNION ALL
SELECT 'millisecond',DATEADD(millisecond,1,@datetime2)
UNION ALL
SELECT 'microsecond',DATEADD(microsecond,1,@datetime2)
UNION ALL
SELECT 'nanosecond',DATEADD(nanosecond,1,@datetime2);
/*
Year 2008-01-01 13:10:10.1111111
quarter 2007-04-01 13:10:10.1111111
month 2007-02-01 13:10:10.1111111
dayofyear 2007-01-02 13:10:10.1111111
day 2007-01-02 13:10:10.1111111
week 2007-01-08 13:10:10.1111111
weekday 2007-01-02 13:10:10.1111111
hour 2007-01-01 14:10:10.1111111
minute 2007-01-01 13:11:10.1111111
second 2007-01-01 13:10:11.1111111
millisecond 2007-01-01 13:10:10.1121111
microsecond 2007-01-01 13:10:10.1111121
nanosecond 2007-01-01 13:10:10.1111111
*/
B. Incrementando mais de um nível de datepart em uma instrução
Cada uma das instruções a seguir incrementa datepart por um number grande o suficiente para também incrementar a próxima datepart superior de date.
DECLARE @datetime2 datetime2;
SET @datetime2 = '2007-01-01 01:01:01.1111111';
--Statement Result
-------------------------------------------------------------------
SELECT DATEADD(quarter,4,@datetime2); --2008-01-01 01:01:01.110
SELECT DATEADD(month,13,@datetime2); --2008-02-01 01:01:01.110
SELECT DATEADD(dayofyear,365,@datetime2); --2008-01-01 01:01:01.110
SELECT DATEADD(day,365,@datetime2); --2008-01-01 01:01:01.110
SELECT DATEADD(week,5,@datetime2); --2007-02-05 01:01:01.110
SELECT DATEADD(weekday,31,@datetime2); --2007-02-01 01:01:01.110
SELECT DATEADD(hour,23,@datetime2); --2007-01-02 00:01:01.110
SELECT DATEADD(minute,59,@datetime2); --2007-01-01 02:00:01.110
SELECT DATEADD(second,59,@datetime2); --2007-01-01 01:02:00.110
SELECT DATEADD(millisecond,1,@datetime2); --2007-01-01 01:01:01.110
C. Usando expressões como argumentos para os parâmetros de número e data
Os exemplos a seguir usam tipos diferentes de expressões como argumentos para os parâmetros number e date.
Especificando coluna como data
O exemplo a seguir adiciona 2 dias a cada OrderDate para calcular uma nova PromisedShipDate.
USE AdventureWorks2008R2;
GO
SELECT SalesOrderID
,OrderDate
,DATEADD(day,2,OrderDate) AS PromisedShipDate
FROM Sales.SalesOrderHeader;
Especificando variáveis definidas pelo usuário como número e data
O exemplo a seguir especifica variáveis definidas pelo usuário como argumentos para number e date.
DECLARE @days int;
DECLARE @datetime datetime;
SET @days = 365;
SET @datetime = '2000-01-01 01:01:01.111'; /* 2000 was a leap year */
SELECT DATEADD(day, @days, @datetime);
Especificando função de sistema escalar como data
O exemplo a seguir especifica SYSDATETIME para date.
SELECT DATEADD(month, 1, SYSDATETIME());
Especificando subconsultas e funções escalares como número e data
O exemplo a seguir usa subconsultas escalares e funções escalares, MAX(ModifiedDate), como argumentos para number e date. (SELECT TOP 1 BusinessEntityID FROM Person.Person) é um argumento artificial para o parâmetro de número mostrar como é selecionado um argumento number de uma lista de valores.
USE AdventureWorks2008R2;
GO
SELECT DATEADD(month,(SELECT TOP 1 BusinessEntityID FROM Person.Person),
(SELECT MAX(ModifiedDate) FROM Person.Person));
Especificando constantes como número e data
O exemplo a seguir usa constantes numéricas e de caractere como argumentos para number e date.
SELECT DATEADD(minute, 1, '2007-05-07 09:53:01.0376635');
Especificando expressões numéricas e funções de sistema escalares como número e data
O exemplo a seguir usa expressões numéricas (-(10/2)), operadores unários (-), um operador aritmético (/) e funções de sistema escalares (SYSDATETIME) como argumentos para number e date.
SELECT DATEADD(month,-(10/2), SYSDATETIME());
Especificando funções de classificação como número
O exemplo a seguir usa uma função de classificação como argumentos para number.
USE AdventureWorks2008R2;
GO
SELECT p.FirstName, p.LastName
,DATEADD(day,ROW_NUMBER() OVER (ORDER BY
a.PostalCode),SYSDATETIME()) AS 'Row Number'
FROM Sales.SalesPerson AS s
INNER JOIN Person.Person AS p
ON s.BusinessEntityID = p.BusinessEntityID
INNER JOIN Person.Address AS a
ON a.AddressID = p.BusinessEntityID
WHERE TerritoryID IS NOT NULL
AND SalesYTD <> 0;
Especificando uma função de janela agregada como número
O exemplo a seguir usa uma função de janela agregada como um argumento para number.
USE AdventureWorks2008R2;
GO
SELECT SalesOrderID, ProductID, OrderQty
,DATEADD(day,SUM(OrderQty)
OVER(PARTITION BY SalesOrderID),SYSDATETIME()) AS 'Total'
FROM Sales.SalesOrderDetail
WHERE SalesOrderID IN(43659,43664);
GO
D. Usando DATEADD para Localidades que usam o formato de data dma
Os exemplos a seguir mostram como usar cadeias de caracteres literais com DATEADD para algumas localidades.
Demonstrando as armadilhas do uso de uma conversão implícita de uma cadeia de caracteres literal
O exemplo a seguir mostra o que acontece quando uma cadeia de caracteres literal não é convertida explicitamente.
SET LANGUAGE Español;
GO
SELECT DATENAME(m, DATEADD(d, 0,'1987-03-07'));
SELECT DATENAME(m, '1987-03-07');
GO
A primeira instrução select retorna julio (julho) para o mês e a segunda instrução select retorna marzo (março) para o mês.
Evitando resultados errôneos convertendo a cadeia de caracteres literal explicitamente
O exemplo a seguir mostra como converter explicitamente o parâmetro date para evitar resultados errôneos.
SET LANGUAGE Español;
GO
SELECT DATENAME(m, DATEADD(d, 0, CAST('1987-03-07' AS datetime2)));
SELECT DATENAME(m, '1987-03-07');
GO
As duas instruções select retornam marzo (março) para o mês.
Usando uma variável datetime2 no lugar de uma cadeia de caracteres literal
O exemplo a seguir evita o uso direto de uma cadeia de caracteres literal.
SET LANGUAGE Español;
GO
DECLARE @d datetime2 = '1987-03-07';
SELECT DATENAME(m, DATEADD(d, 0, @d));
SELECT DATENAME(m, @d);
GO