DATEADD (Transact-SQL)

Aplica-se a:SQL ServerBase de Dados SQL do AzureInstância Gerida do Azure SQLAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)Ponto de Extremidade de Análise SQL no Microsoft FabricArmazém no Microsoft FabricBase de Dados SQL no Microsoft Fabric

Esta função adiciona um número (um bigint assinado) a uma dataparte de uma data de entrada e devolve um valor de data/hora modificado. Por exemplo, você pode usar essa função para encontrar a data que é 7.000 minutos a partir de hoje: número = 7000, datepart = minuto, data = hoje.

Consulte Tipos e funções de dados de data e hora para obter uma visão geral de todos os tipos e funções de dados de data e hora Transact-SQL.

Transact-SQL convenções de sintaxe

Syntax

DATEADD ( datepart , number , date )

Arguments

datepart

A parte da data a que DATEADD acrescenta um número bigint.

Esta tabela lista todos os argumentos datepart válidos. DATEADD não aceita equivalentes de variáveis definidos pelo usuário para os argumentos datepart .

datepart	Abbreviations
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 resultar num bigint que DATEADD se soma a uma data dedata. DATEADD aceita valores de variáveis definidos pelo usuário para número. DATEADD Trunca um valor numérico especificado que tem uma fração decimal. Ele não arredonda o valor do número nessa situação.

date

Uma expressão que pode resolver para um dos seguintes valores:

• date
• datetime
• datetimeoffset
• datetime2
• smalldatetime
• time

Para data, DATEADD aceita uma expressão de coluna, expressão, literal de cadeia de caracteres ou variável definida pelo usuário. Um valor literal de cadeia de caracteres deve ser resolvido para um datetime. Use anos de quatro dígitos para evitar problemas de ambiguidade. Consulte Configuração do servidor: corte de ano de dois dígitos para obter informações sobre anos de dois dígitos.

Tipos de devolução

O tipo de dados de valor de retorno para este método é dinâmico. O tipo de retorno depende do argumento fornecido para date. Se o valor for date for uma string literal date, DATEADD retornará um valor datetime . Se outro tipo de dados de entrada válido for fornecido para date, DATEADD retornará o mesmo tipo de dados. DATEADD gera um erro se a escala de segundos literais da cadeia exceder três posições decimais (.nnn) ou se a cadeia de caracteres literal contiver a parte de deslocamento do fuso horário.

Valor de retorno

Argumento DatePart

dayofyear, daye weekday devolvem o mesmo valor.

Cada datepart e suas abreviaturas retornam o mesmo valor.

Se o seguinte for verdadeiro:

• datepart é month
• o mês de data tem mais dias do que o mês de retorno
• o dia da data não existe no mês de retorno

Em seguida, DATEADD retorna o último dia do mês de retorno. Por exemplo, setembro tem 30 (trinta) dias; Portanto, estas declarações retornam 2024-09-30 00:00:00.000:

SELECT DATEADD(month, 1, '20240830');
SELECT DATEADD(month, 1, '2024-08-31');

Argumento do número

O argumento do número não pode exceder o alcance do bigint. Nas afirmações seguintes, o argumento para o número excede o intervalo de bigint por 1.

DECLARE @datetime2 AS DATETIME2;
SET @datetime2 = '2025-11-01 01:01:01.1111111';
SELECT DATEADD(nanosecond, 9223372036854775808, @datetime2);
SELECT DATEADD(nanosecond, -9223372036854775809, @datetime2);
GO

Essas instruções retornam a seguinte mensagem de erro:

Msg 8115, Level 16, State 2, Line 3
Arithmetic overflow error converting expression to data type bigint.

Argumento de data

DATEADD não aceita um argumento de data incrementado para um valor fora do intervalo de seu tipo de dados. Nas instruções a seguir, o valor do número adicionado ao valor de data excede o intervalo do tipo de dados de data .

SELECT DATEADD(year, 2147483647, '20240731');
SELECT DATEADD(year, -2147483647, '20240731');

DATEADD Retorna a seguinte mensagem de erro:

Msg 517, Level 16, State 1
Line 1 Adding a value to a 'datetime' column caused overflow.

Retornar valores para uma data smalldatetime e uma segunda ou fração de segundos datepart

A parte de segundos de um valor smalldatetime é sempre 00. Para um valor de datasmalldatetime, aplica-se o seguinte:

• Para uma parte de data de , e um valor de secondnúmero entre -30 e +29, DATEADD não faz alterações.

• Para uma dataparte de , e um valor de second menor que -30, ou mais de +29, executa sua adição a partir de DATEADDum minuto.

• Para uma parte da datamillisecond numérico entre -30001 e +29998, DATEADD não faz alterações.

• Para uma parte de data e um valor de millisecond menor que -30001, ou mais de +29998, executa sua adição a partir de DATEADD um minuto.

Remarks

Utilização DATEADD nas seguintes cláusulas:

• GROUP BY
• HAVING
• ORDER BY
• SELECT <list>
• WHERE

Precisão de segundos fracionários

DATEADDnão permite adição para uma parte da data ou microsecond para os tipos de nanosecond dados de datasmalldatetime, date e datetime.

Os milissegundos têm uma escala de 3 (.123), os microssegundos têm uma escala de 6 (.123456), e os nanossegundos têm uma escala de 9 (.123456789). Os tipos de dados time, datetime2 e datetimeoffset têm uma escala máxima de 7 (.1234567). Para uma parte da data do nanosecond, o número deve ser 100 antes da fração de segundos do aumento da data . Um número entre 1 e 49 arredonda para baixo para 0, e um número de 50 para 99 arredonda para 100.

Essas instruções adicionam uma parte da data de millisecond, microsecondou .nanosecond

DECLARE @datetime2 AS DATETIME2 = '2024-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);

Aqui está o conjunto de resultados.

1 millisecond     2024-01-01 13:10:10.1121111
2 milliseconds    2024-01-01 13:10:10.1131111
1 microsecond     2024-01-01 13:10:10.1111121
2 microseconds    2024-01-01 13:10:10.1111131
49 nanoseconds    2024-01-01 13:10:10.1111111
50 nanoseconds    2024-01-01 13:10:10.1111112
150 nanoseconds   2024-01-01 13:10:10.1111113

Deslocamento de fuso horário

DATEADD não permite adição para compensação de fuso horário.

Examples

A. Incrementar datepart por um intervalo de 1

Cada uma dessas instruções incrementa datepart por um intervalo de 1:

DECLARE @datetime2 AS DATETIME2 = '2024-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);

Aqui está o conjunto de resultados.

year         2025-01-01 13:10:10.1111111
quarter      2024-04-01 13:10:10.1111111
month        2024-02-01 13:10:10.1111111
dayofyear    2024-01-02 13:10:10.1111111
day          2024-01-02 13:10:10.1111111
week         2024-01-08 13:10:10.1111111
weekday      2024-01-02 13:10:10.1111111
hour         2024-01-01 14:10:10.1111111
minute       2024-01-01 13:11:10.1111111
second       2024-01-01 13:10:11.1111111
millisecond  2024-01-01 13:10:10.1121111
microsecond  2024-01-01 13:10:10.1111121
nanosecond   2024-01-01 13:10:10.1111111

B. Incrementar mais de um nível de datepart em uma instrução

Cada uma dessas instruções incrementa datepart em um número grande o suficiente para incrementar adicionalmente a próxima datepartmais alta:

DECLARE @datetime2 AS DATETIME2;

SET @datetime2 = '2024-01-01 01:01:01.1111111';

--Statement                                 Result
-------------------------------------------------------------------
SELECT DATEADD(quarter, 4, @datetime2);     --2025-01-01 01:01:01.1111111
SELECT DATEADD(month, 13, @datetime2);      --2025-02-01 01:01:01.1111111
SELECT DATEADD(dayofyear, 366, @datetime2); --2025-01-01 01:01:01.1111111
SELECT DATEADD(day, 366, @datetime2);       --2025-01-01 01:01:01.1111111
SELECT DATEADD(week, 5, @datetime2);        --2024-02-05 01:01:01.1111111
SELECT DATEADD(weekday, 31, @datetime2);    --2024-02-01 01:01:01.1111111
SELECT DATEADD(hour, 23, @datetime2);       --2024-01-02 00:01:01.1111111
SELECT DATEADD(minute, 59, @datetime2);     --2024-01-01 02:00:01.1111111
SELECT DATEADD(second, 59, @datetime2);     --2024-01-01 01:02:00.1111111
SELECT DATEADD(millisecond, 1, @datetime2); --2024-01-01 01:01:01.1121111

C. Use expressões como argumentos para os parâmetros de número e data

Esses exemplos usam diferentes tipos de expressões como argumentos para os parâmetros de número e data . Os exemplos usam o banco de dados AdventureWorks.

Especificar uma coluna como data

Este exemplo adiciona 2 (dois) dias a cada valor na OrderDate coluna, para derivar uma nova coluna chamada PromisedShipDate:

SELECT SalesOrderID,
       OrderDate,
       DATEADD(day, 2, OrderDate) AS PromisedShipDate
FROM Sales.SalesOrderHeader;

Aqui está um conjunto de resultados parciais:

SalesOrderID OrderDate               PromisedShipDate
------------ ----------------------- -----------------------
43659        2005-07-01 00:00:00.000 2005-07-03 00:00:00.000
43660        2005-07-01 00:00:00.000 2005-07-03 00:00:00.000
43661        2005-07-01 00:00:00.000 2005-07-03 00:00:00.000
...
43702        2005-07-02 00:00:00.000 2005-07-04 00:00:00.000
43703        2005-07-02 00:00:00.000 2005-07-04 00:00:00.000
43704        2005-07-02 00:00:00.000 2005-07-04 00:00:00.000
43705        2005-07-02 00:00:00.000 2005-07-04 00:00:00.000
43706        2005-07-03 00:00:00.000 2005-07-05 00:00:00.000
...
43711        2005-07-04 00:00:00.000 2005-07-06 00:00:00.000
43712        2005-07-04 00:00:00.000 2005-07-06 00:00:00.000
...
43740        2005-07-11 00:00:00.000 2005-07-13 00:00:00.000
43741        2005-07-12 00:00:00.000 2005-07-14 00:00:00.000

Especificar variáveis definidas pelo usuário como número e data

Este exemplo especifica variáveis definidas pelo usuário como argumentos para número e data:

DECLARE @days AS INT = 365,
        @datetime AS DATETIME = '2000-01-01 01:01:01.111' /* 2000 was a leap year */;

SELECT DATEADD(day, @days, @datetime);

Aqui está o conjunto de resultados.

2000-12-31 01:01:01.110

Especificar a função do sistema escalar como data

Este exemplo especifica SYSDATETIME a data. O valor exato retornado depende do dia e hora da execução da instrução:

SELECT DATEADD(month, 1, SYSDATETIME());

Aqui está o conjunto de resultados.

2024-04-25 14:29:59.6727944

Especificar subconsultas escalares e funções escalares como número e data

Este exemplo usa subconsultas escalares, MAX(ModifiedDate), como argumentos para número e data. (SELECT TOP 1 BusinessEntityID FROM Person.Person) serve como um argumento artificial para o parâmetro number, para mostrar como selecionar um argumento number de uma lista de valores.

SELECT DATEADD(month,
    (SELECT TOP 1 BusinessEntityID FROM Person.Person),
    (SELECT MAX(ModifiedDate) FROM Person.Person)
);

Especificar expressões numéricas e funções escalares do sistema como número e data

Este exemplo usa uma expressão numérica (-(10 / 2)), operadores unários (-), um operador aritmético (/) e funções escalares do sistema (SYSDATETIME) como argumentos para número e data.

SELECT DATEADD(month, -(10 / 2), SYSDATETIME());

Especificar funções de classificação como número

Este exemplo usa uma função de classificação como um argumento para número.

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;

Especificar uma função de janela agregada como número

Este exemplo usa uma função de janela agregada como um argumento para número.

SELECT SalesOrderID,
       ProductID,
       OrderQty,
       DATEADD(day, SUM(OrderQty) OVER (PARTITION BY SalesOrderID), SYSDATETIME()) AS 'Total'
FROM Sales.SalesOrderDetail
WHERE SalesOrderID IN (43659, 43664);
GO

Conteúdo relacionado

• CAST e CONVERT (Transact-SQL)