DATE_BUCKET (Transact-SQL)

Dotyczy do: SQL Server 2022 (16.x) Azure SQL Database Azure SQL Managed Instance Azure SQL Edge SQL database in Microsoft Fabric

Ta funkcja zwraca wartość daty/godziny odpowiadającą początku każdego zasobnika daty i godziny z znacznika czasu zdefiniowanego przez parametr źródła lub domyślną wartość 1900-01-01 00:00:00.000 źródła, jeśli parametr źródła nie jest określony.

Zobacz Typy danych i funkcje daty i godziny, aby zapoznać się z omówieniem wszystkich Transact-SQL typów i funkcji danych daty i godziny.

Transact-SQL konwencje składni

Składnia

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

Arguments

datepart

Część daty , która jest używana z parametrem liczbowym , na przykład rok, miesiąc, dzień, minuta, sekunda.

DATE_BUCKET nie akceptuje odpowiedników zmiennych zdefiniowanych przez użytkownika dla argumentów elementu datepart .

datepart	Abbreviations
dzień	dd, d
tydzień	WK, WW
miesiąc	mm, m
ćwiartka	qq, q
rok	yy, yyyy
godzina	hh
minuta	mi, n
sekunda	SS, S
milisekunda	Ms

number

Liczba całkowita, która decyduje o szerokości zasobnika połączonego z argumentem elementu datepart . Ten argument reprezentuje szerokość zasobników elementów datepart z godziny początkowej. Ten argument nie może być ujemną wartością całkowitą.

date

Wyrażenie, które musi być jedną z następujących wartości:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

W przypadku daty akceptuje wyrażenie kolumny, wyrażenie lub zmienną zdefiniowaną przez użytkownika, DATE_BUCKET jeśli zostaną rozpoznane dla dowolnego z wymienionych wcześniej typów danych.

pochodzenie

Opcjonalne wyrażenie, które może rozpoznać jedną z następujących wartości:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Typ danych źródła powinien być zgodny z typem danych parametru daty.

DATE_BUCKET Używa domyślnej 1900-01-01 00:00:00.000 wartości daty pochodzenia, czyli 12:00 w poniedziałek, 1 stycznia 1900, jeśli dla funkcji nie określono wartości źródła .

Typy zwracane

Zwracany typ danych wartości dla tej metody jest dynamiczny. Typ zwracany zależy od argumentu podanego dla daty. Jeśli dla daty podano prawidłowy typ danych wejściowych, DATE_BUCKET zwraca ten sam typ danych. DATE_BUCKET zgłasza błąd, jeśli dla parametru daty określono literał ciągu.

Wartość zwracana

Omówienie danych wyjściowych z DATE_BUCKET

DATE_BUCKET Zwraca najnowszą wartość daty lub godziny odpowiadającą parametrowi datepart i number . Na przykład w poniższych wyrażeniach DATE_BUCKET zwraca wartość 2020-04-13 00:00:00.0000000wyjściową elementu , ponieważ dane wyjściowe są obliczane na podstawie przedziałów jednego tygodnia z domyślnego czasu początkowego 1900-01-01 00:00:00.000. Wartość 2020-04-13 00:00:00.0000000 wynosi 6276 tygodni od wartości początkowej .1900-01-01 00:00:00.000

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

SELECT DATE_BUCKET(WEEK, 1, @date);

Dla wszystkich poniższych wyrażeń zwracana jest ta sama wartość wyjściowa 2020-04-13 00:00:00.0000000 . Jest to spowodowane 2020-04-13 00:00:00.0000000 tym, że od daty pochodzenia wynosi 6276 tygodni, a 6276 jest podzielne przez 2, 3, 4 i 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);

Dane wyjściowe następującego wyrażenia to 2020-04-06 00:00:00.0000000, czyli 6275 tygodni od domyślnego czasu 1900-01-01 00:00:00.000pochodzenia .

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

SELECT DATE_BUCKET(WEEK, 5, @date);

Dane wyjściowe dla następującego wyrażenia to 2020-06-09 00:00:00.0000000, czyli 75 tygodni od określonego czasu 2019-01-01 00:00:00pochodzenia .

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

Argument składnika datepart

dayofyear, day i weekday zwracają tę samą wartość. Każdy element datepart i jego skróty zwracają tę samą wartość.

Argument liczbowy

Argument liczbowy nie może przekraczać zakresu dodatnich wartości int . W poniższych instrukcjach argument liczby przekracza zakres int o 1. Następująca instrukcja zwraca komunikat o błędzie: 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);

Jeśli do funkcji zostanie przekazana DATE_BUCKET wartość ujemna, zostanie zwrócony następujący błąd.

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

Argument daty

DATE_BUCKET Zwraca wartość podstawową odpowiadającą typowi danych argumentu daty . W poniższym przykładzie zwracana jest wartość wyjściowa z typem danych datetime2.

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

Argument źródła

Typ danych argumentów źródła i daty w pliku musi być taki sam. Jeśli są używane różne typy danych, zostanie wygenerowany błąd.

Uwagi

Użyj DATE_BUCKET w następujących klauzulach:

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

Przykłady

Przykłady kodu w tym artykule korzystają z przykładowej bazy danych AdventureWorks2025 lub AdventureWorksDW2025, którą można pobrać ze strony głównej Przykładów programu Microsoft SQL Server i projektów społeczności.

A. Obliczanie DATE_BUCKET o szerokości zasobnika 1 od czasu pochodzenia

Każda z tych instrukcji zwiększa DATE_BUCKET się o szerokość zasobnika o szerokości 1 od czasu pochodzenia:

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

Oto zestaw wyników.

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. Użyj wyrażeń jako argumentów dla parametrów liczby i daty

W tych przykładach użyto różnych typów wyrażeń jako argumentów dla parametrów liczby i daty .

Te przykłady są tworzone przy użyciu AdventureWorksDW2025 bazy danych.

Określanie zmiennych zdefiniowanych przez użytkownika jako liczby i daty

W tym przykładzie określono zmienne zdefiniowane przez użytkownika jako argumenty dla liczby i daty:

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

SELECT DATE_BUCKET(DAY, @days, @datetime);

Oto zestaw wyników.

1999-12-08 00:00:00.0000000

Określanie kolumny jako daty

W poniższym przykładzie obliczamy sumę OrderQuantity i sumę UnitPrice grupowanych przedziałów dat tygodniowych.

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;

Oto zestaw wyników.

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

Określ funkcję systemu skalarną jako datę

W tym przykładzie SYSDATETIMEokreślono datę. Dokładna zwrócona wartość zależy od dnia i godziny wykonania instrukcji:

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

Oto zestaw wyników.

2020-03-02 00:00:00.0000000

Określanie podzapytania skalarnego i funkcji skalarnych jako liczby i daty

W tym przykładzie użyto podzapytania skalarnych, MAX(OrderDate), jako argumentów dla liczby i daty. (SELECT TOP 1 CustomerKey FROM dbo.DimCustomer WHERE GeographyKey > 100)służy jako sztuczny argument dla parametru number, aby pokazać, jak wybrać argument liczbowy z listy wartości.

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

Określanie wyrażeń liczbowych i funkcji systemu skalarnego jako liczby i daty

W tym przykładzie użyto wyrażenia liczbowego ((10/2)) i funkcji systemu skalarnego (SYSDATETIME) jako argumentów liczby idaty.

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

Określanie funkcji okna agregacji jako liczby

W tym przykładzie użyto funkcji okna agregacji jako argumentu dla liczby.

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. Używanie wartości innej niż domyślna źródła

W tym przykładzie użyto wartości innej niż domyślna źródła do wygenerowania zasobników dat.

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-05

Udostępnij za pomocą

DATE_BUCKET (Transact-SQL)

Składnia

Arguments

datepart

number

date

pochodzenie

Typy zwracane

Wartość zwracana

Omówienie danych wyjściowych z DATE_BUCKET

Argument składnika datepart

Argument liczbowy

Argument daty

Argument źródła

Uwagi

Przykłady

A. Obliczanie DATE_BUCKET o szerokości zasobnika 1 od czasu pochodzenia

B. Użyj wyrażeń jako argumentów dla parametrów liczby i daty

Określanie zmiennych zdefiniowanych przez użytkownika jako liczby i daty

Określanie kolumny jako daty

Określ funkcję systemu skalarną jako datę

Określanie podzapytania skalarnego i funkcji skalarnych jako liczby i daty

Określanie wyrażeń liczbowych i funkcji systemu skalarnego jako liczby i daty

Określanie funkcji okna agregacji jako liczby

C. Używanie wartości innej niż domyślna źródła

Treści powiązane

Sprzężenie zwrotne

Dodatkowe zasoby