DATE_BUCKET(Transact-SQL)

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

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

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

Transact-SQL 구문 표기 규칙

구문

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

인수

datepart

number 매개 변수(예: 연도, 월, 일, 분, 초)와 함께 사용되는 날짜의 부분입니다.

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

datepart	약어
day	DD, D
week	WK, WW
month	음, 음
quarter	Qq, Q
year	yyy, yyyy
hour	hh
minute	미, N
second	ss, s
millisecond	ms

number

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

date

다음 값 중 하나여야 하는 식입니다.

date
datetime
datetime2
datetimeoffset
smalldatetime
time

날짜앞에서 언급한 데이터 형식으로 확인되는 경우 열 식, 식 또는 사용자 정의 변수를 허용합니다.

origin

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

date
datetime
datetime2
datetimeoffset
smalldatetime
time

원본의 데이터 형식은 날짜 매개 변수의 데이터 형식과 일치해야 합니다.

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

반환 형식

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

반환 값

DATE_BUCKET 출력 이해

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

DECLARE @date AS 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 AS 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기본 원본 시간 1900-01-01 00:00:00.000으로부터 6,275주입니다.

DECLARE @date AS DATETIME2 = '2020-04-15 21:22:11';

SELECT DATE_BUCKET(WEEK, 5, @date);

다음 식의 출력은 2020-06-09 00:00:00.0000000지정된 원본 시간 2019-01-01 00:00:00으로부터 75주입니다.

DECLARE @date AS DATETIME2 = '2020-06-15 21:22:11';
DECLARE @origin AS DATETIME2 = '2019-01-01 00:00:00';

SELECT DATE_BUCKET(WEEK, 5, @date, @origin);

datepart 인수

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

숫자 인수

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

DECLARE @date AS DATETIME2 = '2020-04-30 00:00:00';

SELECT DATE_BUCKET(DAY, 2147483648, @date);

숫자의 음수 값이 함수에 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_BUCKET날짜 인수의 데이터 형식에 해당하는 기본 값을 반환합니다. 다음 예제에서는 datetime2 데이터 형식의 출력 값이 반환됩니다.

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

원본 인수

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

설명

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

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

예제

이 문서의 코드 샘플은 AdventureWorks2025 또는 AdventureWorksDW2025 샘플 데이터베이스를 사용합니다. 이 데이터베이스는 Microsoft SQL Server 샘플 및 커뮤니티 프로젝트 홈페이지에서 다운로드할 수 있습니다.

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

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

DECLARE @date AS 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 매개 변수에 대한 인수로 사용합니다.

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

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

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

DECLARE @days AS INT = 365,
        @datetime AS DATETIME2 = '2000-01-01 01:01:01.1110000';

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 AS 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

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

이 예제에서는 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 AS DATETIME2 = '2020-06-15 21:22:11';
DECLARE @origin AS DATETIME2 = '2019-01-01 00:00:00';

SELECT DATE_BUCKET(HOUR, 2, @date, @origin);

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-05

다음을 통해 공유

DATE_BUCKET(Transact-SQL)

구문

인수

datepart

number

date

origin

반환 형식

반환 값

DATE_BUCKET 출력 이해

datepart 인수

숫자 인수

날짜 인수

원본 인수

설명

예제

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

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

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

열을 날짜로 지정

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

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

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

집계 창 함수를 숫자로 지정

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

관련 콘텐츠

피드백

추가 리소스