Add Month_Of_Year Function To OpenSearch

core/src/main/java/org/opensearch/sql/expression/DSL.java

@@ -345,6 +345,10 @@ public static FunctionExpression month(Expression... expressions) {
     return compile(BuiltinFunctionName.MONTH, expressions);
   }
 
+  public static FunctionExpression month_of_year(Expression... expressions) {
+    return compile(BuiltinFunctionName.MONTH_OF_YEAR, expressions);
+  }
+
   public static FunctionExpression monthname(Expression... expressions) {
     return compile(BuiltinFunctionName.MONTHNAME, expressions);
   }

core/src/main/java/org/opensearch/sql/expression/datetime/DateTimeFunction.java

@@ -109,7 +109,8 @@ public void register(BuiltinFunctionRepository repository) {
     repository.register(maketime());
     repository.register(microsecond());
     repository.register(minute());
-    repository.register(month());
+    repository.register(month(BuiltinFunctionName.MONTH));
+    repository.register(month(BuiltinFunctionName.MONTH_OF_YEAR));
     repository.register(monthName());
     repository.register(now());
     repository.register(period_add());
@@ -415,8 +416,8 @@ private DefaultFunctionResolver minute() {
   /**
    * MONTH(STRING/DATE/DATETIME/TIMESTAMP). return the month for date (1-12).
    */
-  private DefaultFunctionResolver month() {
-    return define(BuiltinFunctionName.MONTH.getName(),
+  private DefaultFunctionResolver month(BuiltinFunctionName month) {
+    return define(month.getName(),
         impl(nullMissingHandling(DateTimeFunction::exprMonth), INTEGER, DATE),
         impl(nullMissingHandling(DateTimeFunction::exprMonth), INTEGER, DATETIME),
         impl(nullMissingHandling(DateTimeFunction::exprMonth), INTEGER, TIMESTAMP),

core/src/main/java/org/opensearch/sql/expression/function/BuiltinFunctionName.java

@@ -76,6 +76,7 @@ public enum BuiltinFunctionName {
   MICROSECOND(FunctionName.of("microsecond")),
   MINUTE(FunctionName.of("minute")),
   MONTH(FunctionName.of("month")),
+  MONTH_OF_YEAR(FunctionName.of("month_of_year")),
   MONTHNAME(FunctionName.of("monthname")),
   PERIOD_ADD(FunctionName.of("period_add")),
   PERIOD_DIFF(FunctionName.of("period_diff")),

core/src/test/java/org/opensearch/sql/expression/datetime/DateTimeFunctionTest.java

@@ -8,6 +8,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.when;
 import static org.opensearch.sql.data.model.ExprValueUtils.integerValue;
 import static org.opensearch.sql.data.model.ExprValueUtils.longValue;
@@ -625,6 +626,44 @@ public void month() {
     assertEquals(integerValue(8), eval(expression));
   }
 
+  public void testInvalidDates(String date) throws SemanticCheckException {
+    FunctionExpression expression = DSL.month_of_year(DSL.literal(new ExprDateValue(date)));
+    eval(expression);
+  }
+
+  @Test void monthOfYearInvalidDates() {
+    when(nullRef.type()).thenReturn(DATE);
+    when(missingRef.type()).thenReturn(DATE);
+    assertEquals(nullValue(), eval(DSL.month_of_year(nullRef)));
+    assertEquals(missingValue(), eval(DSL.month_of_year(missingRef)));
+
+    assertThrows(SemanticCheckException.class, () ->  testInvalidDates("2019-01-50"));
+    assertThrows(SemanticCheckException.class, () ->  testInvalidDates("2019-02-29"));
+    assertThrows(SemanticCheckException.class, () ->  testInvalidDates("2019-02-31"));
+    assertThrows(SemanticCheckException.class, () ->  testInvalidDates("2019-13-05"));
+  }
+
+  @Test
+  public void monthOfYearAlternateArgumentSyntaxes() {
+    lenient().when(nullRef.type()).thenReturn(DATE);
+    lenient().when(missingRef.type()).thenReturn(DATE);
+
+    FunctionExpression expression = DSL.month_of_year(DSL.literal(new ExprDateValue("2020-08-07")));
+    assertEquals(INTEGER, expression.type());
+    assertEquals("month_of_year(DATE '2020-08-07')", expression.toString());
+    assertEquals(integerValue(8), eval(expression));
+
+    expression = DSL.month_of_year(DSL.literal("2020-08-07"));
+    assertEquals(INTEGER, expression.type());
+    assertEquals("month_of_year(\"2020-08-07\")", expression.toString());
+    assertEquals(integerValue(8), eval(expression));
+
+    expression = DSL.month_of_year(DSL.literal("2020-08-07 01:02:03"));
+    assertEquals(INTEGER, expression.type());
+    assertEquals("month_of_year(\"2020-08-07 01:02:03\")", expression.toString());
+    assertEquals(integerValue(8), eval(expression));
+  }
+
   @Test
   public void monthName() {
     when(nullRef.type()).thenReturn(DATE);

docs/user/dql/functions.rst

@@ -1699,6 +1699,7 @@ Description
 >>>>>>>>>>>
 
 Usage: month(date) returns the month for date, in the range 1 to 12 for January to December. The dates with value 0 such as '0000-00-00' or '2008-00-00' are invalid.
+The function month_of_year is also provided as an alias
 
 Argument type: STRING/DATE/DATETIME/TIMESTAMP
 
@@ -1715,6 +1716,15 @@ Example::
     +-----------------------------+
 
 
+    os> SELECT MONTH_OF_YEAR(DATE('2020-08-26'))
+    fetched rows / total rows = 1/1
+    +-------------------------------------+
+    | MONTH_OF_YEAR(DATE('2020-08-26'))   |
+    |-------------------------------------|
+    | 8                                   |
+    +-------------------------------------+
+
+
 MONTHNAME
 ---------
 

integ-test/src/test/java/org/opensearch/sql/sql/DateTimeFunctionIT.java

@@ -322,6 +322,25 @@ public void testMonth() throws IOException {
     verifyDataRows(result, rows(9));
   }
 
+  @Test
+  public void testMonthOfYearDateType() throws IOException {
+    JSONObject result = executeQuery("select month_of_year(date('2020-09-16'))");
+    verifySchema(result, schema("month_of_year(date('2020-09-16'))", null, "integer"));
+    verifyDataRows(result, rows(9));
+
+    result = executeQuery("select month_of_year(datetime('2020-09-16 00:00:00'))");
+    verifySchema(result, schema("month_of_year(datetime('2020-09-16 00:00:00'))", null, "integer"));
+    verifyDataRows(result, rows(9));
+
+    result = executeQuery("select month_of_year(timestamp('2020-09-16 00:00:00'))");
+    verifySchema(result, schema("month_of_year(timestamp('2020-09-16 00:00:00'))", null, "integer"));
+    verifyDataRows(result, rows(9));
+
+    result = executeQuery("select month_of_year('2020-09-16')");
+    verifySchema(result, schema("month_of_year('2020-09-16')", null, "integer"));
+    verifyDataRows(result, rows(9));
+  }
+
   @Test
   public void testMonthName() throws IOException {
     JSONObject result = executeQuery("select monthname(date('2020-09-16'))");

sql/src/main/antlr/OpenSearchSQLParser.g4

@@ -395,7 +395,7 @@ trigonometricFunctionName
 dateTimeFunctionName
     : ADDDATE | CONVERT_TZ | DATE | DATE_ADD | DATE_FORMAT | DATE_SUB
     | DATETIME | DAY | DAYNAME | DAYOFMONTH | DAYOFWEEK | DAYOFYEAR | FROM_DAYS | FROM_UNIXTIME
-    | HOUR | MAKEDATE | MAKETIME | MICROSECOND | MINUTE | MONTH | MONTHNAME | PERIOD_ADD
+    | HOUR | MAKEDATE | MAKETIME | MICROSECOND | MINUTE | MONTH | MONTHNAME | MONTH_OF_YEAR | PERIOD_ADD
     | PERIOD_DIFF | QUARTER | SECOND | SUBDATE | SYSDATE | TIME | TIME_TO_SEC
     | TIMESTAMP | TO_DAYS | UNIX_TIMESTAMP | WEEK | YEAR
     ;

sql/src/test/java/org/opensearch/sql/sql/antlr/SQLSyntaxParserTest.java

@@ -191,6 +191,12 @@ public void can_parse_now_like_functions(String name, Boolean hasFsp, Boolean ha
     assertNotNull(parser.parse("SELECT id FROM test WHERE " + String.join(" AND ", calls)));
   }
 
+  @Test
+  public void can_parse_month_of_year_function() {
+    assertNotNull(parser.parse("SELECT month('2022-11-18')"));
+    assertNotNull(parser.parse("SELECT month_of_year('2022-11-18')"));
+  }
+
   @Test
   public void can_parse_multi_match_relevance_function() {
     assertNotNull(parser.parse(