Skip to content

Commit 5a333e8

Browse files
ktoliverktoliver
authored
Merge pull request #665 from fbsolo/patch-9
Update dateadd-transact-sql.md
2 parents 305616d + 850370c commit 5a333e8

1 file changed

Lines changed: 67 additions & 43 deletions

File tree

‎docs/t-sql/functions/dateadd-transact-sql.md‎

Lines changed: 67 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
---
1+
---
22
title: "DATEADD (Transact-SQL) | Microsoft Docs"
33
ms.custom: ""
44
ms.date: "07/29/2017"
@@ -35,9 +35,9 @@ monikerRange: ">= aps-pdw-2016 || = azuresqldb-current || = azure-sqldw-latest |
3535
# DATEADD (Transact-SQL)
3636
[!INCLUDE[tsql-appliesto-ss2008-all-md](../../includes/tsql-appliesto-ss2008-all-md.md)]
3737

38-
Returns a specified *date* with the specified *number* interval (signed integer) added to a specified *datepart* of that *date*.
38+
This function adds a specified *number* value (as a signed integer) to a specified *datepart* of an input *date* value, and then returns that modified value.
3939

40-
For an overview of all [!INCLUDE[tsql](../../includes/tsql-md.md)] date and time data types and functions, see [Date and Time Data Types and Functions (Transact-SQL)](../../t-sql/functions/date-and-time-data-types-and-functions-transact-sql.md).
40+
See [Date and Time Data Types and Functions (Transact-SQL)](../../t-sql/functions/date-and-time-data-types-and-functions-transact-sql.md) for an overview of all [!INCLUDE[tsql](../../includes/tsql-md.md)] date and time data types and functions.
4141

4242
![Topic link icon](../../database-engine/configure-windows/media/topic-link.gif "Topic link icon") [Transact-SQL Syntax Conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
4343

@@ -49,7 +49,10 @@ DATEADD (datepart , number , date )
4949

5050
## Arguments
5151
*datepart*
52-
Is the part of *date* to which an **integer***number* is added. The following table lists all valid *datepart* arguments. User-defined variable equivalents are not valid.
52+
The part of *date* to which `DATEADD` adds an **integer** *number*. This table lists all valid *datepart* arguments.
53+
54+
> [!NOTE]
55+
> `DATEADD` does not accept user-defined variable equivalents for the *datepart* arguments.
5356
5457
|*datepart*|Abbreviations|
5558
|---|---|
@@ -68,15 +71,22 @@ Is the part of *date* to which an **integer***number* is added. The following ta
6871
|**nanosecond**|**ns**|
6972

7073
*number*
71-
Is an expression that can be resolved to an [int](../../t-sql/data-types/int-bigint-smallint-and-tinyint-transact-sql.md) that is added to a *datepart* of *date*. User-defined variables are valid.
72-
If you specify a value with a decimal fraction, the fraction is truncated and not rounded.
74+
An expression that can resolve to an [int](../../t-sql/data-types/int-bigint-smallint-and-tinyint-transact-sql.md) that `DATEADD` adds to a *datepart* of *date*. `DATEADD` accepts user-defined variable values for *number*. `DATEADD` will truncate a specified *number* value that has a decimal fraction. It will not round the *number* value in this situation.
7375

7476
*date*
75-
Is an expression that can be resolved to a **time**, **date**, **smalldatetime**, **datetime**, **datetime2**, or **datetimeoffset** value. *date* can be an expression, column expression, user-defined variable, or string literal. If the expression is a string literal, it must resolve to a **datetime**. To avoid ambiguity, use four-digit years. For information about two-digit years, see [Configure the two digit year cutoff Server Configuration Option](../../database-engine/configure-windows/configure-the-two-digit-year-cutoff-server-configuration-option.md).
77+
An expression that can resolve to one of the following values:
78+
79+
+ **date**
80+
+ **datetime**
81+
+ **datetimeoffset**
82+
+ **datetime2**
83+
+ **smalldatetime**
84+
+ **time**
85+
86+
For *date*, `DATEADD` will accept a column expression, expression, string literal, or user-defined variable. A string literal value must resolve to a **datetime**. Use four-digit years to avoid ambiguity issues. See [Configure the two digit year cutoff Server Configuration Option](../../database-engine/configure-windows/configure-the-two-digit-year-cutoff-server-configuration-option.md) for information about two-digit years.
7687

7788
## Return types
78-
The return data type is the data type of the *date* argument, except for string literals.
79-
The return data type for a string literal is **datetime**. An error will be raised if the string literal seconds scale is more than three positions (.nnn) or contains the time zone offset part.
89+
The *date* argument data type becomes the `DATEADD` return value data type, except for string literal *date* values. For a string literal, `DATEADD` returns a **datetime** value. `DATEADD` will raise an error if the string literal seconds scale exceeds three decimal place positions (.nnn) or if the string literal contains the time zone offset part.
8090

8191
## Return Value
8292

@@ -85,45 +95,58 @@ The return data type for a string literal is **datetime**. An error will be rais
8595

8696
Each *datepart* and its abbreviations return the same value.
8797

88-
If *datepart* is **month** and the *date* month has more days than the return month and the *date* day does not exist in the return month, the last day of the return month is returned. For example, September has 30 days; therefore, the two following statements return 2006-09-30 00:00:00.000:
98+
If the following are true:
99+
100+
+ *datepart* is **month**
101+
+ the *date* month has more days than the return month
102+
+ the *date* day does not exist in the return month
103+
104+
Then, `DATEADD` returns the last day of the return month. For example, September has 30 (thirty) days; therefore, these statements return 2006-09-30 00:00:00.000:
89105

90106
```sql
91107
SELECT DATEADD(month, 1, '20060830');
92108
SELECT DATEADD(month, 1, '20060831');
93109
```
94110

95111
## number Argument
96-
The *number* argument cannot exceed the range of **int**. In the following statements, the argument for *number* exceeds the range of **int** by 1. The following error message is returned: "`Msg 8115, Level 16, State 2, Line 1. Arithmetic overflow error converting expression to data type int."`
112+
The *number* argument cannot exceed the range of **int**. In the following statements, the argument for *number* exceeds the range of **int** by 1. These statements both return the following error message: "`Msg 8115, Level 16, State 2, Line 1. Arithmetic overflow error converting expression to data type int."`
97113

98114
```sql
99115
SELECT DATEADD(year,2147483648, '20060731');
100116
SELECT DATEADD(year,-2147483649, '20060731');
101117
```
102118

103119
## date Argument
104-
The *date* argument cannot be incremented to a value outside the range of its data type. In the following statements, the *number* value that is added to the *date* value exceeds the range of the *date* data type. The following error message is returned: "`Msg 517, Level 16, State 1, Line 1 Adding a value to a 'datetime' column caused overflow`."
120+
`DATEADD` will not accept a *date* argument incremented to a value outside the range of its data type. In the following statements, the *number* value added to the *date* value exceeds the range of the *date* data type. `DATEADD` returns the following error message: "`Msg 517, Level 16, State 1, Line 1 Adding a value to a 'datetime' column caused overflow`."
105121

106122
```sql
107123
SELECT DATEADD(year,2147483647, '20060731');
108124
SELECT DATEADD(year,-2147483647, '20060731');
109125
```
110126

111127
## Return Values for a smalldatetime date and a second or Fractional Seconds datepart
112-
The seconds part of a [smalldatetime](../../t-sql/data-types/smalldatetime-transact-sql.md) value is always 00. If *date* is **smalldatetime**, the following apply:
113-
- If *datepart* is **second** and *number* is between -30 and +29, no addition is performed.
114-
- If *datepart* is **second** and *number* is less than-30 or more than +29, addition is performed beginning at one minute.
115-
- If *datepart* is **millisecond** and *number* is between -30001 and +29998, no addition is performed.
116-
- If *datepart* is **millisecond** and *number* is less than -30001 or more than +29998, addition is performed beginning at one minute.
128+
The seconds part of a [smalldatetime](../../t-sql/data-types/smalldatetime-transact-sql.md) value is always 00. For a **smalldatetime** *date* value, the following apply:
129+
130+
- For a *datepart* of **second**, and a *number* value between -30 and +29, `DATEADD` makes no changes.
131+
- For a *datepart* of **second**, and a *number* value less than -30, or more than +29, `DATEADD` performs its addition beginning at one minute.
132+
- For a *datepart* of **millisecond** and a *number* value between -30001 and +29998, `DATEADD` makes no changes.
133+
- For a *datepart* of **millisecond** and a *number* value less than -30001, or more than +29998, `DATEADD` performs its addition beginning at one minute.
117134

118135
## Remarks
119-
DATEADD can be used in the SELECT \<list>, WHERE, HAVING, GROUP BY and ORDER BY clauses.
136+
Use `DATEADD` in the following clauses:
137+
138+
+ GROUP BY
139+
+ HAVING
140+
+ ORDER BY
141+
+ SELECT \<list>
142+
+ WHERE
120143

121144
## Fractional seconds precision
122-
Addition for a *datepart* of **microsecond** or **nanosecond** for *date* data types **smalldatetime**, **date**, and **datetime** is not allowed.
145+
`DATEADD` does not allow addition for a *datepart* of **microsecond** or **nanosecond** for *date* data types **smalldatetime**, **date**, and **datetime**.
123146

124-
Milliseconds have a scale of 3 (.123), microseconds have a scale of 6 (.123456), And nanoseconds have a scale of 9 (.123456789). The **time**, **datetime2**, and **datetimeoffset** data types have a maximum scale of 7 (.1234567). If *datepart* is **nanosecond**, *number* must be 100 before the fractional seconds of *date* increase. A *number* between 1 and 49 is rounded down to 0 and a number from 50 to 99 is rounded up to 100.
147+
Milliseconds have a scale of 3 (.123), microseconds have a scale of 6 (.123456), and nanoseconds have a scale of 9 (.123456789). The **time**, **datetime2**, and **datetimeoffset** data types have a maximum scale of 7 (.1234567). For a *datepart* of **nanosecond**, *number* must be 100 before the fractional seconds of *date* increase. A *number* between 1 and 49 will round down to 0, and a number from 50 to 99 rounds up to 100.
125148

126-
The following statements add a *datepart* of **millisecond**, **microsecond**, or **nanosecond**.
149+
These statements add a *datepart* of **millisecond**, **microsecond**, or **nanosecond**.
127150

128151
```sql
129152
DECLARE @datetime2 datetime2 = '2007-01-01 13:10:10.1111111';
@@ -155,12 +178,12 @@ SELECT '150 nanoseconds', DATEADD(nanosecond,150,@datetime2);
155178
```
156179

157180
## Time zone offset
158-
Addition is not allowed for time zone offset.
181+
`DATEADD` does not allow addition for time zone offset.
159182

160183
## Examples
161184

162185
### A. Incrementing datepart by an interval of 1
163-
Each of the following statements increments *datepart* by an interval of 1.
186+
Each of these statements increments *datepart* by an interval of 1:
164187

165188
```sql
166189
DECLARE @datetime2 datetime2 = '2007-01-01 13:10:10.1111111';
@@ -210,30 +233,30 @@ nanosecond 2007-01-01 13:10:10.1111111
210233
```
211234

212235
### B. Incrementing more than one level of datepart in one statement
213-
Each of the following statements increments *datepart* by a *number* large enough to also increment the next higher *datepart* of *date*.
236+
Each of these statements increments *datepart* by a *number* large enough to additionally increment the next higher *datepart* of *date*:
214237

215238
```sql
216239
DECLARE @datetime2 datetime2;
217240
SET @datetime2 = '2007-01-01 01:01:01.1111111';
218241
--Statement Result
219242
-------------------------------------------------------------------
220-
SELECT DATEADD(quarter,4,@datetime2); --2008-01-01 01:01:01.110
221-
SELECT DATEADD(month,13,@datetime2); --2008-02-01 01:01:01.110
222-
SELECT DATEADD(dayofyear,365,@datetime2); --2008-01-01 01:01:01.110
223-
SELECT DATEADD(day,365,@datetime2); --2008-01-01 01:01:01.110
224-
SELECT DATEADD(week,5,@datetime2); --2007-02-05 01:01:01.110
225-
SELECT DATEADD(weekday,31,@datetime2); --2007-02-01 01:01:01.110
226-
SELECT DATEADD(hour,23,@datetime2); --2007-01-02 00:01:01.110
227-
SELECT DATEADD(minute,59,@datetime2); --2007-01-01 02:00:01.110
228-
SELECT DATEADD(second,59,@datetime2); --2007-01-01 01:02:00.110
229-
SELECT DATEADD(millisecond,1,@datetime2); --2007-01-01 01:01:01.110
243+
SELECT DATEADD(quarter,4,@datetime2); --2008-01-01 01:01:01.1111111
244+
SELECT DATEADD(month,13,@datetime2); --2008-02-01 01:01:01.1111111
245+
SELECT DATEADD(dayofyear,365,@datetime2); --2008-01-01 01:01:01.1111111
246+
SELECT DATEADD(day,365,@datetime2); --2008-01-01 01:01:01.1111111
247+
SELECT DATEADD(week,5,@datetime2); --2007-02-05 01:01:01.1111111
248+
SELECT DATEADD(weekday,31,@datetime2); --2007-02-01 01:01:01.1111111
249+
SELECT DATEADD(hour,23,@datetime2); --2007-01-02 00:01:01.1111111
250+
SELECT DATEADD(minute,59,@datetime2); --2007-01-01 02:00:01.1111111
251+
SELECT DATEADD(second,59,@datetime2); --2007-01-01 01:02:00.1111111
252+
SELECT DATEADD(millisecond,1,@datetime2); --2007-01-01 01:01:01.1121111
230253
```
231254

232255
### C. Using expressions as arguments for the number and date parameters
233-
The following examples use different types of expressions as arguments for the *number* and *date* parameters. The examples use the AdventureWorks database.
256+
These examples use different types of expressions as arguments for the *number* and *date* parameters. The examples use the AdventureWorks database.
234257

235258
#### Specifying a column as date
236-
The following example adds `2` days to each value in the `OrderDate` column to derive a new column named `PromisedShipDate`.
259+
This example adds `2` (two) days to each value in the `OrderDate` column, to derive a new column named `PromisedShipDate`:
237260

238261
```sql
239262
SELECT SalesOrderID
@@ -242,7 +265,7 @@ SELECT SalesOrderID
242265
FROM Sales.SalesOrderHeader;
243266
```
244267

245-
Here is a partial result set.
268+
A partial result set:
246269

247270
```sql
248271
SalesOrderID OrderDate PromisedShipDate
@@ -266,7 +289,7 @@ SalesOrderID OrderDate PromisedShipDate
266289
```
267290

268291
#### Specifying user-defined variables as number and date
269-
The following example specifies user-defined variables as arguments for *number* and *date*.
292+
This example specifies user-defined variables as arguments for *number* and *date*:
270293

271294
```sql
272295
DECLARE @days int = 365,
@@ -284,7 +307,8 @@ SELECT DATEADD(day, @days, @datetime);
284307
```
285308

286309
#### Specifying scalar system function as date
287-
The following example specifies `SYSDATETIME` for *date*.
310+
This example specifies `SYSDATETIME` for *date*. The exact value returned depends on the
311+
day and time of statement execution:
288312

289313
```sql
290314
SELECT DATEADD(month, 1, SYSDATETIME());
@@ -300,22 +324,22 @@ SELECT DATEADD(month, 1, SYSDATETIME());
300324
```
301325

302326
#### Specifying scalar subqueries and scalar functions as number and date
303-
The following example uses scalar subqueries, `MAX(ModifiedDate)`, as arguments for *number* and *date*. `(SELECT TOP 1 BusinessEntityID FROM Person.Person)` is an artificial argument for the number parameter to show how to select a *number* argument from a value list.
327+
This example uses scalar subqueries, `MAX(ModifiedDate)`, as arguments for *number* and *date*. `(SELECT TOP 1 BusinessEntityID FROM Person.Person)` serves as an artificial argument for the number parameter, to show how to select a *number* argument from a value list.
304328

305329
```sql
306330
SELECT DATEADD(month,(SELECT TOP 1 BusinessEntityID FROM Person.Person),
307331
(SELECT MAX(ModifiedDate) FROM Person.Person));
308332
```
309333

310334
#### Specifying numeric expressions and scalar system functions as number and date
311-
The following example uses a numeric expression (-`(10/2))`, [unary operators](../../mdx/unary-operators.md) (`-`), an [arithmetic operator](../../mdx/arithmetic-operators.md) (`/`), and scalar system functions (`SYSDATETIME`) as arguments for *number* and *date*.
335+
This example uses a numeric expression (-`(10/2))`, [unary operators](../../mdx/unary-operators.md) (`-`), an [arithmetic operator](../../mdx/arithmetic-operators.md) (`/`), and scalar system functions (`SYSDATETIME`) as arguments for *number* and *date*.
312336

313337
```sql
314338
SELECT DATEADD(month,-(10/2), SYSDATETIME());
315339
```
316340

317341
#### Specifying ranking functions as number
318-
The following example uses a ranking function as arguments for *number*.
342+
This example uses a ranking function as an argument for *number*.
319343

320344
```sql
321345
SELECT p.FirstName, p.LastName
@@ -331,7 +355,7 @@ WHERE TerritoryID IS NOT NULL
331355
```
332356

333357
#### Specifying an aggregate window function as number
334-
The following example uses an aggregate window function as an argument for *number*.
358+
This example uses an aggregate window function as an argument for *number*.
335359

336360
```sql
337361
SELECT SalesOrderID, ProductID, OrderQty

0 commit comments

Comments
 (0)