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 │
#> └──────┴───────┴─────┴─────┴─────────────────────┘