Date and Time Functions and Operators¶

This page documents date and time functions available in Polars SQL.

Date and Time Functions¶

current_date -> date()¶: Returns the current date.

current_timestamp -> timestamp()¶: Returns the current timestamp.

Interval Functions¶

The supported date_add form accepts these units:

date input: day, month, year
timestamp input: day, hour, minute, second, month, year

date_add(unit, value, timestamp) -> [same as input]()¶

Adds an interval value of type unit to timestamp. Subtraction can be performed by using a negative value.

Verified examples:

SELECT date_add('day', 5, date '2024-01-10'); -- 2024-01-15
SELECT date_add('month', 1, date '2024-01-31'); -- 2024-02-29
SELECT date_add('hour', 2, timestamp '2024-01-01 01:00:00'); -- 2024-01-01 03:00:00.0

dateadd(unit, value, timestamp) -> [same as input]()¶: Alias for date_add().

date_add(date_expr, delta) -> [same as input](): Adds delta days to date_expr.

date_diff(timestamp1, timestamp2) -> integer()¶: Returns timestamp2 - timestamp1 in days.

date_diff(timestamp1, timestamp2, unit) -> integer(): Returns timestamp2 - timestamp1 in the specified unit. Supported units include year, month, day, hour, minute and second.

datedif(timestamp1, timestamp2[, unit]) -> integer()¶: Alias for date_diff().

Extraction Function¶

The extract function supports the following fields:

Field	Description
`YEAR`	`year()`
`MONTH`	`month()`
`DAY`	`day()`
`DAY_OF_MONTH`	`day()`
`HOUR`	`hour()`
`MINUTE`	`minute()`
`SECOND`	`second()`

extract(field FROM x) -> integer()¶: Returns field from x.

Note

This SQL-standard function uses special syntax for specifying the arguments.

Convenience Extraction Functions¶

day(x) -> integer()¶: Returns the day of the month from x.

hour(x) -> integer()¶: Returns the hour of the day from x. The value ranges from 0 to 23.

minute(x) -> integer()¶: Returns the minute of the hour from x.

month(x) -> integer()¶: Returns the month of the year from x.

quarter(x) -> integer()¶: Returns the quarter of the year from x. The value ranges from 1 to 4.

second(x) -> integer()¶: Returns the second of the minute from x.

year(x) -> integer()¶: Returns the year from x.