---
title: Time Window Functions reference
meta:
    description: Functions for time windows.
headingMaxLevels: 2
---

# Time Window functions

Time window functions define and return the inclusive lower and exclusive upper bounds of specific time-based windows.

## tumble

A tumbling window divides a time series into fixed-size, non-overlapping, and contiguous time segments. Each record belongs to exactly one window.

### Syntax

```sql
tumble(time_attr, interval [, timezone])
```

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `interval`: The fixed duration of each tumbling window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

A tuple containing the start (inclusive) and end (exclusive) timestamps of the tumbling window. [Tuple](../data-types/tuple)([DateTime](../data-types/datetime), [DateTime](../data-types/datetime)).

### Example

```sql
SELECT tumble(now(), toIntervalDay('1'))
```

Result:

```text
┌─tumble(now(), toIntervalDay('1'))─────────────┐
│ ('2024-07-04 00:00:00','2024-07-05 00:00:00') │
└───────────────────────────────────────────────┘
```

## tumbleStart

Retrieves the starting timestamp (inclusive lower bound) of the tumbling window for a given time attribute and interval.

### Syntax

```sql
tumbleStart(time_attr, interval [, timezone])
```

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `interval`: The fixed duration of each tumbling window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

The inclusive start timestamp of the tumbling window. [DateTime](../data-types/datetime).

### Example

```sql
SELECT tumbleStart(now(), toIntervalDay('1'))
```

Result:

```result
┌─tumbleStart(now(), toIntervalDay('1'))─┐
│                    2024-07-04 00:00:00 │
└────────────────────────────────────────┘
```

## tumbleEnd

Retrieves the ending timestamp (exclusive upper bound) of the tumbling window for a given time attribute and interval.

### Syntax

```sql
tumbleEnd(time_attr, interval [, timezone])
```

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `interval`: The fixed duration of each tumbling window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

The exclusive end timestamp of the tumbling window. [DateTime](../data-types/datetime).

### Example

```sql
SELECT tumbleEnd(now(), toIntervalDay('1'))
```

Result:

```result
┌─tumbleEnd(now(), toIntervalDay('1'))─┐
│                  2024-07-05 00:00:00 │
└──────────────────────────────────────┘
```

## hop

A hopping window creates potentially overlapping time segments of a fixed duration, moving forward by a specified hop interval. Records can belong to multiple windows.

### Syntax

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

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `hop_interval`: The interval by which the window moves forward. [Interval](../data-types/interval).
- `window_interval`: The total duration of each hopping window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

A tuple containing the start (inclusive) and end (exclusive) timestamps of the hopping window. [Tuple](../data-types/tuple)([DateTime](../data-types/datetime), [DateTime](../data-types/datetime)).

{% callout type="info" %}
Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window when hop function is used without `WINDOW VIEW`.
{% /callout %}

### Example

```sql
SELECT hop(now(), INTERVAL '1' DAY, INTERVAL '2' DAY)
```

Result:

```text
┌─hop(now(), toIntervalDay('1'), toIntervalDay('2'))─┐
│ ('2024-07-03 00:00:00','2024-07-05 00:00:00')      │
└────────────────────────────────────────────────────┘
```

## hopStart

Returns the inclusive starting timestamp of the hopping window for a given time attribute, hop interval, and window duration.

### Syntax

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

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `hop_interval`: The interval by which the window moves forward. [Interval](../data-types/interval).
- `window_interval`: The total duration of each hopping window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

The inclusive start timestamp of the hopping window. [DateTime](../data-types/datetime).

{% callout type="info" %}
Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window when hop function is used without `WINDOW VIEW`.
{% /callout %}

### Example

```sql
SELECT hopStart(now(), INTERVAL '1' DAY, INTERVAL '2' DAY)
```

Result:

```text
┌─hopStart(now(), toIntervalDay('1'), toIntervalDay('2'))─┐
│                                     2024-07-03 00:00:00 │
└─────────────────────────────────────────────────────────┘
```

## hopEnd

Returns the exclusive ending timestamp of the hopping window for a given time attribute, hop interval, and window duration.

### Syntax

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

### Arguments

- `time_attr`: The timestamp or datetime value to categorize into a window. [DateTime](../data-types/datetime).
- `hop_interval`: The interval by which the window moves forward. [Interval](../data-types/interval).
- `window_interval`: The total duration of each hopping window. [Interval](../data-types/interval).
- `timezone`: Optional timezone name to apply to the calculation. [String](../data-types/string).

### Returns

The exclusive end timestamp of the hopping window. [DateTime](../data-types/datetime).

{% callout type="info" %}
Since one record can be assigned to multiple hop windows, the function only returns the bound of the first window when hop function is used without `WINDOW VIEW`.
{% /callout %}

### Example

```sql
SELECT hopEnd(now(), INTERVAL '1' DAY, INTERVAL '2' DAY)
```

Result:

```text
┌─hopEnd(now(), toIntervalDay('1'), toIntervalDay('2'))─┐
│                                   2024-07-05 00:00:00 │
└───────────────────────────────────────────────────────┘
```