Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Time window functions

View as MarkdownEdit this pageReport an issueSet up docs MCP
Experimental feature
Not supported in ClickHouse Cloud

Time window functions return the inclusive lower and exclusive upper bound of the corresponding window. The functions for working with time windows are listed below:

hop

Introduced in: v21.12.0

A hopping time window has a fixed duration (window_interval) and hops by a specified hop interval (hop_interval). If the hop_interval is smaller than the window_interval, hopping windows are overlapping. Thus, records can be assigned to multiple windows.

Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window.

Syntax

hop(time_attr, hop_interval, window_interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • hop_interval — Positive Hop interval. Interval
  • window_interval — Positive Window interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the inclusive lower and exclusive upper bound of the corresponding hopping window. Tuple(DateTime, DateTime)

Examples

Hopping window

SELECT hop(toDateTime('2026-01-02 03:04:05', 'UTC'), INTERVAL '1' DAY, INTERVAL '2' DAY)
('2026-01-01 00:00:00','2026-01-03 00:00:00')

hopEnd

Introduced in: v22.1.0

Returns the exclusive upper bound of the corresponding hopping window.

Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window.

Syntax

hopEnd(time_attr, hop_interval, window_interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • hop_interval — Positive Hop interval. Interval
  • window_interval — Positive Window interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the exclusive upper bound of the corresponding hopping window. DateTime

Examples

Hopping window end

SELECT hopEnd(toDateTime('2026-01-02 03:04:05', 'UTC'), INTERVAL '1' DAY, INTERVAL '2' DAY)
2026-01-03 00:00:00

hopStart

Introduced in: v22.1.0

Returns the inclusive lower bound of the corresponding hopping window.

Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window.

Syntax

hopStart(time_attr, hop_interval, window_interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • hop_interval — Positive Hop interval. Interval
  • window_interval — Positive Window interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the inclusive lower bound of the corresponding hopping window. DateTime

Examples

Hopping window start

SELECT hopStart(toDateTime('2026-01-02 03:04:05', 'UTC'), INTERVAL '1' DAY, INTERVAL '2' DAY)
2026-01-01 00:00:00

tumble

Introduced in: v21.12.0

A tumbling time window assigns records to non-overlapping, continuous windows with a fixed duration (interval).

Syntax

tumble(time_attr, interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • interval — Window interval in Interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the inclusive lower and exclusive upper bound of the corresponding tumbling window. Tuple(DateTime, DateTime)

Examples

Tumbling window

SELECT tumble(toDateTime('2026-01-02 03:04:05', 'UTC'), toIntervalDay('1'))
('2026-01-02 00:00:00','2026-01-03 00:00:00')

tumbleEnd

Introduced in: v22.1.0

Returns the exclusive upper bound of the corresponding tumbling window.

Syntax

tumbleEnd(time_attr, interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • interval — Window interval in Interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the exclusive upper bound of the corresponding tumbling window. DateTime

Examples

Tumbling window end

SELECT tumbleEnd(toDateTime('2026-01-02 03:04:05', 'UTC'), toIntervalDay('1'))
2026-01-03 00:00:00

tumbleStart

Introduced in: v22.1.0

Returns the inclusive lower bound of the corresponding tumbling window.

Syntax

tumbleStart(time_attr, interval[, timezone])

Arguments

  • time_attr — Date and time. DateTime
  • interval — Window interval in Interval. Interval
  • timezone — Optional. Timezone name. String

Returned value

Returns the inclusive lower bound of the corresponding tumbling window. DateTime

Examples

Tumbling window start

SELECT tumbleStart(toDateTime('2026-01-02 03:04:05', 'UTC'), toIntervalDay('1'))
2026-01-02 00:00:00

Related content

Navigation