DATE_BUCKET (Transact-SQL)

Artikel
09/22/2023

Viktigt!

Azure SQL Edge stöder inte längre ARM64-plattformen.

Den här funktionen returnerar det datetime-värde som motsvarar starten för varje datetime-bucket, från tidsstämpeln som definieras av parametern origin eller standardvärdet 1900-01-01 00:00:00.000 för ursprung för om ursprungsparametern inte har angetts.

Se Datatyper och funktioner för datum och tid (Transact-SQL) för en översikt över alla datatyper och funktioner för Transact-SQL-datum och tid.

Transact-SQL-syntaxkonventioner

Syntax

DATE_BUCKET (datePart , number , date , origin)

Argument

Datumdel

Den del av datumet som används med parametern "number", som visas i följande tabell. DATE_BUCKETaccepterar inte användardefinierade variabelmotsvarigheter för datePart-argumenten.

Datumdel	Förkortningar
Dag	dd, d
Vecka	wk, ww
Månad	mm, m
Quater	qq, q
År	yyy, yyyyy
Timme	hh
Minuters	mi, n
Andra	ss, s
Millisekund	Ms

Nummer

Heltalsnumret som bestämmer bredden på bucketen i kombination med argumentet datePart. Detta representerar bredden på datePart-bucketarna från ursprungstiden. Det här argumentet måste vara ett positivt heltalsvärde.

Datum

Ett uttryck som kan matcha något av följande värden:

Datum
Datetime
datetime2
datetimeoffset
smalldatetime
Tid

För datumDATE_BUCKET accepterar en kolumnuttryck, ett uttryck eller en användardefinierad variabel om de matchar någon av de datatyper som nämnts tidigare.

Ursprung

Ett valfritt uttryck som kan matcha något av följande värden:

Datum
Datetime
datetime2
datetimeoffset
smalldatetime
Tid

Datatypen för ursprunget ska matcha datatypen för datumparametern.

DATE_BUCKET använder ett standardvärde 1900-01-01 00:00:00.000för ursprungsdatum, dvs. 12:00 måndagen den 1 januari 1900, om inget ursprungsvärde har angetts för funktionen.

Returnerad typ

Datatypen returneringsvärde för den här metoden är dynamisk. Returtypen beror på det argument som angetts för datum. Om en giltig indatatyp anges för datumDATE_BUCKET returnerar samma datatyp. DATE_BUCKET genererar ett fel om en strängliteral anges för datumparametern .

Returvärden

Förstå utdata från `DATE_BUCKET`

DATE_BUCKET returnerar det senaste datum- eller tidsvärdet som motsvarar parametrarna datePart och number . I följande uttryck returnerar DATE_BUCKET till exempel utdatavärdet 2020-04-13 00:00:00.0000000för , eftersom utdata beräknas baserat på en veckas bucketar från standardtiden för ursprunget för 1900-01-01 00:00:00.000. Värdet 2020-04-13 00:00:00.0000000 är 6276 veckor från ursprungsvärdet 1900-01-01 00:00:00.000för .

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

SELECT DATE_BUCKET(WEEK, 1, @date);

För alla följande uttryck returneras samma utdatavärde 2020-04-13 00:00:00.0000000 . Detta beror på att 2020-04-13 00:00:00.0000000 är 6276 veckor från ursprungsdatumet och 6276 är delbar med 2, 3, 4 och 6.

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

Utdata för uttrycket nedan är 2020-04-06 00:00:00.0000000, vilket är 6275 veckor från standardtiden 1900-01-01 00:00:00.000för ursprung .

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

SELECT DATE_BUCKET(WEEK, 5, @date);

Utdata för uttrycket nedan är 2020-06-09 00:00:00.0000000 , vilket är 75 veckor från den angivna ursprungstiden 2019-01-01 00:00:00.

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

Anmärkningar

Använd DATE_BUCKET i följande satser:

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

`datePart`-argument

dayofyear, day och weekday returnerar samma värde. Varje datePart och dess förkortningar returnerar samma värde.

talargument

Talargumentet får inte överskrida intervallet för positiva int-värden. I följande instruktioner överskrider argumentet för tal intervallet för int med 1. Följande instruktion returnerar följande felmeddelande: 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);

Om ett negativt värde för tal skickas till DATE_BUCKET funktionen returneras följande fel.

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

datumargument

DATE_BUCKETreturnera basvärdet som motsvarar datatypen för datumargumentet. I följande exempel returneras ett utdatavärde med datatypen datetime2 .

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

ursprungsargument

Datatypen för argumenten ursprung och datum i måste vara samma. Om olika datatyper används genereras ett fel.

Exempel

A. Beräkna DATE_BUCKET med en bucketbredd på 1 från ursprungstiden

Var och en av dessa instruktioner ökar DATE_BUCKET med en bucketbredd på 1 från ursprungstiden:

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

Här är resultatuppsättningen.

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. Använda uttryck som argument för parametrarna tal och datum

I de här exemplen används olika typer av uttryck som argument för tal - och datumparametrarna . De här exemplen skapas med hjälp av AdventureWorksDW2019 databasen.

Ange användardefinierade variabler som tal och datum

I det här exemplet anges användardefinierade variabler som argument för tal och datum:

DECLARE @days INT = 365,
    @datetime DATETIME2 = '2000-01-01 01:01:01.1110000';/* 2000 was a leap year */;

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

Här är resultatuppsättningen.

---------------------------
1999-12-08 00:00:00.0000000

(1 row affected)

Ange en kolumn som datum

I exemplet nedan beräknar vi summan av OrderQuantity och summan av UnitPrice grupperad över veckovisa datumbucketar.

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;

Här är resultatuppsättningen.

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

Ange skalär systemfunktion som datum

Det här exemplet anger SYSDATETIME för datum. Det exakta värdet som returneras beror på dagen och tiden för instruktionskörningen:

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

Här är resultatuppsättningen.

---------------------------
2020-03-02 00:00:00.0000000

(1 row affected)

Ange skalära underfrågor och skalärfunktioner som tal och datum

I det här exemplet används skalära underfrågor, MAX(OrderDate), som argument för tal och datum. (SELECT top 1 CustomerKey FROM dbo.DimCustomer where GeographyKey > 100) fungerar som ett artificiellt argument för talparametern för att visa hur du väljer ett talargument från en värdelista.

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

Ange numeriska uttryck och skalära systemfunktioner som tal och datum

I det här exemplet används ett numeriskt uttryck ((10/2)) och skalära systemfunktioner (SYSDATETIME) som argument för tal och datum.

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

Ange en mängdfönsterfunktion som tal

I det här exemplet används en mängdfönsterfunktion som argument för tal.

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. Använda ett ursprungsvärde som inte är standard

I det här exemplet används ett ursprungsvärde som inte är standard för att generera datum buckets.

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

Se även

CAST och CONVERT (Transact-SQL)

DATE_BUCKET (Transact-SQL)

Syntax

Argument

Datumdel

Nummer

Datum

Ursprung

Returnerad typ

Returvärden

Förstå utdata från DATE_BUCKET

Anmärkningar

datePart-argument

talargument

datumargument

ursprungsargument

Exempel

A. Beräkna DATE_BUCKET med en bucketbredd på 1 från ursprungstiden

B. Använda uttryck som argument för parametrarna tal och datum

Ange användardefinierade variabler som tal och datum

Ange en kolumn som datum

Ange skalär systemfunktion som datum

Ange skalära underfrågor och skalärfunktioner som tal och datum

Ange numeriska uttryck och skalära systemfunktioner som tal och datum

Ange en mängdfönsterfunktion som tal

C. Använda ett ursprungsvärde som inte är standard

Se även

Ytterligare resurser

Förstå utdata från `DATE_BUCKET`

`datePart`-argument