DATE_BUCKET(Transact-SQL)

적용 대상: SQL Server 2022(16.x) Azure SQL Database Azure SQL Managed Instance Azure SQL Edge

이 함수는 origin 매개 변수가 지정되지 않은 경우 origin 매개 변수로 정의된 타임스탬프 또는 1900-01-01 00:00:00.000의 기본 origin 값에서 각 date-time 버킷의 시작에 해당하는 date-time 값을 반환합니다.

모든 Transact-SQL 날짜/시간 데이터 형식 및 함수에 대한 개요는 날짜 및 시간 데이터 형식 및 함수(Transact-SQL)를 참조하세요.

Transact-SQL 구문 표기 규칙

구문

DATE_BUCKET (datepart, number, date [, origin ] )

인수

datepart

number 매개 변수와 함께 사용하는 날짜 부분(예: year, month, day, minute, second)입니다.

DATE_BUCKET에서는 datepart 인수에 해당하는 사용자 정의 변수 항목을 허용하지 않습니다.

datepart	약어
day	dd, d
week	wk, ww
month	mm, m
quarter	qq, q
year	yy, yyyy
hour	hh
minute	mi, n
second	ss, s
millisecond	ms

number

datepart 인수와 결합된 버킷의 너비를 결정하는 정수입니다. 원본 시간으로부터의 datepart 버킷 너비를 나타냅니다. 이 인수는 음수 정수 값일 수 없습니다.

date

다음 값 중 하나를 확인할 수 있는 식입니다.

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

date의 경우 위에서 언급한 데이터 형식 중 하나를 확인하는 경우 DATE_BUCKET은 열 식, 식 또는 사용자 정의 변수를 허용합니다.

origin

다음 값 중 하나를 확인할 수 있는 선택적 식입니다.

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

origin의 데이터 형식은 date 매개 변수의 데이터 형식과 일치해야 합니다.

함수에 대해 origin 값이 지정되지 않은 경우 DATE_BUCKET에서는 1900-01-01 00:00:00.000의 기본 원본 날짜 값(1900년 1월 1일 월요일 오전 12:00)을 사용합니다.

반환 형식

이 메서드의 반환 값 데이터 형식은 동적입니다. 반환 형식은 date에 제공된 인수의 따라 달라집니다. date에 대해 유효한 입력 데이터 형식이 제공되면 DATE_BUCKET이 동일한 데이터 형식을 반환합니다. DATE_BUCKET은 date 매개 변수에 문자열 리터럴이 지정된 경우 오류를 발생시킵니다.

반환 값

DATE_BUCKET의 출력 이해

DATE_BUCKET은 datepart 및 number 매개 변수에 해당하는 최신 날짜 또는 시간 값을 반환합니다. 예를 들어 아래 식에서 DATE_BUCKET은 1900-01-01 00:00:00.000의 기본 원본 시간에서 1주 버킷을 기반으로 출력이 계산되기 때문에 2020-04-13 00:00:00.0000000의 출력 값을 반환합니다. 2020-04-13 00:00:00.0000000 값은 1900-01-01 00:00:00.000의 원본 값 기준 6,276주입니다.

DECLARE @date DATETIME2 = '2020-04-15 21:22:11';
SELECT DATE_BUCKET(WEEK, 1, @date);

아래의 모든 식에서 2020-04-13 00:00:00.0000000의 동일한 출력 값이 반환됩니다. 2020-04-13 00:00:00.0000000은 원본 날짜 기준 6,276주이며 6,276은 2, 3, 4, 6으로 나뉘기 때문입니다.

DECLARE @date DATETIME2 = '2020-04-15 21:22:11';
SELECT DATE_BUCKET(WEEK, 2, @date);
SELECT DATE_BUCKET(WEEK, 3, @date);
SELECT DATE_BUCKET(WEEK, 4, @date);
SELECT DATE_BUCKET(WEEK, 6, @date);

아래 식의 출력은 2020-04-06 00:00:00.0000000이며, 기본 origin 시간인 1900-01-01 00:00:00.000으로부터 6275주입니다.

DECLARE @date DATETIME2 = '2020-04-15 21:22:11';
SELECT DATE_BUCKET(WEEK, 5, @date);

아래 식의 출력은 2020-06-09 00:00:00.0000000이며, 지정된 origin 시간인 2019-01-01 00:00:00으로부터 75주입니다.

DECLARE @date DATETIME2 = '2020-06-15 21:22:11';
DECLARE @origin DATETIME2 = '2019-01-01 00:00:00';
SELECT DATE_BUCKET(WEEK, 5, @date, @origin);

datepart 인수

dayofyear, day, weekday는 동일한 값을 반환합니다. 각 datepart와 해당 약어는 동일한 값을 반환합니다.

number 인수

number 인수는 양수 int 값의 범위를 초과할 수 없습니다. 다음 명령문에서 number에 대한 인수는 int 범위를 1만큼 초과합니다. 다음 명령문은 Msg 8115, Level 16, State 2, Line 2. Arithmetic overflow error converting expression to data type int. 오류 메시지를 반환합니다

DECLARE @date DATETIME2 = '2020-04-30 00:00:00';
SELECT DATE_BUCKET(DAY, 2147483648, @date);

number에 대한 음수 값이 DATE_BUCKET 함수에 전달되면 다음과 같은 오류가 반환됩니다.

Msg 9834, Level 16, State 1, Line 1
Invalid bucket width value passed to DATE_BUCKET function. Only positive values are allowed.

date 인수

DATE_BUCKET은 date 인수의 데이터 형식에 해당하는 기준 값을 반환합니다. 다음 예제에서는 datetime2 데이터 형식이 포함된 출력 값이 반환됩니다.

SELECT DATE_BUCKET(DAY, 10, SYSUTCDATETIME());

origin 인수

origin 및 date 인수의 데이터 형식은 동일해야 합니다. 다른 데이터 형식을 사용하는 경우 오류가 생성됩니다.

설명

다음 절에서 DATE_BUCKET를 사용합니다.

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

예제

A. 원본 시간으로부터 1의 버킷 너비로 DATE_BUCKET을 계산

이러한 각 명령문은 원본 시간으로부터 1의 버킷 너비로 DATE_BUCKET을 증가시킵니다.

DECLARE @date DATETIME2 = '2020-04-30 21:21:21';
SELECT 'Week', DATE_BUCKET(WEEK, 1, @date)
UNION ALL
SELECT 'Day', DATE_BUCKET(DAY, 1, @date)
UNION ALL
SELECT 'Hour', DATE_BUCKET(HOUR, 1, @date)
UNION ALL
SELECT 'Minutes', DATE_BUCKET(MINUTE, 1, @date)
UNION ALL
SELECT 'Seconds', DATE_BUCKET(SECOND, 1, @date);

결과 집합은 다음과 같습니다.

Week    2020-04-27 00:00:00.0000000
Day     2020-04-30 00:00:00.0000000
Hour    2020-04-30 21:00:00.0000000
Minutes 2020-04-30 21:21:00.0000000
Seconds 2020-04-30 21:21:21.0000000

B. 식을 숫자 및 날짜 매개 변수에 대한 인수로 사용

이러한 예제에서는 여러 유형의 식을 number 및 date 매개 변수에 대한 인수로 사용합니다.

이러한 예제는 AdventureWorksDW2022 데이터베이스를 사용하여 빌드됩니다.

사용자 정의 변수를 숫자 및 날짜로 지정

이 예제에서는 사용자 정의 변수를 number 및 date에 대한 인수로 지정합니다.

DECLARE @days INT = 365,
    @datetime DATETIME2 = '2000-01-01 01:01:01.1110000';
    /* 2000 was a leap year */;
SELECT DATE_BUCKET(DAY, @days, @datetime);

결과 집합은 다음과 같습니다.

1999-12-08 00:00:00.0000000

열을 날짜로 지정

아래 예제에서는 주간 날짜 버킷에 따라 그룹화된 OrderQuantity의 합계와 UnitPrice의 합계를 계산합니다.

SELECT DATE_BUCKET(WEEK, 1, CAST(ShipDate AS DATETIME2)) AS ShippedDateBucket
    , SUM(OrderQuantity) AS SumOrderQuantity
    , SUM(UnitPrice) AS SumUnitPrice
FROM dbo.FactInternetSales FIS
WHERE ShipDate BETWEEN '2011-01-03 00:00:00.000'
        AND '2011-02-28 00:00:00.000'
GROUP BY DATE_BUCKET(WEEK, 1, CAST(ShipDate AS DATETIME2))
ORDER BY ShippedDateBucket;

결과 집합은 다음과 같습니다.

ShippedDateBucket           SumOrderQuantity SumUnitPrice
--------------------------- ---------------- ---------------------
2011-01-03 00:00:00.0000000 21               65589.7546
2011-01-10 00:00:00.0000000 27               89938.5464
2011-01-17 00:00:00.0000000 31               104404.9064
2011-01-24 00:00:00.0000000 36               118525.6846
2011-01-31 00:00:00.0000000 39               123555.431
2011-02-07 00:00:00.0000000 35               109342.351
2011-02-14 00:00:00.0000000 32               107804.8964
2011-02-21 00:00:00.0000000 37               119456.3428
2011-02-28 00:00:00.0000000 9                28968.6982

스칼라 시스템 함수를 날짜로 지정

이 예제에서는 date에 대해 SYSDATETIME을 지정합니다. 반환되는 정확한 값은 명령문 실행의 날짜와 시간에 따라 달라집니다.

SELECT DATE_BUCKET(WEEK, 10, SYSDATETIME());

결과 집합은 다음과 같습니다.

2020-03-02 00:00:00.0000000

스칼라 하위 쿼리 및 스칼라 함수를 숫자 및 날짜로 지정

이 예제에서는 스칼라 하위 쿼리인 MAX(OrderDate)를 number 및 date에 대한 인수로 사용합니다. (SELECT top 1 CustomerKey FROM dbo.DimCustomer where GeographyKey > 100)은 값 목록에서 number 인수를 선택하는 방법을 보여 주기 위하여 만든 숫자 매개 변수에 대한 인수로 작용합니다.

SELECT DATE_BUCKET(WEEK, (
    SELECT TOP 1 CustomerKey
    FROM dbo.DimCustomer
    WHERE GeographyKey > 100
    ), (
    SELECT MAX(OrderDate)
    FROM dbo.FactInternetSales
));

숫자 식 및 스칼라 시스템 함수를 숫자 및 날짜로 지정

이 예제에서는 숫자 식((10/2)), 스칼라 시스템 함수(SYSDATETIME)를 숫자 및 날짜에 대한 인수로 사용합니다.

SELECT DATE_BUCKET(WEEK, (10/2), SYSDATETIME());

집계 창 함수를 숫자로 지정

이 예제에서는 집계 창 함수를 number 인수로 사용합니다.

SELECT DISTINCT DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2)) AS DateBucket
    , FIRST_VALUE([SalesOrderNumber]) OVER (
        ORDER BY DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2))
        ) AS First_Value_In_Bucket
    , LAST_VALUE([SalesOrderNumber]) OVER (
        ORDER BY DATE_BUCKET(DAY, 30, CAST([ShipDate] AS DATETIME2))
        ) AS Last_Value_In_Bucket
FROM [dbo].[FactInternetSales]
WHERE ShipDate BETWEEN '2011-01-03 00:00:00.000'
        AND '2011-02-28 00:00:00.000'
ORDER BY DateBucket;
GO

C. 기본 origin 값이 아닌 값 사용

이 예제에서는 기본 origin 값이 아닌 값을 사용하여 date 버킷을 생성합니다.

DECLARE @date DATETIME2 = '2020-06-15 21:22:11';
DECLARE @origin DATETIME2 = '2019-01-01 00:00:00';
SELECT DATE_BUCKET(HOUR, 2, @date, @origin);

참고 항목

• CAST 및 CONVERT(Transact-SQL)
• 날짜 및 시간 형식
• 날짜 및 시간 데이터 형식 및 함수(Transact-SQL)