PostgreSQL: mapping timestamps (date_bin)

date_bin and timestamps in PostgreSQL

Date and time are relevant to pretty much every PostgreSQL application. A new function was added to PostgreSQL 14 to solve a problem which has caused challenges for many users out there over the years: How can we map timestamps to time bins? The function is called date_bin.

What people often do is to round a timestamp to a full hour. That’s commonly done using the date_trunc function. But what if you want to round data in a way that things fit into a 30-minute or a 15-minute grid?

Let’s take a look at an example:

test=# SELECT date_bin('30 minutes', 
                            '2022-03-04 14:34', '1970-01-01 00:00');
        date_bin     
------------------------
 2022-03-04 14:30:00+00
(1 row)

In this case, we want to round for the next half hour: the date_bin function will do the job. The first parameter defines the size of those bins. In our case, it’s 30 minutes. The second parameter is the variable we want to round. What’s interesting is the third variable. Look at it this way: If we round to a precision of 30 min., what value do we want to start at? Is it 30 min after the full hour, or maybe 35min? The third value is therefore like a baseline where we want to start. In our case, we want to round to 30 min intervals relative to a full hour. Therefore the result is 14:30.

The following parameter sets the baseline to 14:31 and the interval should be 20 min. That’s why it comes up with a result of 14:31:

test=# SELECT date_bin('20 minutes', 
                            '2022-03-04 14:49', '1970-01-01 14:31');
        date_bin        
------------------------
 2022-03-04 14:31:00+00
(1 row)

If we use a slightly higher value, PostgreSQL will put it into the next time bin:

test=# SELECT date_bin('20 minutes', 
                            '2022-03-04 14:54', '1970-01-01 14:31');
        date_bin        
------------------------
 2022-03-04 14:51:00+00
(1 row)

date_bin is super useful, because it gives us a lot of flexibility which can’t be achieved using the date_trunc function alone. date_trunc can basically only round to full hours, full days, and so forth.

Finally…

The date_bin function is adaptable and offers many new features on top of what PostgreSQL already has to offer.

Read more about PostgreSQL and time series right now: my blog post about string encoding has further information for you.