feat: Support SQL temporal functions STRFTIME and STRPTIME, and typed literal syntax

[alexander-beedie]

Improves the slightly sparse temporal SQL support with some key functions.

Updates

• Added support for STRFTIME (temporal → string)
• Added support for STRPTIME (string → temporal)
• Added support for temporal "typed literal" syntax for, eg:
  SELECT DATETIME '2077-07-05 10:30:45'
SELECT DATE '2077-07-05'
SELECT TIME '10:30:45'
• New SQL doc entries and test coverage for all of the above.

Also

• Closes DATE() SQL function always returns Date type, even with DateTime strftime format string  #17093 (introducing TIMESTAMP and DATETIME to join the existing DATE).
• Improved our default Time inference patterns to account for fractional seconds.
• Improved SQL "invalid number of argument" error messages by additionally including how many arguments were actually expected.

Examples

STRFTIME:

pl.DataFrame({
    "dtm": [None, datetime(1980, 9, 30, 1, 25, 50)],
    "dt": [date(1978, 7, 5), date(1969, 12, 31)],
    "tm": [time(10, 10, 10), time(22, 33, 55)],
}).sql(
    """
    SELECT
      STRFTIME(dtm,'%m.%d.%Y/%T') AS s_dtm,
      STRFTIME(dt,'%B %d, %Y') AS s_dt,
      STRFTIME(tm,'%S.%M.%H') AS s_tm,
    FROM self
    """
)
# shape: (2, 3)
# ┌─────────────────────┬───────────────────┬──────────┐
# │ s_dtm               ┆ s_dt              ┆ s_tm     │
# │ ---                 ┆ ---               ┆ ---      │
# │ str                 ┆ str               ┆ str      │
# ╞═════════════════════╪═══════════════════╪══════════╡
# │ null                ┆ July 05, 1978     ┆ 10.10.10 │
# │ 09.30.1980/01:25:50 ┆ December 31, 1969 ┆ 55.33.22 │
# └─────────────────────┴───────────────────┴──────────┘

STRPTIME:

pl.DataFrame({
    "s_dtm": [None, "09.30.1980/01:25:50", "07.17.2077/11:30:55"],
    "s_dt": ["July 5, 1978", "December 31, 1969", "April 10, 2020"],
    "s_tm": ["10.10.10", "55.33.22", None],
}).sql(
    """
    SELECT
      STRPTIME(s_dtm,'%m.%d.%Y/%T') AS dtm,
      STRPTIME(s_dt,'%B %d, %Y')::date AS dt,
      STRPTIME(s_tm,'%S.%M.%H')::time AS tm
    FROM self
    """
)
# shape: (3, 3)
# ┌─────────────┬──────────┬─────────────────────┐
# │ s_dt        ┆ s_tm     ┆ dtm                 │
# │ ---         ┆ ---      ┆ ---                 │
# │ str         ┆ str      ┆ datetime[μs]        │
# ╞═════════════╪══════════╪═════════════════════╡
# │ 1969 Oct 30 ┆ 00.30.55 ┆ 1969-10-30 00:30:55 │
# │ 2024 Jul 05 ┆ 12.40.15 ┆ 2024-07-05 12:40:15 │
# │ 2077 Feb 28 ┆ 10.45.00 ┆ 2077-02-28 10:45:00 │
# └─────────────┴──────────┴─────────────────────┘

[codecov]

Codecov Report

Attention: Patch coverage is 92.10526% with 9 lines in your changes missing coverage. Please review.

Project coverage is 80.87%. Comparing base (4d2f928) to head (c166c27).
Report is 3 commits behind head on main.

Files	Patch %	Lines
crates/polars-sql/src/sql_expr.rs	91.07%	5 Missing ⚠️
crates/polars-sql/src/functions.rs	92.45%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #17245      +/-   ##
==========================================
+ Coverage   80.82%   80.87%   +0.04%     
==========================================
  Files        1466     1466              
  Lines      192313   192405      +92     
  Branches     2745     2745              
==========================================
+ Hits       155446   155603     +157     
+ Misses      36364    36299      -65     
  Partials      503      503              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.