DATE_BUCKET (Transact-SQL)

Artikel
09/21/2024

Belangrijk

Azure SQL Edge wordt op 30 september 2025 buiten gebruik gesteld. Zie de kennisgeving buitengebruikstelling voor meer informatie en migratieopties.

Notitie

Azure SQL Edge biedt geen ondersteuning meer voor het ARM64-platform.

Deze functie retourneert de datum/tijd-waarde die overeenkomt met het begin van elke datum/tijd-bucket, vanaf de tijdstempel die is gedefinieerd door de origin parameter of de standaardwaarde van oorsprong als 1900-01-01 00:00:00.000 de oorspronkelijke parameter niet is opgegeven.

Zie Datum- en tijdgegevenstypen en -functies (Transact-SQL) voor een overzicht van alle transact-SQL-datum- en tijdgegevenstypen en -functies.

Transact-SQL-syntaxisconventies

Syntaxis

DATE_BUCKET (datePart , number , date , origin)

Argumenten

datePart

Het deel van de datum dat wordt gebruikt met de parameter 'getal', zoals wordt weergegeven in de volgende tabel. DATE_BUCKET accepteert geen door de gebruiker gedefinieerde variabelenequivalenten voor de datePart-argumenten .

datePart	Abbreviations
dag	dd, d
week	wk, ww
maand	mm, m
wijk	qq, q
jaar	yyy, jjjj
uur	hh
minuut	mi, n
tweede	ss, s
milliseconde	mevrouw

getal

Het gehele getal waarmee de breedte van de bucket wordt bepaald in combinatie met het argument datePart . Dit vertegenwoordigt de breedte van de datePart-buckets vanaf de oorspronkelijke tijd. Dit argument moet een positief geheel getal zijn.

datum

Een expressie die kan worden omgezet in een van de volgende waarden:

datum
datum/tijd
datetime2
datetimeoffset
smalldatetime
time

Voor datumDATE_BUCKET accepteert u een kolomexpressie, expressie of door de gebruiker gedefinieerde variabele als deze worden omgezet in een van de eerder genoemde gegevenstypen.

oorsprong

Een optionele expressie die kan worden omgezet in een van de volgende waarden:

datum
datum/tijd
datetime2
datetimeoffset
smalldatetime
time

Het gegevenstype voor oorsprong moet overeenkomen met het gegevenstype van de datumparameter .

DATE_BUCKET gebruikt een standaardwaarde voor de oorsprongsdatum van 1900-01-01 00:00:00.000, dat wil gezegd: 12:00 uur op maandag 1 januari 1900, als er geen oorsprongswaarde is opgegeven voor de functie.

Retourtype

Het gegevenstype retourwaarde voor deze methode is dynamisch. Het retourtype is afhankelijk van het argument dat is opgegeven voor datum. Als er een geldig invoergegevenstype voor de datum wordt opgegeven, DATE_BUCKET wordt hetzelfde gegevenstype geretourneerd. DATE_BUCKET genereert een fout als een letterlijke tekenreeks is opgegeven voor de datumparameter .

Retourwaarden

Inzicht in de uitvoer van `DATE_BUCKET`

DATE_BUCKET retourneert de laatste datum- of tijdwaarde, die overeenkomt met de parameters datePart en getal . Retourneert in de volgende expressies bijvoorbeeld de uitvoerwaarde van 2020-04-13 00:00:00.0000000, omdat de uitvoer wordt berekend op basis van buckets DATE_BUCKET van één week van de standaard oorspronkelijke tijd van 1900-01-01 00:00:00.000. De waarde 2020-04-13 00:00:00.0000000 is 6276 weken van de oorsprongswaarde van 1900-01-01 00:00:00.000.

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

SELECT DATE_BUCKET(WEEK, 1, @date);

Voor alle volgende expressies wordt dezelfde uitvoerwaarde 2020-04-13 00:00:00.0000000 geretourneerd. Dit komt doordat 2020-04-13 00:00:00.0000000 6276 weken vanaf de oorspronkelijke datum en 6276 deelbaar is door 2, 3, 4 en 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);

De uitvoer voor de onderstaande expressie is 2020-04-06 00:00:00.0000000, die 6275 weken is vanaf de standaard oorspronkelijke tijd 1900-01-01 00:00:00.000.

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

SELECT DATE_BUCKET(WEEK, 5, @date);

De uitvoer voor de onderstaande expressie is 2020-06-09 00:00:00.0000000 , dat is 75 weken vanaf de opgegeven oorspronkelijke tijd 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);

Opmerkingen

Gebruik DATE_BUCKET in de volgende componenten:

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

Argument voor `datePart`

dayofyear, day en weekday retourneren dezelfde waarde. Elke datePart en de bijbehorende afkortingen retourneren dezelfde waarde.

getalargument

Het getalargument kan het bereik van positieve intwaarden niet overschrijden. In de volgende instructies overschrijdt het argument voor getal het bereik van int door 1. De volgende instructie retourneert het volgende foutbericht: 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);

Als een negatieve waarde voor getal wordt doorgegeven aan de DATE_BUCKET functie, wordt de volgende fout geretourneerd.

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

datumargument

DATE_BUCKET retourneert de basiswaarde die overeenkomt met het gegevenstype van het datumargument . In het volgende voorbeeld wordt een uitvoerwaarde met het gegevenstype datetime2 geretourneerd.

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

argument oorsprong

Het gegevenstype van de oorspronkelijke en datumargumenten in moet hetzelfde zijn. Als er verschillende gegevenstypen worden gebruikt, wordt er een fout gegenereerd.

Voorbeelden

A. Bereken DATE_BUCKET met een bucketbreedte van 1 vanaf de oorspronkelijke tijd

Elk van deze instructies wordt verhoogd DATE_BUCKET met een bucketbreedte van 1 vanaf de oorspronkelijke tijd:

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

Dit is de resultatenset.

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. Expressies gebruiken als argumenten voor de parameters getal en datum

In deze voorbeelden worden verschillende typen expressies gebruikt als argumenten voor de getal- en datumparameters. Deze voorbeelden worden gebouwd met behulp van de AdventureWorksDW2019 database.

Door de gebruiker gedefinieerde variabelen opgeven als getal en datum

In dit voorbeeld worden door de gebruiker gedefinieerde variabelen opgegeven als argumenten voor getal en 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);

Dit is de resultatenset.

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

(1 row affected)

Een kolom opgeven als datum

In het onderstaande voorbeeld berekenen we de som van OrderQuantity en de som van UnitPrice gegroepeerd in wekelijkse datumbuckets.

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;

Dit is de resultatenset.

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

Scalaire systeemfunctie opgeven als datum

In dit voorbeeld wordt de datum opgegeven SYSDATETIME . De exacte waarde die wordt geretourneerd, is afhankelijk van de dag en tijd van de uitvoering van de instructie:

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

Dit is de resultatenset.

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

(1 row affected)

Scalaire subquery's en scalaire functies opgeven als getal en datum

In dit voorbeeld worden scalaire subquery's gebruikt, MAX(OrderDate)als argumenten voor getal en datum. (SELECT top 1 CustomerKey FROM dbo.DimCustomer where GeographyKey > 100) fungeert als een kunstmatig argument voor de getalparameter om te laten zien hoe u een getalargument in een lijst met waarden selecteert.

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

Numerieke expressies en scalaire systeemfuncties opgeven als getal en datum

In dit voorbeeld wordt een numerieke expressie ((10/2)) en scalaire systeemfuncties (SYSDATETIME) gebruikt als argumenten voor getal en datum.

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

Een statistische vensterfunctie opgeven als getal

In dit voorbeeld wordt een statistische vensterfunctie gebruikt als argument voor getal.

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. Een niet-standaardwaarde voor oorsprong gebruiken

In dit voorbeeld wordt een niet-standaardwaarde voor oorsprong gebruikt om de datumbuckets te genereren.

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 en CONVERT (Transact-SQL)

Delen via

DATE_BUCKET (Transact-SQL)

Syntaxis

Argumenten

datePart

getal

datum

oorsprong

Retourtype

Retourwaarden

Inzicht in de uitvoer van `DATE_BUCKET`

Opmerkingen

Argument voor `datePart`

getalargument

datumargument

argument oorsprong

Voorbeelden

A. Bereken DATE_BUCKET met een bucketbreedte van 1 vanaf de oorspronkelijke tijd

B. Expressies gebruiken als argumenten voor de parameters getal en datum

Door de gebruiker gedefinieerde variabelen opgeven als getal en datum

Een kolom opgeven als datum

Scalaire systeemfunctie opgeven als datum

Scalaire subquery's en scalaire functies opgeven als getal en datum

Numerieke expressies en scalaire systeemfuncties opgeven als getal en datum

Een statistische vensterfunctie opgeven als getal

C. Een niet-standaardwaarde voor oorsprong gebruiken

Feedback

Aanvullende resources

Delen via

DATE_BUCKET (Transact-SQL)

Syntaxis

Argumenten

datePart

getal

datum

oorsprong

Retourtype

Retourwaarden

Inzicht in de uitvoer van DATE_BUCKET

Opmerkingen

Argument voor datePart

getalargument

datumargument

argument oorsprong

Voorbeelden

A. Bereken DATE_BUCKET met een bucketbreedte van 1 vanaf de oorspronkelijke tijd

B. Expressies gebruiken als argumenten voor de parameters getal en datum

Door de gebruiker gedefinieerde variabelen opgeven als getal en datum

Een kolom opgeven als datum

Scalaire systeemfunctie opgeven als datum

Scalaire subquery's en scalaire functies opgeven als getal en datum

Numerieke expressies en scalaire systeemfuncties opgeven als getal en datum

Een statistische vensterfunctie opgeven als getal

C. Een niet-standaardwaarde voor oorsprong gebruiken

Gerelateerde inhoud

Feedback

Aanvullende resources

Inzicht in de uitvoer van `DATE_BUCKET`

Argument voor `datePart`