Skip to content

timehash — Time bucket

Every example on this page starts here

import polars as pl
import polars_hash as plh

Time buckets, on pl.Expr as .timehash.

A timehash is a short string that names the window of time an instant falls in. Two instants in the same window get the same hash, and a shorter hash names a wider window, so a comparison of prefixes is a coarser bucket.

from_datetime 

from_datetime(precision: int | str | Expr = 10, *, strict: bool = True) -> Expr

Encode an instant to the timehash of the window that holds it.

Datetime and Date columns work directly. Epoch seconds may be Float64 or any integer type. Float32 cannot hold one closely enough to land in the right window. The timestamp must fall between 1970-01-01 and 2098-01-01.

Parameters:

Name Type Description Default
precision int | str | Expr

The number of characters in the hash, from 1 to 32. A higher precision means a shorter window: 10 covers about 4 seconds and 8 about 4 minutes. Past about 18 the hash stops changing for a present-day timestamp, and the extra characters are padding.

 10
strict bool

With False, a timestamp outside the range gives null instead of raising. Precision stays strict either way.

 True

Returns:

Type Description
Expr

Utf8.
Tip

A when/then guard cannot skip an out-of-range timestamp, because polars evaluates both branches over the whole column. Use strict=False instead.

Examples:

>>> from datetime import datetime
>>> df = pl.DataFrame({"t": [datetime(2024, 5, 17, 12, 30, 45)]})
>>> df.select(plh.col("t").timehash.from_datetime()).item()
'bb1c00aaf0'

A lower precision gives a shorter hash and a wider window:

>>> df.select(plh.col("t").timehash.from_datetime(8)).item()
'bb1c00aa'

to_datetime 

to_datetime() -> Expr

Decode a timehash to the midpoint of the window it names.

Returns:

Type Description
Expr

Datetime in microseconds, UTC.
Note

The hash holds an instant and not a wall clock, so the original time zone is gone. Use .dt.convert_time_zone(tz) for another zone. The midpoint is not the instant you encoded. It is the center of the window that instant fell in, so a round trip is exact only up to the precision you used.

Examples:

>>> df = pl.DataFrame({"h": ["bb1c00aaf0"]})
>>> df.select(
...     plh.col("h").timehash.to_datetime().dt.strftime("%Y-%m-%d %H:%M:%S")
... ).item()
'2024-05-17 12:30:46'

neighbors 

neighbors() -> Expr

Give the windows on either side of the one the hash names.

Returns:

Type Description
Expr

A Struct with the Utf8 fields before and after.

Examples:

>>> df = pl.DataFrame({"h": ["bb1c00aaf0"]})
>>> df.select(plh.col("h").timehash.neighbors()).item()
{'before': 'bb1c00aaef', 'after': 'bb1c00aaf1'}