Bring EXTRACT into alignment with PostgreSQL v14

doc/user/content/release-notes.md

@@ -145,6 +145,20 @@ changes that have not yet been documented.
     * Infer the name `case` for `CASE` expressions unless column name inference
       on the `ELSE` expression produces a preferred name.
 
+- **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,74 @@
+---
+title: "date_part Function"
+description: "Returns a specified time component from a time-based value"
+menu:
+  main:
+    parent: 'sql-functions'
+---
+
+`date_part` is modeled on the traditional Ingres equivalent to the SQL-standard 
+function [`EXTRACT`](../extract). For 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')
+AS sec_extr;
+```
+```nofmt
+ sec_extr
+----------
+     5.06
+```
+
+### Extract century from date
+
+```sql
+SELECT date_part('CENTURIES', DATE '2006-01-02')
+AS sec_extr;
+```
+```nofmt
+ sec_extr
+----------
+      21
+```

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

@@ -8,13 +8,15 @@ menu:
 
 `EXTRACT` returns some time component from a time-based value, such as the year from a Timestamp.
 
+See [`date_part`](../date-part) for the traditional Ingres equivalent function.
+
 ## Signatures
 
 {{< 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,7 +44,7 @@ decade  |  `DEC`, `DECS`, `DECADE`, `DECADES`
 
 ### Return value
 
-`EXTRACT` returns a [`float`](../../types/float) value.
+`EXTRACT` returns a [`numeric`](../../types/numeric) value.
 
 ## Examples
 

doc/user/data/sql_funcs.yml

@@ -403,10 +403,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/sql-grammar/sql-grammar.bnf

@@ -345,6 +345,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 ::=