Partilhar via

DATE_BUCKET (Transact-SQL)

Aplica-se a: SQL Server 2022 (16.x) Azure SQL DatabaseAzure SQL Managed Instance Azure SQL Edge SQL database in Microsoft Fabric

Essa função retorna o valor de data-hora correspondente ao início de cada bucket de data-hora do carimbo de data/hora definido pelo parâmetro origin , ou o valor de origem padrão de se o parâmetro origin 1900-01-01 00:00:00.000 não for especificado.

Consulte Tipos e funções de dados de data e hora para obter uma visão geral de todos os tipos e funções de dados de data e hora Transact-SQL.

Transact-SQL convenções de sintaxe

Sintaxe

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

Arguments

datepart

A parte da data que é usada com o parâmetro number , por exemplo, ano, mês, dia, minuto, segundo.

DATE_BUCKET não aceita equivalentes de variáveis definidos pelo usuário para os argumentos datepart .

datepart Abbreviations
Dia DD, D
semana WK, WW
mês Mm, M
trimestre QQ, Q
ano aaa, aaaa
hora hh
minuto mi, n
segundo SS, S
milissegundos em

number

O número inteiro que decide a largura do bucket combinado com o argumento datepart . Este argumento representa a largura dos buckets datepart da hora de origem. Este argumento não pode ser um valor inteiro negativo.

date

Uma expressão que deve ser um dos seguintes valores:

  • date
  • datetime
  • datetime2
  • datetimeoffset
  • smalldatetime
  • time

Para data, DATE_BUCKET aceita uma expressão de coluna, expressão ou variável definida pelo usuário se eles resolverem para qualquer um dos tipos de dados mencionados anteriormente.

Origem

Uma expressão opcional que pode resolver para um dos seguintes valores:

  • date
  • datetime
  • datetime2
  • datetimeoffset
  • smalldatetime
  • time

O tipo de dados para origem deve corresponder ao tipo de dados do parâmetro date .

DATE_BUCKET usa um valor de data de origem padrão ou seja, 12:00 na segunda-feira, 1º de janeiro de 1900-01-01 00:00:00.000 1900, se nenhum valor de origem for especificado para a função.

Tipos de devolução

O tipo de dados de valor de retorno para este método é dinâmico. O tipo de retorno depende do argumento fornecido para a data. Se um tipo de dados de entrada válido for fornecido para a data, DATE_BUCKET retornará o mesmo tipo de dados. DATE_BUCKET gera um erro se um literal de cadeia de caracteres for especificado para o parâmetro date .

Valor de retorno

Entenda a saída do DATE_BUCKET

DATE_BUCKET Retorna o valor de data ou hora mais recente, correspondente ao parâmetro datePart e Number . Por exemplo, nas expressões a seguir, DATE_BUCKET retorna o valor de saída de , pois a saída é calculada com base em buckets de 2020-04-13 00:00:00.0000000uma semana a partir da hora de origem padrão de 1900-01-01 00:00:00.000. O valor 2020-04-13 00:00:00.0000000 é de 6.276 semanas a partir do valor de origem de 1900-01-01 00:00:00.000.

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

SELECT DATE_BUCKET(WEEK, 1, @date);

Para todas as expressões a seguir, o mesmo valor de saída de é retornado 2020-04-13 00:00:00.0000000 . Isso ocorre porque 2020-04-13 00:00:00.0000000 é 6.276 semanas a partir da data de origem, e 6.276 é divisível por 2, 3, 4 e 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);

A saída para a expressão a seguir é 2020-04-06 00:00:00.0000000, que é de 6.275 semanas a partir da hora 1900-01-01 00:00:00.000de origem padrão.

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

SELECT DATE_BUCKET(WEEK, 5, @date);

A saída para a expressão a seguir é 2020-06-09 00:00:00.0000000, que é de 75 semanas a partir do tempo 2019-01-01 00:00:00de origem especificado.

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

O argumento datepart

dia-do-ano, dia e dia da semana devolvem o mesmo valor. Cada datepart e suas abreviaturas retornam o mesmo valor.

O argumento do número

O argumento number não pode exceder o intervalo de valores int positivos. Nas instruções a seguir, o argumento para número excede o intervalo de int em 1. A instrução a seguir retorna a mensagem de erro: 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);

Se um valor negativo para o número for passado para a DATE_BUCKET função, o seguinte erro será retornado.

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

O argumento da data

DATE_BUCKET Retornar o valor base correspondente ao tipo de dados do argumento date . No exemplo a seguir, um valor de saída com o tipo de dados datetime2 é retornado.

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

O argumento da origem

O tipo de dados dos argumentos origem e data deve ser o mesmo. Se diferentes tipos de dados forem usados, um erro será gerado.

Observações

Utilização DATE_BUCKET nas seguintes cláusulas:

  • GROUP BY
  • HAVING
  • ORDER BY
  • SELECT <list>
  • WHERE

Examples

Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que pode ser descarregado da página inicial de Exemplos e Projetos da Comunidade do Microsoft SQL Server.

A. Calcular DATE_BUCKET com uma largura de balde de 1 a partir da hora de origem

Cada uma dessas instruções é incrementada DATE_BUCKET com uma largura de bucket de 1 a partir do momento de origem:

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

Aqui está o conjunto de resultados.

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. Use expressões como argumentos para os parâmetros de número e data

Esses exemplos usam diferentes tipos de expressões como argumentos para os parâmetros de número e data .

Esses exemplos são criados usando o AdventureWorksDW2025 banco de dados.

Especificar variáveis definidas pelo usuário como número e data

Este exemplo especifica variáveis definidas pelo usuário como argumentos para número e data:

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

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

Aqui está o conjunto de resultados.

1999-12-08 00:00:00.0000000

Especificar uma coluna como data

No exemplo a seguir, calculamos a soma e OrderQuantity a soma de agrupados em intervalos de UnitPrice datas semanais.

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;

Aqui está o conjunto de resultados.

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

Especificar a função do sistema escalar como data

Este exemplo especifica SYSDATETIME a data. O valor exato retornado depende do dia e hora da execução da instrução:

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

Aqui está o conjunto de resultados.

2020-03-02 00:00:00.0000000

Especificar subconsultas escalares e funções escalares como número e data

Este exemplo usa subconsultas escalares, MAX(OrderDate), como argumentos para número e data. (SELECT TOP 1 CustomerKey FROM dbo.DimCustomer WHERE GeographyKey > 100) serve como um argumento artificial para o parâmetro number, para mostrar como selecionar um argumento number de uma lista de valores.

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

Especificar expressões numéricas e funções escalares do sistema como número e data

Este exemplo usa uma expressão numérica ((10/2)) e funções escalares do sistema (SYSDATETIME) como argumentos para número e data.

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

Especificar uma função de janela agregada como número

Este exemplo usa uma função de janela agregada como um argumento para número.

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. Usar um valor de origem não padrão

Este exemplo usa um valor de origem não padrão para gerar os buckets de data.

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

Conteúdo relacionado

  • Last updated on