Bring EXTRACT into alignment with PostgreSQL v14 (#10027)

Bring EXTRACT into alignment with PostgreSQL v14

Before this commit, EXTRACT was treated as an alias to date_part with slightly
different syntax. Both of these functions returned a float data type. PostgreSQL
v14 updated EXTRACT to return a numeric data type, which makes it compliant with
the SQL standard. This commit updates the EXTRACT function so that it return a
numeric data type so that it matches PostgreSQL. date_part still returns a float.

Additionally PostgreSQL v14 implemented EXTRACT explicitly for the DATE data
type. Previously DATEs were casted to TIMESTAMPs before extracting fields from
them. This commit also explicitly implements EXTRACT for DATE types, so they
aren't cast to a TIMESTAMP first. A consequence of this is that time related
fields (e.g. SECOND) are now rejected when trying to EXTRACT a DATE type.
However, The implementation for date_part still casts DATE types to TIMESTAMP
types. This means that date_part does not reject time related fields for DATE
types. This implementation matches PostgreSQL.

The postgres commit that implements these changes can be found here:
postgres/postgres@a2da77c

This commit also implements extracting EPOCHs from TIME types, which wasn't
previously implemented.

Fixes #9853, #9870, #10027

Author: jkosh44

doc/user/content/release-notes.md

@@ -114,6 +114,20 @@ changes that have not yet been documented.
 - Support the inverse [trigonometric functions](/sql/functions/#trigonometric-func)
   `asin`, `asinh`, `acos`, `acosh`, `atan`, `atanh`.
 
+- **Breaking change.** Return an error when [`extract`](/sql/functions/extract/)
+  is called with a [`date`] value but a time-related field (e.g., `SECOND`).
+
+  Previous versions of Materialize would incorrectly return `0` in these cases.
+  The new behavior matches PostgreSQL.
+
+  [`date_part`](/sql/functions/date-part/) still returns a `0` in these cases,
+  which matches the PostgreSQL behavior.
+
+- **Breaking change.** Change the return type of [`extract`](/sql/functions/extract/)
+  from [`float`](/sql/types/float/) to [`numeric`](/sql/types/numeric/).
+
+  This new behavior matches PostgreSQL v14.
+
 {{< comment >}}
 Only add new release notes above this line.
 

doc/user/content/sql/functions/date-part.md

@@ -0,0 +1,72 @@
+---
+title: "date_part Function"
+description: "Returns a specified time component from a time-based value"
+menu:
+  main:
+    parent: 'sql-functions'
+---
+
+`date_part` returns some time component from a time-based value, such as the year from a Timestamp.
+It is mostly functionally equivalent to the function [`EXTRACT`](../extract), except to maintain
+PostgreSQL compatibility, `date_part` returns values of type [`float`](../../types/float). This can
+result in a loss of precision in certain uses. Using [`EXTRACT`](../extract) is recommended instead.
+
+## Signatures
+
+{{< diagram "func-date-part.svg" >}}
+
+Parameter | Type                                                                                                                                                          | Description
+----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------
+_val_ | [`time`](../../types/time), [`timestamp`](../../types/timestamp), [`timestamp with time zone`](../../types/timestamptz), [`interval`](../../types/interval), [`date`](../../types/date) | The value from which you want to extract a component. vals of type [`date`](../../types/date) are first cast to type [`timestamp`](../../types/timestamp).
+
+### Arguments
+
+`date_part` supports multiple synonyms for most time periods.
+
+Time period | Synonyms
+------------|---------
+epoch | `EPOCH`
+millennium   | `MIL`, `MILLENNIUM`, `MILLENNIA`
+century | `C`, `CENT`, `CENTURY`, `CENTURIES`
+decade  |  `DEC`, `DECS`, `DECADE`, `DECADES`
+year | `Y`, `YEAR`, `YEARS`, `YR`, `YRS`
+quarter  | `QTR`, `QUARTER`
+month | `MON`, `MONS`, `MONTH`, `MONTHS`
+week | `W`, `WEEK`, `WEEKS`
+day  | `D`, `DAY`, `DAYS`
+hour   |`H`, `HR`, `HRS`, `HOUR`, `HOURS`
+minute | `M`, `MIN`, `MINS`, `MINUTE`, `MINUTES`
+second | `S`, `SEC`, `SECS`, `SECOND`, `SECONDS`
+microsecond  | `US`, `USEC`, `USECS`, `USECONDS`, `MICROSECOND`, `MICROSECONDS`
+millisecond | `MS`, `MSEC`, `MSECS`, `MSECONDS`, `MILLISECOND`, `MILLISECONDS`
+day of week |`DOW`
+ISO day of week | `ISODOW`
+day of year | `DOY`
+
+### Return value
+
+`date_part` returns a [`float`](../../types/float) value.
+
+## Examples
+
+### Extract second from timestamptz
+
+```sql
+SELECT date_part('S', TIMESTAMP '2006-01-02 15:04:05.06');
+```
+```nofmt
+ date_part
+-----------
+      5.06
+```
+
+### Extract century from date
+
+```sql
+SELECT date_part('CENTURIES', DATE '2006-01-02');
+```
+```nofmt
+ date_part
+-----------
+        21
+```

doc/user/content/sql/functions/extract.md

@@ -12,9 +12,9 @@ menu:
 
 {{< diagram "func-extract.svg" >}}
 
-Parameter | Type                                                                                                                                                | Description
-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|------------
-_val_ | [`date`](../../types/date), [`time`](../../types/time), [`timestamp`](../../types/timestamp), [`timestamp with time zone`](../../types/timestamptz) | The value from which you want to extract a component.
+Parameter | Type                                                                                                                                                                                    | Description
+----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------
+_val_ | [`date`](../../types/date), [`time`](../../types/time), [`timestamp`](../../types/timestamp), [`timestamp with time zone`](../../types/timestamptz), [`interval`](../../types/interval) | The value from which you want to extract a component.
 
 ### Arguments
 
@@ -42,30 +42,28 @@ decade  |  `DEC`, `DECS`, `DECADE`, `DECADES`
 
 ### Return value
 
-`EXTRACT` returns a [`float`](../../types/float) value.
+`EXTRACT` returns a [`numeric`](../../types/numeric) value.
 
 ## Examples
 
 ### Extract second from timestamptz
 
 ```sql
-SELECT EXTRACT(S FROM TIMESTAMP '2006-01-02 15:04:05.06')
-AS sec_extr;
+SELECT EXTRACT(S FROM TIMESTAMP '2006-01-02 15:04:05.06');
 ```
 ```nofmt
- sec_extr
-----------
-     5.06
+ extract
+---------
+    5.06
 ```
 
 ### Extract century from date
 
 ```sql
-SELECT EXTRACT(CENTURIES FROM DATE '2006-01-02')
-AS sec_extr;
+SELECT EXTRACT(CENTURIES FROM DATE '2006-01-02');
 ```
 ```nofmt
- sec_extr
-----------
+ extract
+---------
       21
 ```

doc/user/data/sql_funcs.yml

@@ -421,10 +421,14 @@
     description: Largest `time_component` <= `val`
     url: date-trunc
 
-  - signature: EXTRACT(extract_expr) -> float
+  - signature: EXTRACT(extract_expr) -> numeric
     description: Specified time component from value
     url: extract
 
+  - signature: 'date_part(time_component: str, val: timestamp) -> float'
+    description: Specified time component from value
+    url: date-part
+
   - signature: mz_logical_timestamp() -> numeric
     description: 'The logical time at which a query executes. Used for temporal filters and internal debugging.'
     url: now_and_mz_logical_timestamp

doc/user/layouts/partials/sql-grammar/func-date-part.svg

@@ -346,6 +346,8 @@ func_date_trunc ::=
   'date_trunc' '(' "'" ( 'microseconds' | 'milliseconds' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millenium' ) "'" ',' ts_val ')'
 func_extract ::=
   'EXTRACT' '(' ( 'EPOCH' | 'MILLENNIUM' | 'CENTURY' | 'DECADE' | 'YEAR' | 'QUARTER' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' | 'MICROSECOND' | 'MILLISECOND' | 'DOW' | 'ISODOW' | 'DOY' ) 'FROM' val ')'
+func_date_part ::=
+  'date_part' '(' "'" ( 'epoch' | 'millennium' | 'century' | 'decade' | 'year' | 'quarter' | 'month' | 'week' | 'dat' | 'hour' | 'minute' | 'second' | 'microsecond' | 'millisecond' | 'dow' | 'isodow' | 'doy' ) "'" ',' val ')'
 func_length ::=
   'length' '(' str (',' encoding_name)? ')'
 func_substring ::=