DATEADD (Transact-SQL)

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics PDW (Analytics Platform System) Ponto de extremidade de análise do SQL Warehouse no Microsoft Fabric

Essa função adiciona um número (um inteiro com sinal) a um datepart de uma data de entrada e retorna um valor de data/hora modificado. Por exemplo, você pode usar essa função para localizar a data que é de 7.000 minutos a partir de hoje: número = 7000, datepart = minuto, data = hoje.

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

Convenções de sintaxe de Transact-SQL

Sintaxe

DATEADD (datepart , number , date )

Argumentos

datepart

A parte da data à qual DATEADD adiciona um número int. Esta tabela lista todos os argumentos datepart válidos.

Observação

DATEADD não aceita os equivalentes de variável definidos pelo usuário para os argumentos datepart.

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 DATEADD adiciona a um datepart de date. DATEADD aceita valores de variável definidos pelo usuário para número. DATEADD trunca um valor específico de número 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 um dos seguintes valores:

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

Para date, 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 resolver um datetime. Para evitar ambiguidade, use anos de quatro dígitos. Consulte Configurar o corte de ano de dois dígitos (opção de configuração do servidor) para obter informações sobre anos de dois dígitos.

Tipos de retorno

O tipo de dados do valor retornado para esse método é dinâmico. O tipo de retorno depende do argumento fornecido para date. Se o valor para date for uma data literal de cadeia de caracteres, 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 gerará um erro se a escala de segundos do literal de cadeia de caracteres exceder três casas decimais (,nnn) ou se o literal de cadeia de caracteres contiver a parte de deslocamento de fuso horário.

Valor retornado

Argumento datepart

dayofyear, daye weekday retorna o mesmo valor.

Cada datepart retorna o mesmo valor das abreviações dela.

Se as seguintes condições forem verdadeiras:

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

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

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

Argumento number

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. Essas duas instruções retornam a seguinte mensagem de erro: Msg 8115, Level 16, State 2, Line 1. Arithmetic overflow error converting expression to data type int.

SELECT DATEADD(year, 2147483648, '20240731');
SELECT DATEADD(year, -2147483649, '20240731');

Argumento date

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 number adicionado ao valor de date excede o intervalo do tipo de dados date. DATEADD retorna a seguinte mensagem de erro: Msg 517, Level 16, State 1, Line 1 Adding a value to a 'datetime' column caused overflow.

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

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

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

  • Para uma dataparte de , e um valor numérico second entre -30 e +29, DATEADD não faz alterações.

  • Para uma dataparte de second, e um valor numérico menor que -30 ou maior que +29, DATEADD executa sua adição começando em um minuto.

  • Para uma dataparte de e um valor numérico millisecond entre -30001 e +29998, DATEADD não faz alterações.

  • Para uma parte de data e millisecond um valor numérico menor que -30001 ou maior que +29998, DATEADD executa sua adição começando em um minuto.

Comentários

Use DATEADD nas seguintes cláusulas:

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

Precisão de segundos fracionários

DATEADDNão permite a adição de um datePart de ou nanosecond para tipos de dados de microsecond data smallDateTime, 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 dataparte de nanosecond, o número deve ser 100 antes do aumento de segundos fracionários de data . Um número entre 1 e 49 arredonda para baixo para 0 e um número de 50 a 99 arredonda para 100.

Essas instruções adicionam uma dataparte de millisecond, microsecond, ou nanosecond.

DECLARE @datetime2 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);

Veja a seguir 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 deslocamento de fuso horário.

Exemplos

R. Incrementar datepart em um intervalo de 1

Cada uma destas instruções incrementa datepart em um intervalo de 1:

DECLARE @datetime2 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);

Veja a seguir 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 destas instruções incrementa datepart em um número grande o suficiente para também incrementar a próxima datepart mais alta de date:

DECLARE @datetime2 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. Usar expressões como argumentos para os parâmetros number e date

Estes exemplos usam diferentes tipos de expressões como argumentos para os parâmetros number e date. Os exemplos usam o banco de dados AdventureWorks.

Especificar uma coluna como data

Este exemplo adiciona 2 (dois) dias a cada valor na coluna OrderDate 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 INT = 365,
    @datetime DATETIME = '2000-01-01 01:01:01.111'; /* 2000 was a leap year */;

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

Veja a seguir o conjunto de resultados.

2000-12-31 01:01:01.110

Especificar a função do sistema escalar como data

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

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

Veja a seguir o conjunto de resultados.

2024-04-25 14:29:59.6727944

Especificar subconsultas 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) funciona como um argumento artificial do parâmetro de número que mostra como selecionar um argumento number em 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 do sistema escalares 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 do sistema escalar (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 number.

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 de agregação como número

Este exemplo usa uma função de janela de agregação como um argumento para number.

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