SQL: Expose WEEK function and document datetime functions (elastic/x-pack-elasticsearch#3680)

Adds documentation for all of the date time functions using the new
cli-like format extracted from the csv spec. In the process of doing
this I noticed that the `WEEK` function isn't exposed as a function.
This exposes it for consistency.

Relates to elastic/x-pack-elasticsearch#2898

Original commit: elastic/x-pack-elasticsearch@0459b24cb9

docs/en/sql/functions/index.asciidoc

@@ -251,7 +251,7 @@ include-tagged::{sql-specs}/math.sql-spec[sinh]
 include-tagged::{sql-specs}/math.sql-spec[cosh]
 --------------------------------------------------
 
-
+[[sql-functions-datetime]]
 === Date and Time Functions
 
 * Extract the year from a date (`YEAR`)
@@ -261,6 +261,72 @@ include-tagged::{sql-specs}/math.sql-spec[cosh]
 include-tagged::{sql-specs}/datetime.csv-spec[year]
 --------------------------------------------------
 
+* Extract the month of the year from a date (`MONTH_OF_YEAR` or `MONTH`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[monthOfYear]
+--------------------------------------------------
+
+* Extract the week of the year from a date (`WEEK_OF_YEAR` or `WEEK`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[weekOfYear]
+--------------------------------------------------
+
+* Extract the day of the year from a date (`DAY_OF_YEAR` or `DOY`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[dayOfYear]
+--------------------------------------------------
+
+* Extract the day of the month from a date (`DAY_OF_MONTH`, `DOM`, or `DAY`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[dayOfMonth]
+--------------------------------------------------
+
+* Extract the day of the week from a date (`DAY_OF_WEEK` or `DOW`).
+Monday is `1`, Tuesday is `2`, etc.
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[dayOfWeek]
+--------------------------------------------------
+
+* Extract the hour of the day from a date (`HOUR_OF_DAY` or `HOUR`).
+Monday is `1`, Tuesday is `2`, etc.
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[hourOfDay]
+--------------------------------------------------
+
+* Extract the minute of the day from a date (`MINUTE_OF_DAY`).
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[minuteOfDay]
+--------------------------------------------------
+
+* Extract the minute of the hour from a date (`MINUTE_OF_HOUR`, `MINUTE`).
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[minuteOfHour]
+--------------------------------------------------
+
+* Extract the second of the minute from a date (`SECOND_OF_MINUTE`, `SECOND`).
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/datetime.csv-spec[secondOfMinute]
+--------------------------------------------------
+
+
 // aggregate
 
 // geospatial

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/FunctionRegistry.java

@@ -34,6 +34,7 @@ import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.MinuteOfD
 import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.MinuteOfHour;
 import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.MonthOfYear;
 import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.SecondOfMinute;
+import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.WeekOfYear;
 import org.elasticsearch.xpack.sql.expression.function.scalar.datetime.Year;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.ACos;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.ASin;
@@ -109,6 +110,7 @@ public class FunctionRegistry {
             def(SecondOfMinute.class, SecondOfMinute::new, "SECOND"),
             def(MonthOfYear.class, MonthOfYear::new, "MONTH"),
             def(Year.class, Year::new),
+            def(WeekOfYear.class, WeekOfYear::new, "WEEK"),
             // Math
             def(Abs.class, Abs::new),
             def(ACos.class, ACos::new),

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/DayOfMonth.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the day of the month from a datetime.
+ */
 public class DayOfMonth extends DateTimeFunction {
     public DayOfMonth(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/DayOfWeek.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the day of the week from a datetime. 1 is Monday, 2 is Tuesday, etc.
+ */
 public class DayOfWeek extends DateTimeFunction {
     public DayOfWeek(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/DayOfYear.java

@@ -14,6 +14,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the day of the year from a datetime.
+ */
 public class DayOfYear extends DateTimeFunction {
     public DayOfYear(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/Extract.java

@@ -6,7 +6,6 @@
 package org.elasticsearch.xpack.sql.expression.function.scalar.datetime;
 
 import org.elasticsearch.xpack.sql.expression.Expression;
-import org.elasticsearch.xpack.sql.session.SqlSession;
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.joda.time.DateTimeZone;
 
@@ -27,7 +26,7 @@ public enum Extract {
     WEEK {
         @Override
         public DateTimeFunction toFunction(Location source, Expression argument, DateTimeZone timeZone) {
-            return new WeekOfWeekYear(source, argument, timeZone);
+            return new WeekOfYear(source, argument, timeZone);
         }
     },
     DAY {

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/HourOfDay.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the hour of the day from a datetime.
+ */
 public class HourOfDay extends DateTimeFunction {
     public HourOfDay(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/MinuteOfDay.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the minute of the day from a datetime.
+ */
 public class MinuteOfDay extends DateTimeFunction {
 
     public MinuteOfDay(Location location, Expression field, DateTimeZone timeZone) {

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/MinuteOfHour.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Exract the minute of the hour from a datetime.
+ */
 public class MinuteOfHour extends DateTimeFunction {
     public MinuteOfHour(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/MonthOfYear.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the month of the year from a datetime.
+ */
 public class MonthOfYear extends DateTimeFunction {
     public MonthOfYear(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/SecondOfMinute.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the second of the minute from a datetime.
+ */
 public class SecondOfMinute extends DateTimeFunction {
     public SecondOfMinute(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/WeekOfYear.java

@@ -13,19 +13,22 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
-public class WeekOfWeekYear extends DateTimeFunction {
+/**
-    public WeekOfWeekYear(Location location, Expression field, DateTimeZone timeZone) {
+ * Extract the week of the year from a datetime.
+ */
+public class WeekOfYear extends DateTimeFunction {
+    public WeekOfYear(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);
     }
 
     @Override
     protected NodeCtor2<Expression, DateTimeZone, DateTimeFunction> ctorForInfo() {
-        return WeekOfWeekYear::new;
+        return WeekOfYear::new;
     }
 
     @Override
-    protected WeekOfWeekYear replaceChild(Expression newChild) {
+    protected WeekOfYear replaceChild(Expression newChild) {
-        return new WeekOfWeekYear(location(), newChild, timeZone());
+        return new WeekOfYear(location(), newChild, timeZone());
     }
 
     @Override

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/datetime/Year.java

@@ -13,6 +13,9 @@ import org.joda.time.DateTimeZone;
 
 import java.time.temporal.ChronoField;
 
+/**
+ * Extract the year from a datetime.
+ */
 public class Year extends DateTimeHistogramFunction {
     public Year(Location location, Expression field, DateTimeZone timeZone) {
         super(location, field, timeZone);

qa/sql/src/main/resources/command.csv-spec

@@ -42,6 +42,8 @@ SECOND          |SCALAR
 MONTH_OF_YEAR   |SCALAR
 MONTH           |SCALAR
 YEAR            |SCALAR
+WEEK_OF_YEAR    |SCALAR
+WEEK            |SCALAR
 ABS             |SCALAR
 ACOS            |SCALAR
 ASIN            |SCALAR
@@ -94,7 +96,7 @@ AVG             |AGGREGATE
 ABS             |SCALAR
 ;
 
-showFunctions
+showFunctionsWithLeadingPattern
 SHOW FUNCTIONS '%DAY%';
 
     name:s      |    type:s

qa/sql/src/main/resources/datetime.csv-spec

@@ -166,9 +166,110 @@ d:i                  | c:l                  | s:i
 
 constantYear
 // tag::year
-SELECT YEAR(CAST('2018-01-19T10:23:27Z' AS TIMESTAMP)) as year;
+SELECT YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS year;
+
      year
 ---------------
 2018
 // end::year
 ;
+
+constantMonthOfYear
+// tag::monthOfYear
+SELECT MONTH_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS month;
+
+     month
+---------------
+2
+// end::monthOfYear
+;
+
+constantWeekOfYear
+// tag::weekOfYear
+SELECT WEEK_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS week;
+
+     week
+---------------
+8
+// end::weekOfYear
+;
+
+constantDayOfYear
+// tag::dayOfYear
+SELECT DAY_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day;
+
+      day
+---------------
+50
+// end::dayOfYear
+;
+
+extractDayOfYear
+// tag::extractDayOfYear
+SELECT EXTRACT(DAY_OF_YEAR FROM CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day;
+
+      day
+---------------
+50
+// end::extractDayOfYear
+;
+
+constantDayOfMonth
+// tag::dayOfMonth
+SELECT DAY_OF_MONTH(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day;
+
+      day
+---------------
+19
+// end::dayOfMonth
+;
+
+constantDayOfWeek
+// tag::dayOfWeek
+SELECT DAY_OF_WEEK(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day;
+
+      day
+---------------
+1
+// end::dayOfWeek
+;
+
+constantHourOfDay
+// tag::hourOfDay
+SELECT HOUR_OF_DAY(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS hour;
+
+     hour
+---------------
+10
+// end::hourOfDay
+;
+
+constantMinuteOfDay
+// tag::minuteOfDay
+SELECT MINUTE_OF_DAY(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS minute;
+
+    minute
+---------------
+623
+// end::minuteOfDay
+;
+
+constantMinuteOfHour
+// tag::minuteOfHour
+SELECT MINUTE_OF_HOUR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS minute;
+
+    minute
+---------------
+23
+// end::minuteOfHour
+;
+
+constantSecondOfMinute
+// tag::secondOfMinute
+SELECT SECOND_OF_MINUTE(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS second;
+
+    second
+---------------
+27
+// end::secondOfMinute
+;