SQL - DATE_BUCKET() Function

The SQL DATE_BUCKET() function enables you to group data into groups that correspond to fixed periods of time. According to the arguments supplied to the function, it returns the datetime value that marks the beginning of each datetime bucket.

The Date Bucket function, as its name suggests, computes date buckets with a single defined size. The function will return the start date of the bucket holding the date in the event that it is supplied with a date and the bucket size.

Syntax

Following is the syntax of the SQL DATE_BUCKET() function −

DATE_BUCKET (datepart, number, date, origin)

Parameters

This function accepts four parameters. The same is discussed below −

  • datepart − part of the date that is used with number. Ex. Year, minutes, hours etc.

  • number − it is an integer that going to decide the width of the bucket combined with datepart argument. It should be a positive integer value as it represents the width of the datepart buckets from the origin time.

  • date − DATE_BUCKET accepts an expression, column expressions or user defined variables for date, if they resolved to any of these data types, such as date, datetime, datetime2, datetimeoffset, smalldatetime, time

  • origin − the origin datatype should match the datatype of the date parameter. DATE_BUCKET uses the default origin date value, if no origin value is specified for function.

Example

Let us look into the following example on SQL DATE_BUCKET() function where the width is 1 day wide by using following query −

DECLARE @date date = '2023-02-21',
@origin date = '2023-02-05';
SELECT DATE_BUCKET(DAY, 1, @date, @origin);

Output

When we execute the above query, the output is obtained as follows −

+------------+
| Result     |
+------------+
| 2023-02-21 |
+------------+

Example

Here is another scenario, where we are going to increment the argument to 2,3,4 respectively by using the following query −

DECLARE @date date = '2023-02-21',
@origin date = '2023-02-05';
SELECT 
   DATE_BUCKET(day, 1, @date, @origin) AS "1 day",
   DATE_BUCKET(day, 2, @date, @origin) AS "2 days",
   DATE_BUCKET(day, 3, @date, @origin) AS "3 days",
   DATE_BUCKET(day, 4, @date, @origin) AS "4 days";

Output

When the query gets executed, it will generate the output as shown below −

+------------+------------+------------+------------+
| 1day       | 2 days     | 3 days     | 4 days     |
+------------+------------+------------+------------+
| 2023-02-21 | 2023-02-21 | 2023-02-20 | 2023-02-21 |
+------------+------------+------------+------------+

Example

In the following example, we are going to set a 7 days wide, but we there are only 5 days left between @date and @origin let us look the result by using the following query −

DECLARE 
   @date date = '2023-02-21',
   @origin date = '2023-02-17';
SELECT DATE_BUCKET(day, 7, @date, @origin) AS OriginDate;

Output

On executing the above query, the output is displayed as follows− 

+------------+
| OriginDate |
+------------+
| 2023-02-17 |
+------------+

Example

Let us look into the another scenario, where we are using the 7 days wide, and increasing the gap between the two date and checking the result by using the following query −

DECLARE 
   @date date = '2023-02-21',
   @origin date = '2023-02-10';
SELECT DATE_BUCKET(day, 7, @date, @origin) AS Result;

Output

When the query, gets executed it will generate the output as shown below −

+------------+
| Result     |
+------------+
| 2023-02-17 |
+------------+

Example

Let us look into another example, where we are going to use user defined variables as arguments for number, date and checking the result by running the following query −

DECLARE @days int = 365,
        @datetime datetime2 = '2023-02-21 18:03:59.8684429';;
SELECT Date_Bucket(DAY, @days, @datetime) AS Result;

Output

The output for the above query is produced as given below −

+-----------------------------+
| Result                      |
+-----------------------------+
| 2022-12-02 00:00:00.0000000 |
+-----------------------------+

Example

In the following example we are using the SYSDATETIME() for date by using the following query −

SELECT Date_Bucket(WEEK, 08, SYSDATETIME()) AS Result;

Output

When the query gets executed, it will generate an output as shown below −

+-----------------------------+
| Result                      |
+-----------------------------+
| 2023-02-13 00:00:00.0000000 |
+-----------------------------+

Example

Here is another scenario, where we are using SYSDATETIME() and numeric expression(07/2) as arguments for number and date by using the following query −

SELECT Date_Bucket(WEEK,(07/2), SYSDATETIME()) AS Result;

Output

On running the above query, it will generate an output as shown below −

+-----------------------------+
| Result                      |
+-----------------------------+
| 2023-02-06 00:00:00.0000000 |
+-----------------------------+

Example

Consider the following example, where we are using the non-default origin value for generating the date_bucket by using the following query −

Declare @date datetime2 = '2023-02-21 11:34:22';
declare @origin datetime2 = '2023-01-01 00:00:00';
Select DATE_BUCKET(HOUR, 3, @date, @origin) AS Result;

Output

On running the above query, it will generate an output as shown below −

+-----------------------------+
| Result                      |
+-----------------------------+
| 2023-02-21 09:00:00.0000000 |
+-----------------------------+
sql-date-functions.htm
Advertisements