nodejs-polars
    Preparing search index...

    Interface DatetimeSeries

    DateTime functions for Series

    interface DatetimeSeries {
        day(): pl.Series;
        hour(): pl.Series;
        minute(): pl.Series;
        month(): pl.Series;
        nanosecond(): pl.Series;
        ordinalDay(): pl.Series;
        round(every: string | pl.Expr): pl.Series;
        second(): pl.Series;
        strftime(fmt: string): pl.Series;
        timestamp(): pl.Series;
        truncate(every: string | pl.Expr): pl.Series;
        week(): pl.Series;
        weekday(): pl.Series;
        year(): pl.Series;
    }

    Hierarchy (View Summary)

    Index

    Methods

    day hour minute month nanosecond ordinalDay round second strftime timestamp truncate week weekday year

    Methods

    • Extract day from underlying Date representation. Can be performed on Date and Datetime.

      Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

      Returns pl.Series

      day as pl.UInt32

    • Extract seconds from underlying DateTime representation. Can be performed on Datetime.

      Returns the number of nanoseconds since the whole non-leap second. The range from 1,000,000,000 to 1,999,999,999 represents the leap second.

      Returns pl.Series

      Nanosecond as UInt32

    • Extract ordinal day from underlying Date representation. Can be performed on Date and Datetime.

      Returns the day of year starting from 1. The return value ranges from 1 to 366. (The last day of year differs by years.)

      Returns pl.Series

      Day as UInt32

    • Divide the date/datetime range into buckets.

      • Each date/datetime in the first half of the interval is mapped to the start of its bucket.
      • Each date/datetime in the second half of the interval is mapped to the end of its bucket.
      • Half-way points are mapped to the start of their bucket.

      Ambiguous results are localised using the DST offset of the original timestamp - for example, rounding '2022-11-06 01:20:00 CST' by '1h' results in '2022-11-06 01:00:00 CST', whereas rounding '2022-11-06 01:20:00 CDT' by '1h' results in '2022-11-06 01:00:00 CDT'.

      Parameters

      • every: string | pl.Expr

        Every interval start and period length

      Returns pl.Series

      Expr Expression of data type :class:Date or :class:Datetime.

      The every argument is created with the following small string formatting language:

      • 1ns (1 nanosecond)
      • 1us (1 microsecond)
      • 1ms (1 millisecond)
      • 1s (1 second)
      • 1m (1 minute)
      • 1h (1 hour)
      • 1d (1 calendar day)
      • 1w (1 calendar week)
      • 1mo (1 calendar month)
      • 1q (1 calendar quarter)
      • 1y (1 calendar year)

      By "calendar day", we mean the corresponding time on the next day (which may not be 24 hours, due to daylight savings). Similarly for "calendar week", "calendar month", "calendar quarter", and "calendar year".

      --------
       const df = pl.DataFrame([
         pl.Series("datetime", [
           new Date(Date.parse("2020-01-01T01:30:00.002+00:00")),
           new Date(Date.parse("2020-01-01T02:02:01.030+00:00")),
           new Date(Date.parse("2020-01-01T04:42:20.001+00:00")),
         ])]);
       
       >>> df.select("datetime", pl.col("datetime").dt.round("1h").alias("hr0"));
       shape: (3, 2)
       ┌─────────────────────────┬─────────────────────┐
       │ datetime                ┆ hr0                 │
       │ ---                     ┆ ---                 │
       │ datetime[ms]            ┆ datetime[ms]        │
       ╞═════════════════════════╪═════════════════════╡
       │ 2020-01-01 01:30:00.002 ┆ 2020-01-01 02:00:00 │
       │ 2020-01-01 02:02:01.030 ┆ 2020-01-01 02:00:00 │
       │ 2020-01-01 04:42:20.001 ┆ 2020-01-01 05:00:00 │
       └─────────────────────────┴─────────────────────┘
       >>> df.select("datetime", pl.col("datetime").dt.round("30m").alias("hr30m"));
       shape: (3, 2)
       ┌─────────────────────────┬─────────────────────┐
       │ datetime                ┆ hr30m               │
       │ ---                     ┆ ---                 │
       │ datetime[ms]            ┆ datetime[ms]        │
       ╞═════════════════════════╪═════════════════════╡
       │ 2020-01-01 01:32:00.002 ┆ 2020-01-01 01:30:00 │
       │ 2020-01-01 02:02:01.030 ┆ 2020-01-01 02:00:00 │
       │ 2020-01-01 04:42:20.001 ┆ 2020-01-01 05:00:00 │
       └─────────────────────────┴─────────────────────┘

    • Divide the date/datetime range into buckets. Each date/datetime is mapped to the start of its bucket using the corresponding local datetime. Note that:

      • Weekly buckets start on Monday.
      • All other buckets start on the Unix epoch (1970-01-01).
      • Ambiguous results are localised using the DST offset of the original timestamp - for example, truncating '2022-11-06 01:30:00 CST' by '1h' results in '2022-11-06 01:00:00 CST', whereas truncating '2022-11-06 01:30:00 CDT' by '1h' results in '2022-11-06 01:00:00 CDT'.

      Parameters

      • every: string | pl.Expr

        The size of each bucket.

        The every argument is created with the following string language:

        • 1ns (1 nanosecond)
        • 1us (1 microsecond)
        • 1ms (1 millisecond)
        • 1s (1 second)
        • 1m (1 minute)
        • 1h (1 hour)
        • 1d (1 calendar day)
        • 1w (1 calendar week)
        • 1mo (1 calendar month)
        • 1q (1 calendar quarter)
        • 1y (1 calendar year)

        By "calendar day", we mean the corresponding time on the next day (which may not be 24 hours, due to daylight savings). Similarly for "calendar week", "calendar month", "calendar quarter", and "calendar year".

      Returns pl.Series

      Expr Expression of data type :class:Date or :class:Datetime.

      --------
       const df = pl.DataFrame([
         pl.Series("datetime", [
           new Date(Date.parse("2020-01-01T01:32:00.002+00:00")),
           new Date(Date.parse("2020-01-01T02:02:01.030+00:00")),
           new Date(Date.parse("2020-01-01T04:42:20.001+00:00")),
         ])]);
       
       >>> df.select("datetime", pl.col("datetime").dt.truncate("1h").alias("hr0"));
       shape: (3, 2)
       ┌─────────────────────────┬─────────────────────┐
       │ datetime                ┆ hr0                 │
       │ ---                     ┆ ---                 │
       │ datetime[ms]            ┆ datetime[ms]        │
       ╞═════════════════════════╪═════════════════════╡
       │ 2020-01-01 01:32:00.002 ┆ 2020-01-01 01:00:00 │
       │ 2020-01-01 02:02:01.030 ┆ 2020-01-01 02:00:00 │
       │ 2020-01-01 04:42:20.001 ┆ 2020-01-01 04:00:00 │
       └─────────────────────────┴─────────────────────┘
       >>> df.select("datetime", pl.col("datetime").dt.truncate("30m").alias("hr30m"));
       shape: (3, 2)
       ┌─────────────────────────┬─────────────────────┐
       │ datetime                ┆ hr30m               │
       │ ---                     ┆ ---                 │
       │ datetime[ms]            ┆ datetime[ms]        │
       ╞═════════════════════════╪═════════════════════╡
       │ 2020-01-01 01:32:00.002 ┆ 2020-01-01 01:30:00 │
       │ 2020-01-01 02:02:01.030 ┆ 2020-01-01 02:00:00 │
       │ 2020-01-01 04:42:20.001 ┆ 2020-01-01 04:30:00 │
       └─────────────────────────┴─────────────────────┘

    • Extract the week from the underlying Date representation. Can be performed on Date and Datetime

      Returns the ISO week number starting from 1. The return value ranges from 1 to 53. (The last week of year differs by years.)

      Returns pl.Series

      Week number as UInt32

    Settings

    Member Visibility

    On This Page

    Methods