[SPARK-31474][SQL] Consistency between dayofweek/dow in extract expression and dayofweek function

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala

@@ -2089,8 +2089,7 @@ object DatePart {
     case "MONTH" | "MON" | "MONS" | "MONTHS" => Month(source)
     case "WEEK" | "W" | "WEEKS" => WeekOfYear(source)
     case "DAY" | "D" | "DAYS" => DayOfMonth(source)
-    case "DAYOFWEEK" => DayOfWeek(source)
-    case "DOW" => Subtract(DayOfWeek(source), Literal(1))
+    case "DOW" | "DAYOFWEEK" => DayOfWeek(source)
     case "ISODOW" => Add(WeekDay(source), Literal(1))
     case "DOY" => DayOfYear(source)
     case "HOUR" | "H" | "HOURS" | "HR" | "HRS" => Hour(source)
@@ -2105,38 +2104,42 @@ object DatePart {
   }
 }
 
+// scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(field, source) - Extracts a part of the date/timestamp or interval source.",
   arguments = """
     Arguments:
       * field - selects which part of the source should be extracted.
-               Supported string values of `field` for dates and timestamps are:
-                ["MILLENNIUM", ("MILLENNIA", "MIL", "MILS"),
-                 "CENTURY", ("CENTURIES", "C", "CENT"),
-                 "DECADE", ("DECADES", "DEC", "DECS"),
-                 "YEAR", ("Y", "YEARS", "YR", "YRS"),
-                 "ISOYEAR",
-                 "QUARTER", ("QTR"),
-                 "MONTH", ("MON", "MONS", "MONTHS"),
-                 "WEEK", ("W", "WEEKS"),
-                 "DAY", ("D", "DAYS"),
-                 "DAYOFWEEK",
-                 "DOW",
-                 "ISODOW",
-                 "DOY",
-                 "HOUR", ("H", "HOURS", "HR", "HRS"),
-                 "MINUTE", ("M", "MIN", "MINS", "MINUTES"),
-                 "SECOND", ("S", "SEC", "SECONDS", "SECS"),
-                 "MILLISECONDS", ("MSEC", "MSECS", "MILLISECON", "MSECONDS", "MS"),
-                 "MICROSECONDS", ("USEC", "USECS", "USECONDS", "MICROSECON", "US"),
-                 "EPOCH"]
-                Supported string values of `field` for intervals are:
-                 ["YEAR", ("Y", "YEARS", "YR", "YRS"),
-                  "MONTH", ("MON", "MONS", "MONTHS"),
-                  "DAY", ("D", "DAYS"),
-                  "HOUR", ("H", "HOURS", "HR", "HRS"),
-                  "MINUTE", ("M", "MIN", "MINS", "MINUTES"),
-                  "SECOND", ("S", "SEC", "SECONDS", "SECS")]
+      <ul>
+        <b> Supported string values of `field` for dates and timestamps are: </b>
+          <li> "MILLENNIUM", ("MILLENNIA", "MIL", "MILS") - the conventional numbering of millennia </li>
+          <li> "CENTURY", ("CENTURIES", "C", "CENT") - the conventional numbering of centuries </li>
+          <li> "DECADE", ("DECADES", "DEC", "DECS") - the year field divided by 10 </li>
+          <li> "YEAR", ("Y", "YEARS", "YR", "YRS") - the year field </li>
+          <li> "ISOYEAR" - the ISO 8601 week-numbering year that the datetime falls in </li>
+          <li> "QUARTER", ("QTR") - the quarter (1 - 4) of the year that the datetime falls in </li>
+          <li> "MONTH", ("MON", "MONS", "MONTHS") - the month field </li>
+          <li> "WEEK", ("W", "WEEKS") - the number of the ISO 8601 week-of-week-based-year. A week is considered to start on a Monday and week 1 is the first week with >3 days. In the ISO week-numbering system, it is possible for early-January dates to be part of the 52nd or 53rd week of the previous year, and for late-December dates to be part of the first week of the next year. For example, 2005-01-02 is part of the 53rd week of year 2004, while 2012-12-31 is part of the first week of 2013 </li>
+          <li> "DAY", ("D", "DAYS") - the day of the month field (1 - 31) </li>
+          <li> "DAYOFWEEK",("DOW") - the day of the week for datetime as Sunday(1) to Saturday(7) </li>
+          <li> "ISODOW" - ISO 8601 based day of the week for datetime as Monday(1) to Sunday(7) </li>
+          <li> "DOY" - the day of the year (1 - 365/366) </li>
+          <li> "HOUR", ("H", "HOURS", "HR", "HRS") - The hour field (0 - 23) </li>
+          <li> "MINUTE", ("M", "MIN", "MINS", "MINUTES") - the minutes field (0 - 59) </li>
+          <li> "SECOND", ("S", "SEC", "SECONDS", "SECS") - the seconds field, including fractional parts </li>
+          <li> "MILLISECONDS", ("MSEC", "MSECS", "MILLISECON", "MSECONDS", "MS") - the seconds field, including fractional parts, multiplied by 1000. Note that this includes full seconds </li>
+          <li> "MICROSECONDS", ("USEC", "USECS", "USECONDS", "MICROSECON", "US") - The seconds field, including fractional parts, multiplied by 1000000. Note that this includes full seconds </li>
+          <li> "EPOCH" - the number of seconds with fractional part in microsecond precision since 1970-01-01 00:00:00 local time (can be negative) </li>
+      </ul>
+      <ul>
+        <b> Supported string values of `field` for interval(which consists of `months`, `days`, `microseconds`) are: </b>
+          <li> "YEAR", ("Y", "YEARS", "YR", "YRS") - the total `months` / 12 </li>
+          <li> "MONTH", ("MON", "MONS", "MONTHS") - the total `months` modulo 12 </li>
+          <li> "DAY", ("D", "DAYS") - the `days` part of interval </li>
+          <li> "HOUR", ("H", "HOURS", "HR", "HRS") - how many hours the `microseconds` contains </li>
+          <li> "MINUTE", ("M", "MIN", "MINS", "MINUTES") - how many minutes left after taking hours from `microseconds` </li>
+          <li> "SECOND", ("S", "SEC", "SECONDS", "SECS") - how many second with fractions left after taking hours and minutes from `microseconds` </li>
+      </ul>
       * source - a date/timestamp or interval column from where `field` should be extracted
   """,
   examples = """
@@ -2154,7 +2157,11 @@ object DatePart {
       > SELECT _FUNC_('seconds', interval 5 hours 30 seconds 1 milliseconds 1 microseconds);
        30.001001
   """,
+  note = """
+    The _FUNC_ function is equivalent to the SQL-standard function `extract`
+  """,
   since = "3.0.0")
+// scalastyle:off line.size.limit
 case class DatePart(field: Expression, source: Expression, child: Expression)
   extends RuntimeReplaceable {
 

sql/core/src/test/resources/sql-tests/results/date_part.sql.out

@@ -255,7 +255,7 @@ select date_part('dow', c) from t
 -- !query schema
 struct<date_part('dow', t.`c`):int>
 -- !query output
-5
+6
 
 
 -- !query

sql/core/src/test/resources/sql-tests/results/extract.sql.out

@@ -263,7 +263,7 @@ select extract(dow from c) from t
 -- !query schema
 struct<date_part('dow', t.`c`):int>
 -- !query output
-5
+6
 
 
 -- !query