Skip to content

Create a Datetime expression

Source code

Description

Create a Datetime expression

Usage

pl$datetime(
  year,
  month,
  day,
  hour = NULL,
  minute = NULL,
  second = NULL,
  microsecond = NULL,
  ...,
  time_unit = "us",
  time_zone = NULL,
  ambiguous = "raise"
)

Arguments

year An Expr or something coercible to an Expr, that must return an integer. Strings are parsed as column names. Floats are cast to integers.
month An Expr or something coercible to an Expr, that must return an integer between 1 and 12. Strings are parsed as column names. Floats are cast to integers.
day An Expr or something coercible to an Expr, that must return an integer between 1 and 31. Strings are parsed as column names. Floats are cast to integers.
hour An Expr or something coercible to an Expr, that must return an integer between 0 and 23. Strings are parsed as column names. Floats are cast to integers.
minute An Expr or something coercible to an Expr, that must return an integer between 0 and 59. Strings are parsed as column names. Floats are cast to integers.
second An Expr or something coercible to an Expr, that must return an integer between 0 and 59. Strings are parsed as column names. Floats are cast to integers.
microsecond An Expr or something coercible to an Expr, that must return an integer between 0 and 999,999. Strings are parsed as column names. Floats are cast to integers.
Not used.
time_unit Unit of time. One of “ms”, “us” (default) or “ns”.
time_zone Time zone string, as defined in OlsonNames(). Setting timezone = “\*“ will match any timezone, which can be useful to select all Datetime columns containing a timezone.
ambiguous Determine how to deal with ambiguous datetimes:
  • “raise” (default): throw an error
  • “earliest”: use the earliest datetime
  • “latest”: use the latest datetime
  • “null”: return a null value

Value

An Expr of type Datetime

See Also

  • pl$date()
  • pl$time()

Examples

library("polars")

df = pl$DataFrame(
  year = 2019:2021,
  month = 9:11,
  day = 10:12,
  min = 55:57
)

df$with_columns(
  dt_from_cols = pl$datetime("year", "month", "day", minute = "min"),
  dt_from_lit = pl$datetime(2020, 3, 5, hour = 20:22),
  dt_from_mix = pl$datetime("year", 3, 5, second = 1)
)
#> shape: (3, 7)
#> ┌──────┬───────┬─────┬─────┬─────────────────────┬─────────────────────┬─────────────────────┐
#> │ year ┆ month ┆ day ┆ min ┆ dt_from_cols        ┆ dt_from_lit         ┆ dt_from_mix         │
#> │ ---  ┆ ---   ┆ --- ┆ --- ┆ ---                 ┆ ---                 ┆ ---                 │
#> │ i32  ┆ i32   ┆ i32 ┆ i32 ┆ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        │
#> ╞══════╪═══════╪═════╪═════╪═════════════════════╪═════════════════════╪═════════════════════╡
#> │ 2019 ┆ 9     ┆ 10  ┆ 55  ┆ 2019-09-10 00:55:00 ┆ 2020-03-05 20:00:00 ┆ 2019-03-05 00:00:01 │
#> │ 2020 ┆ 10    ┆ 11  ┆ 56  ┆ 2020-10-11 00:56:00 ┆ 2020-03-05 21:00:00 ┆ 2020-03-05 00:00:01 │
#> │ 2021 ┆ 11    ┆ 12  ┆ 57  ┆ 2021-11-12 00:57:00 ┆ 2020-03-05 22:00:00 ┆ 2021-03-05 00:00:01 │
#> └──────┴───────┴─────┴─────┴─────────────────────┴─────────────────────┴─────────────────────┘
# floats are coerced to integers
df$with_columns(
  dt_floats = pl$datetime(2018.8, 5.3, 1, second = 2.1)
)
#> shape: (3, 5)
#> ┌──────┬───────┬─────┬─────┬─────────────────────┐
#> │ year ┆ month ┆ day ┆ min ┆ dt_floats           │
#> │ ---  ┆ ---   ┆ --- ┆ --- ┆ ---                 │
#> │ i32  ┆ i32   ┆ i32 ┆ i32 ┆ datetime[μs]        │
#> ╞══════╪═══════╪═════╪═════╪═════════════════════╡
#> │ 2019 ┆ 9     ┆ 10  ┆ 55  ┆ 2018-05-01 00:00:02 │
#> │ 2020 ┆ 10    ┆ 11  ┆ 56  ┆ 2018-05-01 00:00:02 │
#> │ 2021 ┆ 11    ┆ 12  ┆ 57  ┆ 2018-05-01 00:00:02 │
#> └──────┴───────┴─────┴─────┴─────────────────────┘
# if datetime can't be constructed, it returns null
df$with_columns(
  dt_floats = pl$datetime(pl$lit("abc"), -2, 1)
)
#> shape: (3, 5)
#> ┌──────┬───────┬─────┬─────┬──────────────┐
#> │ year ┆ month ┆ day ┆ min ┆ dt_floats    │
#> │ ---  ┆ ---   ┆ --- ┆ --- ┆ ---          │
#> │ i32  ┆ i32   ┆ i32 ┆ i32 ┆ datetime[μs] │
#> ╞══════╪═══════╪═════╪═════╪══════════════╡
#> │ 2019 ┆ 9     ┆ 10  ┆ 55  ┆ null         │
#> │ 2020 ┆ 10    ┆ 11  ┆ 56  ┆ null         │
#> │ 2021 ┆ 11    ┆ 12  ┆ 57  ┆ null         │
#> └──────┴───────┴─────┴─────┴──────────────┘
# can control the time_unit
df$with_columns(
  dt_from_cols = pl$datetime("year", "month", "day", minute = "min", time_unit = "ms")
)
#> shape: (3, 5)
#> ┌──────┬───────┬─────┬─────┬─────────────────────┐
#> │ year ┆ month ┆ day ┆ min ┆ dt_from_cols        │
#> │ ---  ┆ ---   ┆ --- ┆ --- ┆ ---                 │
#> │ i32  ┆ i32   ┆ i32 ┆ i32 ┆ datetime[ms]        │
#> ╞══════╪═══════╪═════╪═════╪═════════════════════╡
#> │ 2019 ┆ 9     ┆ 10  ┆ 55  ┆ 2019-09-10 00:55:00 │
#> │ 2020 ┆ 10    ┆ 11  ┆ 56  ┆ 2020-10-11 00:56:00 │
#> │ 2021 ┆ 11    ┆ 12  ┆ 57  ┆ 2021-11-12 00:57:00 │
#> └──────┴───────┴─────┴─────┴─────────────────────┘