DATE_BUCKET (Transact-SQL)

Gilt für: SQL Server 2022 (16.x) Azure SQL Database Azure SQL Managed Instance Azure SQL Edge SQL database in Microsoft Fabric

Diese Funktion gibt den Datum-Uhrzeit-Wert zurück, der dem Start jedes Datum-Uhrzeit-Buckets aus dem durch den Origin-Parameter definierten Zeitstempel entspricht, oder den Standardwert, wenn 1900-01-01 00:00:00.000 der Origin-Parameter nicht angegeben ist.

Eine Übersicht über alle Transact-SQL-Datums- und Uhrzeitdatentypen und -funktionen finden Sie unter Datums- und Uhrzeitdatentypen und -funktionen .

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

datepart

Der Teil des Datums , der mit dem Zahlenparameter verwendet wird, z. B. Jahr, Monat, Tag, Minute, Sekunde.

DATE_BUCKET akzeptiert für die datepart-Argumente keine benutzerdefinierten Variablenentsprechungen.

datepart	Abkürzungen
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

Zahl

Der Integerwert, der die Breite des Buckets in Kombination mit dem datepart-Argument bestimmt. Dieses Argument stellt die Breite der Datepart-Buckets aus der Ursprungszeit dar. Dieses Argument kann kein negativer ganzzahliger Wert sein.

date

Ein Ausdruck, der einen der folgenden Werte sein muss:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Akzeptiert für einen Spaltenausdruck, einen Ausdruck oder eine benutzerdefinierte Variable, wenn sie in einen der zuvor erwähnten Datentypen aufgelöst werden.

origin

Ein optionaler Ausdruck, der in einen der folgenden Werte aufgelöst werden kann:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Der Datentyp für den Ursprung sollte mit dem Datentyp des Datumsparameters übereinstimmen.

DATE_BUCKET verwendet einen Standardmäßigen Ursprungsdatumswert, der 1900-01-01 00:00:00.000 lautet, 12:00 Uhr am Montag, dem 1. Januar 1900, wenn kein Ursprungswert für die Funktion angegeben ist.

Rückgabetypen

Der Datentyp des Rückgabewerts für diese Methode ist dynamisch. Der Rückgabetyp hängt von dem Argument ab, das für date angegeben wird. Wenn ein gültiger Eingabedatentyp für datum angegeben wird, DATE_BUCKET wird derselbe Datentyp zurückgegeben. DATE_BUCKETlöst einen Fehler aus, wenn für den Datumsparameter ein Zeichenfolgenliteral angegeben ist.

Rückgabewert

Grundlegendes zur Ausgabe von DATE_BUCKET

DATE_BUCKET gibt den aktuellsten Datums- oder Uhrzeitwert zurück, der dem datepart- und dem number-Parameter entspricht. Gibt z. B. in den folgenden Ausdrücken den Ausgabewert zurückDATE_BUCKET, 2020-04-13 00:00:00.0000000 da die Ausgabe basierend auf einer Woche Buckets aus der Standardursprungzeit 1900-01-01 00:00:00.000berechnet wird. Der Wert 2020-04-13 00:00:00.0000000 ist 6.276 Wochen vom Ursprungswert 1900-01-01 00:00:00.000 entfernt.

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

SELECT DATE_BUCKET(WEEK, 1, @date);

Für alle folgenden Ausdrücke wird derselbe Ausgabewert 2020-04-13 00:00:00.0000000 zurückgegeben. Dies liegt daran, dass 2020-04-13 00:00:00.0000000 6.276 Wochen vom origin-Wert entfernt und 6.276 durch 2, 3, 4 und 6 teilbar ist.

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

Die Ausgabe für den folgenden Ausdruck lautet 2020-04-06 00:00:00.0000000, was 6.275 Wochen ab der Standardursprungzeit 1900-01-01 00:00:00.000ist.

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

SELECT DATE_BUCKET(WEEK, 5, @date);

Die Ausgabe für den folgenden Ausdruck lautet 2020-06-09 00:00:00.0000000, die 75 Wochen ab der angegebenen Ursprungszeit 2019-01-01 00:00:00liegt.

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

Das Datepart-Argument

dayofyear, day und weekday geben den gleichen Wert zurück. Jedes datepart-Argument und die jeweils zugehörigen Abkürzungen geben den gleichen Wert zurück.

Das Argument "Zahl"

Das number-Argument kann den Bereich von positiven int-Werten nicht überschreiten. In den folgenden Anweisungen überschreitet das Argument für number den Bereich von int um 1. Die folgende Anweisung gibt die Fehlermeldung zurück: 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);

Wenn ein negativer Wert für die Zahl an die DATE_BUCKET Funktion übergeben wird, wird der folgende Fehler zurückgegeben.

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

Das Datum-Argument

DATE_BUCKET gibt den Basiswert zurück, der dem Datentyp des Datumsarguments entspricht. Im folgenden Beispiel wird ein Ausgabewert mit dem Datentyp datetime2 zurückgegeben.

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

Das Origin-Argument

Der Datentyp der Ursprungs - und Datumsargumente in muss identisch sein. Wenn unterschiedliche Datentypen verwendet werden, wird ein Fehler generiert.

Bemerkungen

Verwenden Sie DATE_BUCKET in den folgenden Klauseln:

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

Beispiele

Die Codebeispiele in diesem Artikel verwenden die AdventureWorks2025- oder AdventureWorksDW2025 Beispieldatenbank, die Sie von der Microsoft SQL Server Samples and Community Projects Homepage herunterladen können.

A. Berechnen von DATE_BUCKET mit einer Bucketbreite von 1 ab der Ursprungszeit

Jede dieser Anweisungen erhöht DATE_BUCKET mit einer Bucketbreite von 1 ab der Ursprungszeit:

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

Hier sehen Sie das Ergebnis.

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. Verwenden von Ausdrücken als Argumente für den number-Parameter und den date-Parameter

In diesen Beispielen werden verschiedene Typen von Ausdrücken als Argumente für die Parameter number und date verwendet.

Diese Beispiele werden mithilfe der AdventureWorksDW2025-Datenbank erstellt.

Angeben von benutzerdefinierten Variablen als Argumente für number und date

In diesem Beispiel werden benutzerdefinierte Variablen als Argumente für number und date angegeben:

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

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

Hier sehen Sie das Ergebnis.

1999-12-08 00:00:00.0000000

Angeben einer Spalte als date-Parameter

Im folgenden Beispiel berechnen wir die Summe und OrderQuantity Summe, die UnitPrice über wöchentliche Datums-Buckets gruppiert ist.

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;

Hier sehen Sie das Ergebnis.

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

Angeben einer skalaren Systemfunktion als Argument für date

In diesem Beispiel wird SYSDATETIME für date angegeben. Welcher Wert genau zurückgegeben wird, hängt davon ab, an welchem Tag und zu welcher Uhrzeit die Anweisung ausgeführt wird:

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

Hier sehen Sie das Ergebnis.

2020-03-02 00:00:00.0000000

Angeben von skalaren Unterabfragen und skalaren Funktionen als Argumente für number und date

In diesem Beispiel werden skalare Unterabfragen (MAX(OrderDate)) als Argumente für number und date verwendet. (SELECT TOP 1 CustomerKey FROM dbo.DimCustomer WHERE GeographyKey > 100) dient als Beispielargument für den Parameter „number“, das veranschaulicht, wie ein number-Argument aus einer Werteliste ausgewählt wird.

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

Angeben von numerischen Ausdrücken und skalaren Systemfunktionen als Argumente für number und date

In diesem Beispiel wird ein numerischer Ausdruck ((10/2)) und skalare Systemfunktionen (SYSDATETIME) als Argumente für Zahl und Datum verwendet.

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

Angeben einer Aggregatfensterfunktion als Argument für number

In diesem Beispiel wird eine Aggregatfensterfunktion als Argument für number verwendet.

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. Verwenden eines nicht standardmäßigen Ursprungswerts

In diesem Beispiel wird ein nicht standardmäßiger Ursprungswert für date-Buckets verwendet.

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

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-05

Freigeben über

DATE_BUCKET (Transact-SQL)

Syntax

Argumente

datepart

Zahl

date

origin

Rückgabetypen

Rückgabewert

Grundlegendes zur Ausgabe von DATE_BUCKET

Das Datepart-Argument

Das Argument "Zahl"

Das Datum-Argument

Das Origin-Argument

Bemerkungen

Beispiele

A. Berechnen von DATE_BUCKET mit einer Bucketbreite von 1 ab der Ursprungszeit

B. Verwenden von Ausdrücken als Argumente für den number-Parameter und den date-Parameter

Angeben von benutzerdefinierten Variablen als Argumente für number und date

Angeben einer Spalte als date-Parameter

Angeben einer skalaren Systemfunktion als Argument für date

Angeben von skalaren Unterabfragen und skalaren Funktionen als Argumente für number und date

Angeben von numerischen Ausdrücken und skalaren Systemfunktionen als Argumente für number und date

Angeben einer Aggregatfensterfunktion als Argument für number

C. Verwenden eines nicht standardmäßigen Ursprungswerts

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen