DATE_BUCKET (Transact-SQL)

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

Esta función devuelve el valor de fecha y hora correspondiente al inicio de cada cubo de fecha y hora desde la marca de tiempo definida por el parámetro origin o el valor de origen predeterminado de 1900-01-01 00:00:00.000 si no se especifica el parámetro de origen.

Consulte Tipos y funciones de datos de fecha y hora para obtener información general sobre todos los tipos de datos y funciones de fecha y hora de Transact-SQL.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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

Argumentos

datepart

Parte de la fecha que se usa con el parámetro number , por ejemplo, year, month, day, minute, second.

DATE_BUCKET no acepta los equivalentes de variables definidas por el usuario para los argumentos datepart.

datepart	Abreviaturas
day	dd,d
week	WK, WW
month	mm, m
quarter	qq, q
year	Sí, aaaa
hour	hh
minute	mi, n
second	ss,s
millisecond	ms

número

Número entero que decide el ancho del cubo combinado con el argumento datepart. Este argumento representa el ancho de los cubos datepart de la hora de origen. Este argumento no puede ser un valor entero negativo.

date

Expresión que debe ser uno de los siguientes valores:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

Para date, DATE_BUCKET acepta una expresión de columna, expresión o variable definida por el usuario si se resuelven en cualquiera de los tipos de datos mencionados anteriormente.

origin

Expresión opcional que se puede resolver en uno de los valores siguientes:

date
datetime
datetime2
datetimeoffset
smalldatetime
time

El tipo de datos de origen debe coincidir con el tipo de datos del parámetro date .

DATE_BUCKET usa un valor de fecha de origen predeterminado de 1900-01-01 00:00:00.000 es decir, 12:00 a. m. el lunes, 1 de enero de 1900, si no se especifica ningún valor de origen para la función.

Tipos de retorno

El tipo de datos de valores devueltos de este método es dinámico. El tipo devuelto depende del argumento proporcionado para date. Si se proporciona un tipo de datos de entrada válido para la fecha, DATE_BUCKET devuelve el mismo tipo de datos. DATE_BUCKET genera un error si se especifica un literal de cadena para el parámetro date .

Valor devuelto

Descripción de la salida de DATE_BUCKET

DATE_BUCKET devuelve el valor de fecha u hora más reciente, que corresponde a datepart y al parámetro number. Por ejemplo, en las expresiones siguientes, DATE_BUCKET devuelve el valor de salida de 2020-04-13 00:00:00.0000000, ya que la salida se calcula en función de depósitos de una semana a partir de la hora de origen predeterminada de 1900-01-01 00:00:00.000. El valor 2020-04-13 00:00:00.0000000 es 6276 semanas desde el valor de origen 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 las expresiones siguientes, se devuelve el mismo valor de salida de 2020-04-13 00:00:00.0000000 . Esto se debe a que 2020-04-13 00:00:00.0000000 es 6276 semanas a partir de la fecha de origen y 6276 es divisible por 2, 3, 4 y 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);

La salida de la expresión siguiente es 2020-04-06 00:00:00.0000000, que es de 6275 semanas a partir de la hora 1900-01-01 00:00:00.000de origen predeterminada.

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

SELECT DATE_BUCKET(WEEK, 5, @date);

La salida de la expresión siguiente es 2020-06-09 00:00:00.0000000, que es de 75 semanas a partir de la hora 2019-01-01 00:00:00de origen especificada.

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

Argumento datepart

dayofyear, day y weekday devuelven el mismo valor. Cada datepart y sus abreviaturas devuelven el mismo valor.

Argumento number

El argumento number no puede superar el intervalo de valores int positivos. En estas instrucciones, el argumento para number supera el intervalo de int en uno. La siguiente instrucción devuelve el mensaje de error: 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);

Si se pasa un valor negativo para number a la DATE_BUCKET función , se devuelve el siguiente error.

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

Argumento date

DATE_BUCKET devuelve el valor base correspondiente al tipo de datos del argumento date . En el ejemplo siguiente, se devuelve un valor de salida con el tipo de datos datetime2.

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

Argumento origin

El tipo de datos de los argumentos origin y date de debe ser el mismo. Si se usan distintos tipos de datos, se genera un error.

Observaciones

Use DATE_BUCKET en las cláusulas siguientes:

GROUP BY
HAVING
ORDER BY
SELECT <list>
WHERE

Ejemplos

Los ejemplos de código de este artículo usan la base de datos de ejemplo de AdventureWorks2025 o AdventureWorksDW2025, que puede descargar de la página principal de Ejemplos de Microsoft SQL Server y proyectos de comunidad.

A. Cálculo de DATE_BUCKET con un ancho de cubo de 1 a partir de la hora de origen

Cada una de estas instrucciones incrementa DATE_BUCKET con un ancho de cubo de 1 a partir de la hora de origen:

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

Este es el 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. Uso de expresiones como argumentos para los parámetros "number" y "date"

En los ejemplos siguientes se usan otros tipos de expresiones como argumentos para los parámetros number y date.

Estos ejemplos se compilan con la base de datos AdventureWorksDW2025.

Especificación de variables definidas por el usuario como número y fecha

En este ejemplo se especifican variables definidas por el usuario como argumentos para number y date:

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

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

Este es el conjunto de resultados.

1999-12-08 00:00:00.0000000

Especificación de una columna como fecha

En el ejemplo siguiente, calculamos la suma de OrderQuantity y la suma de UnitPrice los cubos de fechas semanales agrupados.

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;

Este es el 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

Especificación de la función de sistema escalar como fecha

En este ejemplo se especifica SYSDATETIME para date. El valor devuelto exacto depende del día y la hora de ejecución de la instrucción:

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

Este es el conjunto de resultados.

2020-03-02 00:00:00.0000000

Especificación de subconsultas y funciones escalares como número y fecha

En este ejemplo se usan subconsultas escalares, MAX(OrderDate), como argumentos para number y date. (SELECT TOP 1 CustomerKey FROM dbo.DimCustomer WHERE GeographyKey > 100) actúa como argumento artificial para el parámetro "number", para mostrar cómo se selecciona un argumento number de una lista de valores.

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

Especificación de expresiones numéricas y funciones del sistema escalares como número y fecha

En este ejemplo se usa una expresión numérica ((10/2)) y funciones del sistema escalares (SYSDATETIME) como argumentos para number y date.

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

Especificación de una función de ventana agregada como número

En este ejemplo se usa una función de ventana agregada como argumento para number.

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. Uso de un valor de origen no predeterminado

En este ejemplo se usa un valor de origen no predeterminado para generar los cubos de fecha.

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-05

Compartir a través de

DATE_BUCKET (Transact-SQL)

Sintaxis

Argumentos

datepart

número

date

origin

Tipos de retorno

Valor devuelto

Descripción de la salida de DATE_BUCKET

Argumento datepart

Argumento number

Argumento date

Argumento origin

Observaciones

Ejemplos

A. Cálculo de DATE_BUCKET con un ancho de cubo de 1 a partir de la hora de origen

B. Uso de expresiones como argumentos para los parámetros "number" y "date"

Especificación de variables definidas por el usuario como número y fecha

Especificación de una columna como fecha

Especificación de la función de sistema escalar como fecha

Especificación de subconsultas y funciones escalares como número y fecha

Especificación de expresiones numéricas y funciones del sistema escalares como número y fecha

Especificación de una función de ventana agregada como número

C. Uso de un valor de origen no predeterminado

Contenido relacionado

Comentarios

Recursos adicionales