nodejs-polars
    Preparing search index...

    Interface DatetimeNamespace

    DateTime functions for expression

    interface DatetimeNamespace {
        convertTimeZone(timeZone: string): pl.Expr;
        day(): pl.Expr;
        hour(): pl.Expr;
        minute(): pl.Expr;
        month(): pl.Expr;
        nanosecond(): pl.Expr;
        ordinalDay(): pl.Expr;
        replaceTimeZone(
            timeZone: string,
            ambiguous?: string | pl.Expr,
            nonExistent?: string,
        ): pl.Expr;
        round(every: string | pl.Expr): pl.Expr;
        second(): pl.Expr;
        strftime(fmt: string): pl.Expr;
        timestamp(): pl.Expr;
        truncate(every: string | pl.Expr): pl.Expr;
        week(): pl.Expr;
        weekday(): pl.Expr;
        year(): pl.Expr;
    }

    Hierarchy (View Summary)

    Index

    Methods

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

    Methods

      Convert to given time zone for an expression of type Datetime.

      Parameters

      • timeZone: string

        Time zone for the Datetime expression.

      Returns pl.Expr

      Expr Expression of data type Datetime with the given time zone.

      --------
      >>> DataFrame([
        Series("london_timezone", [new Date(Date.UTC(2026, 0, 1, 6, 0, 0))],DataType.Datetime("us"),).dt.replaceTimeZone("Europe/London"),
      ]).select([
        pl.col("london_timezone"),
        pl.col("london_timezone").dt.convertTimeZone("Europe/Amsterdam").alias("London_to_Amsterdam"),
      ]);
      shape: (1, 2)
      ┌─────────────────────────────┬────────────────────────────────┐
      │ london_timezone             ┆ London_to_Amsterdam            │
      │ ---                         ┆ ---                            │
      │ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
      ╞═════════════════════════════╪════════════════════════════════╡
      │ 2026-01-01 06:00:00 GMT     ┆ 2026-01-01 07:00:00 CET        │
      └─────────────────────────────┴────────────────────────────────┘

    • 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.Expr

      day as pl.UInt32

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

      Returns the month number starting from 1. The return value ranges from 1 to 12.

      Returns pl.Expr

      Month as 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.Expr

      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.Expr

      Day as UInt32

    • Replace time zone for an expression of type Datetime.

      Parameters

      • timeZone: string

        Time zone for the Datetime expression. Pass null to unset time zone.

      • Optionalambiguous: string | pl.Expr

        Determine how to deal with ambiguous datetimes: - 'raise' (default): raise - 'earliest': use the earliest datetime - 'latest': use the latest datetime - 'null': set to null

      • OptionalnonExistent: string

        Determine how to deal with non-existent datetimes: - 'raise' (default): raise - 'null': set to null

      Returns pl.Expr

       DataFrame([
           Series("london_timezone", [new Date(Date.UTC(2026, 0, 1, 6, 0, 0))],DataType.Datetime("us")).dt.replaceTimeZone("Europe/London")
         ]).select([ pl.col("london_timezone"),
                     pl.col("london_timezone").dt.replaceTimeZone("Europe/Amsterdam").alias("London_to_Amsterdam")]);

       shape: (1, 2)
       ┌─────────────────────────────┬────────────────────────────────┐
       │ london_timezone             ┆ London_to_Amsterdam            │
       │ ---                         ┆ ---                            │
       │ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
       ╞═════════════════════════════╪════════════════════════════════╡
       │ 2026-01-01 06:00:00 GMT     ┆ 2026-01-01 06:00:00 CET        │
       └─────────────────────────────┴────────────────────────────────┘

       You can use `ambiguous` to deal with ambiguous datetimes:

       >>> const dates = [
       ...     "2018-10-28 01:30",
       ...     "2018-10-28 02:00",
       ...     "2018-10-28 02:30",
       ...     "2018-10-28 02:00",
       ... ];

       pl.DataFrame(
        {
            "ts": pl.Series(dates).str.strptime(pl.Datetime),
            "ambiguous": ["earliest", "earliest", "latest", "latest"],
        }).withColumns(
           pl.col("ts").dt.replaceTimeZone( "Europe/Brussels", pl.col("ambiguous")).alias("ts_localized")
         );

       shape: (4, 3)
       ┌─────────────────────┬───────────┬───────────────────────────────┐
       │ ts                  ┆ ambiguous ┆ ts_localized                  │
       │ ---                 ┆ ---       ┆ ---                           │
       │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
       ╞═════════════════════╪═══════════╪═══════════════════════════════╡
       │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
       │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
       │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
       │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │

    • 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.Expr

      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.Expr

      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.Expr

      Week number as UInt32

    Settings

    Member Visibility

    On This Page

    Methods