DATE_BUCKET (Transact-SQL)

Относится к: SQL Server 2022 (16.x) Azure SQL Database AzureSQL 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

Часть даты , которая используется с параметром числа , например год, месяц, день, минута, вторая.

DATE_BUCKET не принимает эквивалентные переменные, определяемые пользователем, для аргументов datepart.

datepart	Abbreviations
day	dd, d
week	wk, ww
month	мм, м
quarter	qq, q
year	yy, yyy
hour	hh
minute	Ми, Н
second	ss, s
millisecond	ms

number

Целое число, которое определяет ширину контейнера в сочетании с аргументом datepart. Этот аргумент представляет ширину сегментов даты и времени источника. Этот аргумент не может быть отрицательным целым числом.

date

Выражение, которое должно быть одним из следующих значений:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Для даты принимает выражение столбца, выражение или определяемую пользователем переменную, DATE_BUCKET если они разрешаются любому из указанных ранее типов данных.

origin

Необязательное выражение, которое может быть разрешено для одного из следующих значений.

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Тип данных для источника должен соответствовать типу данных параметра date .

DATE_BUCKET использует значение 1900-01-01 00:00:00.000 даты источника по умолчанию, равное 12:00 в понедельник, 1 января 1900 г., если для функции не указано значение источника .

Типы возвращаемых данных

Тип данных возвращаемого значения для этого метода является динамическим. Тип возвращаемого значения зависит от типа аргумента, переданного в параметре date. Если для даты указан допустимый тип входных данных, DATE_BUCKET возвращает тот же тип данных. DATE_BUCKET Вызывает ошибку, если строковый литерал указан для параметра date .

Возвращаемое значение

Общие сведения о выходных данных из DATE_BUCKET

DATE_BUCKET возвращает последнее значение даты или времени, соответствующее параметрам datepart и number. Например, в следующих выражениях DATE_BUCKET возвращает выходное значение 2020-04-13 00:00:00.0000000, так как выходные данные вычисляются на основе одного недельного контейнера из времени 1900-01-01 00:00:00.000источника по умолчанию. Значение 2020-04-13 00:00:00.0000000 составляет 6,276 недель от значения аргумента origin 1900-01-01 00:00:00.000.

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.00000006275 недель с момента 1900-01-01 00:00:00.000начала по умолчанию.

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

SELECT DATE_BUCKET(WEEK, 5, @date);

Выходные данные для следующего выражения : 2020-06-09 00:00:00.000000075 недель с указанного времени 2019-01-01 00:00:00источника.

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 и.

А. Вычисление DATE_BUCKET с шириной контейнера, равной 1, от времени аргумента origin

Каждый из этих операторов увеличивается DATE_BUCKET с шириной контейнера 1 от времени источника:

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

В этих примерах выражения различного типа используются в качестве аргументов для параметров number и date.

Эти примеры создаются с использованием базы данных AdventureWorksDW2025.

Указание пользовательских переменных в качестве аргументов number и date

В этом примере в качестве аргументов 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

Указание столбца в качестве аргумента date

В следующем примере вычисляется сумма 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

Указание в качестве аргумента date скалярной системной функции

В этом примере для аргумента SYSDATETIME указано значение . Точное возвращаемое значение зависит от дня и времени выполнения инструкции.

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

Вот результирующий набор.

2020-03-02 00:00:00.0000000

Указание в качестве аргументов number и date скалярных вложенных запросов и скалярных функций

В этом примере в качестве аргументов для MAX(OrderDate) и 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
    )
);

Указание в качестве аргументов number и date числовых выражений и скалярных системных функций

В этом примере используется числовое выражение ((10/2)) и скалярные системные функции (SYSDATETIME) в качестве аргументов для числа и даты.

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

Указание в качестве аргумента number статистической оконной функции

В этом примере в качестве аргумента 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

В. Использование значения аргумента origin не по умолчанию

В этом примере используется значение origin, отличное от значения по умолчанию, для создания контейнеров даты.

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

Аргумент числа

Аргумент даты

Аргумент источника

Замечания

Примеры

А. Вычисление DATE_BUCKET с шириной контейнера, равной 1, от времени аргумента origin

B. Использование выражений в качестве аргументов для параметров number и date

Указание пользовательских переменных в качестве аргументов number и date

Указание столбца в качестве аргумента date

Указание в качестве аргумента date скалярной системной функции

Указание в качестве аргументов number и date скалярных вложенных запросов и скалярных функций

Указание в качестве аргументов number и date числовых выражений и скалярных системных функций

Указание в качестве аргумента number статистической оконной функции

В. Использование значения аргумента origin не по умолчанию

Связанный контент

Обратная связь

Дополнительные ресурсы