Bring EXTRACT into alignment with PostgreSQL v14

doc/user/content/release-notes.md

@@ -147,6 +147,20 @@ changes that have not yet been documented.
 - Fix a bug where using a `ROWS FROM` clause with an alias in a view would cause
   Materialize to fail to reboot {{% gh 10008 %}}.
 
+- **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,75 @@
+---
+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
+
+TODO: this svg doesn't exist
+{{< 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