You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This function returns the date-time value corresponding to the start of each date-time bucket from the timestamp defined by the `origin` parameter, or the default origin value of `1900-01-01 00:00:00.000` if the origin parameter isn't specified.
24
+
This function returns the date-time value corresponding to the start of each date-time bucket from the timestamp defined by the *origin* parameter, or the default origin value of `1900-01-01 00:00:00.000` if the origin parameter isn't specified.
25
25
26
-
See [Date and Time Data Types and Functions (Transact-SQL)](../functions/date-and-time-data-types-and-functions-transact-sql.md) for an overview of all Transact-SQL date and time data types and functions.
26
+
See [Date and time data types and functions](date-and-time-data-types-and-functions-transact-sql.md) for an overview of all Transact-SQL date and time data types and functions.
The part of *date* that is used with the `number` parameter, for example, year, month, day, minute, second.
40
+
The part of *date* that is used with the *number* parameter, for example, **year**, **month**, **day**, **minute**, **second**.
41
41
42
42
`DATE_BUCKET` doesn't accept user-defined variable equivalents for the *datepart* arguments.
43
43
44
-
|*datepart*|Abbreviations|
45
-
|---|---|
46
-
|**day**|**dd**, **d**|
47
-
|**week**|**wk**, **ww**|
48
-
|**month**|**mm**, **m**|
49
-
|**quarter**|**qq**, **q**|
50
-
|**year**|**yy**, **yyyy**|
51
-
|**hour**|**hh**|
52
-
|**minute**|**mi**, **n**|
53
-
|**second**|**ss**, **s**|
54
-
|**millisecond**|**ms**|
44
+
|*datepart*|Abbreviations|
45
+
|---|---|
46
+
|**day**|**dd**, **d**|
47
+
|**week**|**wk**, **ww**|
48
+
|**month**|**mm**, **m**|
49
+
|**quarter**|**qq**, **q**|
50
+
|**year**|**yy**, **yyyy**|
51
+
|**hour**|**hh**|
52
+
|**minute**|**mi**, **n**|
53
+
|**second**|**ss**, **s**|
54
+
|**millisecond**|**ms**|
55
55
56
56
#### *number*
57
57
58
-
The integer number that decides the width of the bucket combined with *datepart* argument. This represents the width of the *datepart* buckets from the origin time. This argument can't be a negative integer value.
58
+
The integer number that decides the width of the bucket combined with *datepart* argument. This argument represents the width of the *datepart* buckets from the origin time. This argument can't be a negative integer value.
59
59
60
60
#### *date*
61
61
62
-
An expression that can resolve to one of the following values:
62
+
An expression that must be one of the following values:
63
63
64
64
-**date**
65
65
-**datetime**
@@ -68,7 +68,7 @@ An expression that can resolve to one of the following values:
68
68
-**smalldatetime**
69
69
-**time**
70
70
71
-
For **date**, `DATE_BUCKET`will accept a column expression, expression, or user-defined variable if they resolve to any of the data types mentioned above.
71
+
For **date**, `DATE_BUCKET`accepts a column expression, expression, or user-defined variable if they resolve to any of the data types mentioned previously.
72
72
73
73
#### *origin*
74
74
@@ -81,112 +81,116 @@ An optional expression that can resolve to one of the following values:
81
81
-**smalldatetime**
82
82
-**time**
83
83
84
-
The data type for `origin` should match the data type of the `date` parameter.
84
+
The data type for *origin* should match the data type of the *date* parameter.
85
85
86
-
`DATE_BUCKET` uses a default origin date value of `1900-01-01 00:00:00.000` that is, 12:00 AM on Monday, January 1, 1900, if no `origin` value is specified for the function.
86
+
`DATE_BUCKET` uses a default origin date value of `1900-01-01 00:00:00.000` that is, 12:00 AM on Monday, January 1, 1900, if no *origin* value is specified for the function.
87
87
88
-
## Return type
88
+
## Return types
89
89
90
-
The return value data type for this method is dynamic. The return type depends on the argument supplied for `date`. If a valid input data type is supplied for `date`, `DATE_BUCKET` returns the same data type. `DATE_BUCKET` raises an error if a string literal is specified for the `date` parameter.
90
+
The return value data type for this method is dynamic. The return type depends on the argument supplied for *date*. If a valid input data type is supplied for *date*, `DATE_BUCKET` returns the same data type. `DATE_BUCKET` raises an error if a string literal is specified for the *date* parameter.
91
91
92
-
## Return values
92
+
## Return value
93
93
94
-
### Understanding the output from `DATE_BUCKET`
94
+
### Understand the output from DATE_BUCKET
95
95
96
-
`DATE_BUCKET` returns the latest date or time value, corresponding to the *datepart* and *number* parameter. For example, in the expressions below, `DATE_BUCKET`will return the output value of `2020-04-13 00:00:00.0000000`, as the output is calculated based on one week buckets from the default origin time of `1900-01-01 00:00:00.000`. The value `2020-04-13 00:00:00.0000000` is 6,276 weeks from the origin value of `1900-01-01 00:00:00.000`.
96
+
`DATE_BUCKET` returns the latest date or time value, corresponding to the *datepart* and *number* parameter. For example, in the following expressions, `DATE_BUCKET`returns the output value of `2020-04-13 00:00:00.0000000`, as the output is calculated based on one week buckets from the default origin time of `1900-01-01 00:00:00.000`. The value `2020-04-13 00:00:00.0000000` is 6,276 weeks from the origin value of `1900-01-01 00:00:00.000`.
97
97
98
98
```sql
99
-
DECLARE @date DATETIME2 ='2020-04-15 21:22:11';
99
+
DECLARE @dateAS DATETIME2 ='2020-04-15 21:22:11';
100
+
100
101
SELECT DATE_BUCKET(WEEK, 1, @date);
101
102
```
102
103
103
-
For all the expressions below, the same output value of `2020-04-13 00:00:00.0000000`will be returned. This is because `2020-04-13 00:00:00.0000000` is 6,276 weeks from the origin date, and 6,276 is divisible by 2, 3, 4 and 6.
104
+
For all the following expressions, the same output value of `2020-04-13 00:00:00.0000000`is returned. This is because `2020-04-13 00:00:00.0000000` is 6,276 weeks from the origin date, and 6,276 is divisible by 2, 3, 4 and 6.
104
105
105
106
```sql
106
-
DECLARE @date DATETIME2 ='2020-04-15 21:22:11';
107
+
DECLARE @dateAS DATETIME2 ='2020-04-15 21:22:11';
108
+
107
109
SELECT DATE_BUCKET(WEEK, 2, @date);
108
110
SELECT DATE_BUCKET(WEEK, 3, @date);
109
111
SELECT DATE_BUCKET(WEEK, 4, @date);
110
112
SELECT DATE_BUCKET(WEEK, 6, @date);
111
113
```
112
114
113
-
The output for the expression below is `2020-04-06 00:00:00.0000000`, which is 6275 weeks from the default origin time `1900-01-01 00:00:00.000`.
115
+
The output for the following expression is `2020-04-06 00:00:00.0000000`, which is 6,275 weeks from the default origin time `1900-01-01 00:00:00.000`.
114
116
115
117
```sql
116
-
DECLARE @date DATETIME2 ='2020-04-15 21:22:11';
118
+
DECLARE @dateAS DATETIME2 ='2020-04-15 21:22:11';
119
+
117
120
SELECT DATE_BUCKET(WEEK, 5, @date);
118
121
```
119
122
120
-
The output for the expression below is `2020-06-09 00:00:00.0000000`, which is 75 weeks from the specified origin time `2019-01-01 00:00:00`.
123
+
The output for the following expression is `2020-06-09 00:00:00.0000000`, which is 75 weeks from the specified origin time `2019-01-01 00:00:00`.
121
124
122
125
```sql
123
-
DECLARE @date DATETIME2 ='2020-06-15 21:22:11';
124
-
DECLARE @origin DATETIME2 ='2019-01-01 00:00:00';
126
+
DECLARE @dateAS DATETIME2 ='2020-06-15 21:22:11';
127
+
DECLARE @origin AS DATETIME2 ='2019-01-01 00:00:00';
128
+
125
129
SELECT DATE_BUCKET(WEEK, 5, @date, @origin);
126
130
```
127
131
128
-
## datepart argument
132
+
## The *datepart* argument
129
133
130
134
**dayofyear**, **day**, and **weekday** return the same value. Each *datepart* and its abbreviations return the same value.
131
135
132
-
## number argument
136
+
## The *number* argument
133
137
134
-
The *number* argument can't exceed the range of positive **int** values. In the following statements, the argument for *number* exceeds the range of **int** by 1. The following statement returns the error message,`Msg 8115, Level 16, State 2, Line 2. Arithmetic overflow error converting expression to data type int.`
138
+
The *number* argument can't exceed the range of positive **int** values. In the following statements, the argument for *number* exceeds the range of **int** by 1. The following statement returns the error message:`Msg 8115, Level 16, State 2, Line 2. Arithmetic overflow error converting expression to data type int.`
135
139
136
140
```sql
137
-
DECLARE @date DATETIME2 ='2020-04-30 00:00:00';
141
+
DECLARE @dateAS DATETIME2 ='2020-04-30 00:00:00';
142
+
138
143
SELECT DATE_BUCKET(DAY, 2147483648, @date);
139
144
```
140
145
141
-
If a negative value for number is passed to the `DATE_BUCKET` function, the following error will be returned.
146
+
If a negative value for number is passed to the `DATE_BUCKET` function, the following error is returned.
142
147
143
148
```text
144
149
Msg 9834, Level 16, State 1, Line 1
145
150
Invalid bucket width value passed to DATE_BUCKET function. Only positive values are allowed.
146
151
```
147
152
148
-
## date argument
153
+
## The *date* argument
149
154
150
-
`DATE_BUCKET` return the base value corresponding to the data type of the `date` argument. In the following example, an output value with datetime2 datatype is returned.
155
+
`DATE_BUCKET` return the base value corresponding to the data type of the *date* argument. In the following example, an output value with datetime2 data type is returned.
151
156
152
157
```sql
153
158
SELECT DATE_BUCKET(DAY, 10, SYSUTCDATETIME());
154
159
```
155
160
156
-
## origin argument
161
+
## The *origin* argument
157
162
158
-
The data type of the `origin` and `date` arguments in must be the same. If different data types are used, an error will be generated.
163
+
The data type of the *origin* and *date* arguments in must be the same. If different data types are used, an error is generated.
#### Specify scalar subqueries and scalar functions as number and date
268
271
269
-
This example uses scalar subqueries, `MAX(OrderDate)`, as arguments for *number* and *date*. `(SELECT top 1 CustomerKey FROM dbo.DimCustomer where GeographyKey > 100)` serves as an artificial argument for the number parameter, to show how to select a *number* argument from a value list.
272
+
This example uses scalar subqueries, `MAX(OrderDate)`, as arguments for *number* and *date*. `(SELECT TOP 1 CustomerKey FROM dbo.DimCustomer WHERE GeographyKey > 100)` serves as an artificial argument for the number parameter, to show how to select a *number* argument from a value list.
270
273
271
274
```sql
272
275
SELECT DATE_BUCKET(WEEK, (
273
276
SELECT TOP 1 CustomerKey
274
277
FROMdbo.DimCustomer
275
-
WHERE GeographyKey >100
276
-
), (
277
-
SELECTMAX(OrderDate)
278
-
FROMdbo.FactInternetSales
279
-
));
278
+
WHERE GeographyKey >100),
279
+
(
280
+
SELECTMAX(OrderDate)
281
+
FROMdbo.FactInternetSales
282
+
)
283
+
);
280
284
```
281
285
282
286
#### Specify numeric expressions and scalar system functions as number and date
283
287
284
-
This example uses a numeric expression ((10/2)), and scalar system functions (`SYSDATETIME`) as arguments for number and date.
288
+
This example uses a numeric expression (`(10/2)`), and scalar system functions (`SYSDATETIME`) as arguments for *number* and *date*.
285
289
286
290
```sql
287
-
SELECT DATE_BUCKET(WEEK, (10/2), SYSDATETIME());
291
+
SELECT DATE_BUCKET(WEEK, (10/2), SYSDATETIME());
288
292
```
289
293
290
294
#### Specify an aggregate window function as number
291
295
292
296
This example uses an aggregate window function as an argument for *number*.
293
297
294
298
```sql
295
-
SELECT DISTINCT DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2)) AS DateBucket
296
-
, FIRST_VALUE([SalesOrderNumber]) OVER (
299
+
SELECT DISTINCT DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2)) AS DateBucket,
300
+
FIRST_VALUE([SalesOrderNumber]) OVER (
297
301
ORDER BY DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2))
298
-
) AS First_Value_In_Bucket
299
-
, LAST_VALUE([SalesOrderNumber]) OVER (
302
+
) AS First_Value_In_Bucket,
303
+
LAST_VALUE([SalesOrderNumber]) OVER (
300
304
ORDER BY DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2))
301
-
) AS Last_Value_In_Bucket
305
+
) AS Last_Value_In_Bucket
302
306
FROM [dbo].[FactInternetSales]
303
-
WHERE ShipDate BETWEEN '2011-01-03 00:00:00.000'
304
-
AND'2011-02-28 00:00:00.000'
307
+
WHERE ShipDate BETWEEN '2011-01-03 00:00:00.000'AND'2011-02-28 00:00:00.000'
305
308
ORDER BY DateBucket;
306
309
GO
307
310
```
@@ -311,13 +314,14 @@ GO
311
314
This example uses a non-default origin value to generate the date buckets.
312
315
313
316
```sql
314
-
DECLARE @date DATETIME2 ='2020-06-15 21:22:11';
315
-
DECLARE @origin DATETIME2 ='2019-01-01 00:00:00';
317
+
DECLARE @dateAS DATETIME2 ='2020-06-15 21:22:11';
318
+
DECLARE @origin AS DATETIME2 ='2019-01-01 00:00:00';
319
+
316
320
SELECT DATE_BUCKET(HOUR, 2, @date, @origin);
317
321
```
318
322
319
-
## See also
323
+
## Related content
320
324
321
-
-[CAST and CONVERT (Transact-SQL)](../functions/cast-and-convert-transact-sql.md)
325
+
-[CAST and CONVERT (Transact-SQL)](cast-and-convert-transact-sql.md)
322
326
-[Date and time types](../data-types/date-and-time-types.md)
323
327
-[Date and time data types and functions (Transact-SQL)](date-and-time-data-types-and-functions-transact-sql.md)
0 commit comments