DATE_BUCKET(Transact-SQL)

아티클
10/24/2023

Important

Azure SQL Edge는 더 이상 ARM64 플랫폼을 지원하지 않습니다.

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

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

Transact-SQL 구문 표기 규칙

구문

DATE_BUCKET (datePart , number , date , origin)

인수

datePart

다음 표와 같이 'number' 매개 변수와 함께 사용되는 날짜의 부분입니다. 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_BUCKET의 경우 이전에 멘션 데이터 형식으로 확인되는 경우 열 식, 식 또는 사용자 정의 변수를 허용합니다.

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`

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

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

SELECT DATE_BUCKET(WEEK, 1, @date);

다음 식 모두에 대해 동일한 출력 값 2020-04-13 00:00:00.0000000 이 반환됩니다. 이는 원본 날짜로부터 6276주이고 6276은 2, 3, 4 및 6으로 나눌 수 있기 2020-04-13 00:00:00.0000000 때문입니다.

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);

설명

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

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

`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);

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

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

origin 인수

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

예제

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 매개 변수에 대한 인수로 사용합니다. 이러한 예제는 데이터베이스를 AdventureWorksDW2019 사용하여 빌드됩니다.

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

이 예제에서는 사용자 정의 변수를 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

(1 row affected)

열을 날짜로 지정

아래 예제에서는 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

(1 row affected)

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

이 예제에서는 스칼라 하위 쿼리인 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)

DATE_BUCKET(Transact-SQL)

구문

인수

datePart

number

date

origin

반환 형식

반환 값

다음의 출력 이해 DATE_BUCKET

설명

datePart 인수

number 인수

date 인수

origin 인수

예제

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

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

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

열을 날짜로 지정

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

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

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

집계 창 함수를 숫자로 지정

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

참고 항목

추가 리소스

다음의 출력 이해 `DATE_BUCKET`

`datePart` 인수